@typeonce/ritmo 0.6.0 → 0.8.0

package/src/Condition.ts

@@ -45,10 +45,25 @@ type AnyQuery = Query.Query.Any<any>
 /** Access categories a check may declare. */
 export interface CheckAccessInput {
   readonly queries?: Record<string, AnyQuery>
-  readonly resources?: Record<string, System.ResourceRead<Descriptor<"resource", string, any>>>
+  readonly resources?: Record<string, CheckResourceAccess>
   readonly machines?: Record<string, Machine.MachineRead<Machine.StateMachine.Any>>
 }
 
+/** Accepted at the constraint so `ExactCheckAccess` can reject the last two with a message naming the fix. */
+type CheckResourceAccess =
+  | System.ResourceRead<Descriptor<"resource", string, any>>
+  | System.ResourceChanged<Descriptor<"resource", string, any>>
+  | System.ResourceWrite<Descriptor<"resource", string, any>>
+
+/** A check reads committed values and owns no cursor: `changedResource` and `writeResource` slots become a message naming the fix. */
+type CheckResources<Resources> = {
+  readonly [K in keyof Resources]: Resources[K] extends { readonly mode: "changed" }
+    ? "changedResource consumes a per-reader cursor, which a check does not have: use Game.System.readResource here, and changedResource in the gated system"
+    : Resources[K] extends { readonly mode: "write" }
+      ? "a check cannot write resources: use Game.System.readResource"
+      : Resources[K]
+}
+
 type QueryWriteAccess<Q extends AnyQuery> =
   Extract<Q["selection"][keyof Q["selection"]], { readonly mode: "write" }>
 
@@ -72,6 +87,7 @@ export type ExactCheckAccess<Access extends CheckAccessInput> = Access & {
   readonly queries?: Access["queries"] extends Record<string, AnyQuery>
     ? StatelessQueries<Access["queries"]>
     : never
+  readonly resources?: CheckResources<Access["resources"]>
 }
 
 /** What a check's predicate sees: its declared resources, machines, and queries, read-only. */

package/src/Debug.ts

@@ -1,7 +1,7 @@
 /**
  * Opt-in runtime introspection for tools, tests, and coding agents.
  *
- * A runtime made with `debug: true` carries a `debug` handle. Runtimes made
+ * A runtime made with `debug: { hostClock }` carries a `debug` handle. Runtimes made
  * without it have no handle at all, so production code cannot reach into
  * internals by accident and pays nothing for them.
  *
@@ -35,7 +35,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, resources, debug: true })
+ * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } })
  * runtime.debug.nameSchedules({ setup: setupSchedule, update: updateSchedule })
  *
  * const stop = runtime.debug.observe((event) => {
@@ -46,15 +46,16 @@
  * stop()
  * ```
  */
+import type { HostClock } from "./HostClock.ts"
 import type * as Machine from "./Machine.ts"
-import type { ExecutableScheduleDefinition } from "./Schedule.ts"
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "./Schedule.ts"
 import type { Schema } from "./Schema.ts"
 
 /** Version of the description, dump, and trace formats. */
 export const formatVersion = 1 as const
 
 /**
- * The debug handle of a runtime made with `debug: true`.
+ * The debug handle of a runtime made with `debug: { hostClock }`.
  */
 export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
   /**
@@ -64,8 +65,15 @@ export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
    * `onEnter(Game/Flow=Playing)`. Naming again replaces earlier names.
    */
   readonly nameSchedules: (
-    schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>>
+    schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
   ) => void
+  /**
+   * Declares the events the host publishes with `runtime.send`, so
+   * `describe()` counts them as written (`event-never-written`) before the
+   * first send happens. Events actually sent count as well. Declaring again
+   * replaces the list.
+   */
+  readonly declareHostEvents: (events: ReadonlyArray<Schema.EventDescriptor<S>>) => void
   /** The static description of the schema and the named schedules. */
   readonly describe: () => Description
   /** The current world as plain data. */
@@ -75,6 +83,21 @@ export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
    * active only while at least one listener is registered.
    */
   readonly observe: (listener: (event: TraceEvent) => void) => () => void
+  /**
+   * Delivers what the host does to the runtime, until the returned function
+   * is called: each tick's start and end (with the schedule values it runs)
+   * and each `runtime.send`. Unlike `observe`, it turns no tracing on, so a
+   * tool can listen for a whole play session (replay recorders do).
+   */
+  readonly observeHost: (listener: (event: HostEvent<S, Root>) => void) => () => void
+  /**
+   * Reports the last failed tick result if nobody read its `ok`, as a
+   * `failure.ignored` event (to `observe` and `observeHost` listeners), with
+   * `when: "session-end"`. Call it when a session ends; the start of the
+   * next tick checks the same with `when: "next-tick"`. Emits nothing to a
+   * console.
+   */
+  readonly checkIgnoredFailures: () => void
   /** Retention and reader state of every stream that has readers or entries. */
   readonly streams: () => ReadonlyArray<StreamStatus>
   /** Live entity count and, per component, how many entities have it. Cheap enough to sample every frame. */
@@ -93,6 +116,10 @@ export type Storage = "constructed" | "transient" | "plain"
 export interface ComponentDescription {
   readonly name: string
   readonly storage: Storage
+  /** Declared `immutable: true`: queries only read it, `commands.insert` replaces it. */
+  readonly immutable: boolean
+  /** The components it directly requires (`Schema.requires`). */
+  readonly requires: ReadonlyArray<string>
 }
 
 export interface ResourceDescription {
@@ -113,8 +140,22 @@ export interface RelationDescription {
 export interface MachineDescription {
   readonly name: string
   readonly states: ReadonlyArray<Machine.StateValue>
-  /** The committed value, or `undefined` when the runtime does not provide the machine. */
+  /**
+   * The committed value, or `undefined` when the runtime does not provide the
+   * machine, or when it is a sub-state whose parent is in another state.
+   */
   readonly current: Machine.StateValue | undefined
+  /** Whether the runtime was given an initial value for the machine. */
+  readonly provided: boolean
+  /** For a sub-state, where it exists, as `Parent=state`. */
+  readonly within: string | undefined
+}
+
+/** An entity scope and the state changes that despawn it (`Game.EntityScope(name, { despawnOnExit, despawnOnEnter })`). */
+export interface ScopeDescription {
+  readonly name: string
+  /** Triggers as `onExit(Flow=Playing)` / `onEnter(Flow=Menu)`; empty when only `commands.despawnScope` ends it. */
+  readonly despawnOn: ReadonlyArray<string>
 }
 
 export interface ServiceDescription {
@@ -132,6 +173,8 @@ export interface QueryDescription {
   readonly without: ReadonlyArray<string>
   readonly added: ReadonlyArray<string>
   readonly changed: ReadonlyArray<string>
+  /** One entry per `anyOf` filter: the components of its `added` and `changed` members. */
+  readonly anyOf: ReadonlyArray<{ readonly added: ReadonlyArray<string>; readonly changed: ReadonlyArray<string> }>
   /** Relation filters and reads, for example `with ChildOf` or `read Children`. */
   readonly relations: ReadonlyArray<string>
 }
@@ -142,7 +185,8 @@ export interface SystemDescription {
   /** Where the system runs, as `schedule#step`. */
   readonly placements: ReadonlyArray<string>
   readonly queries: ReadonlyArray<QueryDescription>
-  readonly resources: { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
+  /** Resource reads and writes. `changed` lists the reads declared with `changedResource` (also in `reads`). */
+  readonly resources: { readonly reads: ReadonlyArray<string>; readonly changed: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
   readonly events: { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
   readonly machines: {
     readonly reads: ReadonlyArray<string>
@@ -153,7 +197,15 @@ export interface SystemDescription {
   readonly removed: ReadonlyArray<string>
   readonly despawned: boolean
   readonly relationFailures: ReadonlyArray<string>
+  /** Events and resources read with `Game.System.thisTick`, and query slots as `queries.<slot>`. */
+  readonly thisTick: ReadonlyArray<string>
   readonly services: ReadonlyArray<string>
+  /**
+   * The declared command permissions (`Game.System.commands(...)`), by
+   * kind: component names for spawns, inserts, removes and despawns, scope
+   * names for despawnsScope, relation names for relates.
+   */
+  readonly commands: CommandPermissions
   /** Run conditions, rendered, for example `stateChanged(Game/Flow)`. */
   readonly when: ReadonlyArray<string>
   /** Pause conditions, rendered: while one fails the system waits and holds its stream entries. */
@@ -162,6 +214,16 @@ export interface SystemDescription {
   readonly local: boolean
 }
 
+/** Declared command permissions of one system, by kind. Empty lists when it declares none. */
+export interface CommandPermissions {
+  readonly spawns: ReadonlyArray<string>
+  readonly inserts: ReadonlyArray<string>
+  readonly removes: ReadonlyArray<string>
+  readonly despawns: ReadonlyArray<string>
+  readonly despawnsScope: ReadonlyArray<string>
+  readonly relates: ReadonlyArray<string>
+}
+
 export type StepDescription =
   | { readonly kind: "system"; readonly system: string }
   | { readonly kind: "applyDeferred" }
@@ -175,17 +237,34 @@ export interface ScheduleDescription {
 /**
  * A finding about the described schedules. `warning` is almost certainly a
  * bug; `info` is worth a look but can be intentional.
+ *
+ * Most lints read declarations only. Some also use what the runtime has seen
+ * so far: events sent with `runtime.send(...)` count as written,
+ * `relation-failure-never-read` fires for a relation that applied commands
+ * have tried to relate or reorder (which can fail) while no described system
+ * reads its failures, and `requirement-violated` lists commands skipped
+ * because they would have broken a `Schema.requires` requirement, so
+ * describe after the game has run for a while. `scope-trigger-never-applied`
+ * also reads which machines the runtime provides.
  */
 export interface Lint {
   readonly severity: "warning" | "info"
   readonly code:
     | "event-never-read"
+    | "relation-failure-never-read"
     | "event-never-written"
     | "next-state-never-applied"
+    | "resource-changed-never-written"
     | "component-never-read"
     | "read-before-write"
+    | "this-tick-order"
+    | "command-permission-unused"
+    | "requirement-violated"
+    | "scope-trigger-never-applied"
   readonly message: string
   readonly subject: string
+  /** What to change to resolve it (or, for `info`, when it is fine as it is). */
+  readonly fix: string
 }
 
 /** Readers and writers of one component, resource, or event. */
@@ -202,12 +281,15 @@ export interface Description {
   readonly events: ReadonlyArray<{ readonly name: string }>
   readonly relations: ReadonlyArray<RelationDescription>
   readonly machines: ReadonlyArray<MachineDescription>
+  /** Scopes defined through the game, in definition order. */
+  readonly scopes: ReadonlyArray<ScopeDescription>
   readonly services: ReadonlyArray<ServiceDescription>
   readonly schedules: ReadonlyArray<ScheduleDescription>
   readonly systems: ReadonlyArray<SystemDescription>
   /**
    * Readers and writers across the named schedules. Component writers are
-   * systems with a write query slot; command inserts are not static.
+   * systems with a write query slot or a declared `spawns`, `inserts`, or
+   * `removes` permission for it.
    */
   readonly access: {
     readonly components: ReadonlyArray<AccessIndexEntry>
@@ -340,6 +422,32 @@ export type Effect =
   | { readonly kind: "relate"; readonly entity: number; readonly relation: string; readonly target: number }
   | { readonly kind: "unrelate"; readonly entity: number; readonly relation: string }
   | { readonly kind: "relationFailure"; readonly entity: number; readonly relation: string; readonly error: string }
+  /** A command skipped because it would leave `component` without `missing` (`Schema.requires`). */
+  | {
+      readonly kind: "requirementViolated"
+      readonly entity: number
+      readonly command: RequirementViolation["command"]
+      readonly component: string
+      readonly missing: string
+    }
+
+/**
+ * Commands of one system skipped because applying them would have left a
+ * component without one it requires (`Schema.requires`): the
+ * `requirement-violated` lint.
+ */
+export interface RequirementViolation {
+  readonly system: string
+  readonly command: "spawn" | "insert" | "remove"
+  /** The requirer. */
+  readonly component: string
+  /** The required component it would have lacked. */
+  readonly missing: string
+  /** The last entity it happened to. */
+  readonly entity: number
+  /** How many commands were skipped this way. */
+  readonly count: number
+}
 
 export interface AppliedCommand {
   readonly tag: string
@@ -433,8 +541,10 @@ export interface TransitionEvent {
   readonly tick: number
   readonly schedule: string
   readonly machine: string
-  readonly from: Machine.StateValue
-  readonly to: Machine.StateValue
+  /** `undefined` when a sub-state starts existing (its parent entered its state). */
+  readonly from: Machine.StateValue | undefined
+  /** `undefined` when a sub-state stops existing (its parent left its state). */
+  readonly to: Machine.StateValue | undefined
   /**
    * `applied` committed the new value; `unchanged` was a `setIfChanged` to the
    * current value; `failed` stopped in an exit or transition schedule and was
@@ -450,6 +560,45 @@ export interface RestoreEvent {
   readonly ok: boolean
 }
 
+/** What `observeHost` delivers. */
+export type HostEvent<S extends Schema.Any = Schema.Any, Root = unknown> =
+  | {
+      readonly type: "tick.start"
+      /** The schedule values passed to this `tick(...)` (or `tryTick`) call, in order. */
+      readonly schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>
+      readonly frame: number
+    }
+  | {
+      readonly type: "tick.end"
+      readonly schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>
+      readonly frame: number
+      /** `failed`: a system returned `Result.failure`; `defect`: one threw (rethrown after this event). */
+      readonly outcome: "ok" | "failed" | "defect"
+      readonly error?: unknown
+    }
+  | { readonly type: "send"; readonly event: string; readonly value: unknown }
+  | FailureIgnoredEvent
+
+/**
+ * A failed `tick` / `tryTick` result whose `ok` nobody read: the failure
+ * went unnoticed, and the systems after the failing one did not run that
+ * tick. Found at the start of the next tick (`when: "next-tick"`) or by
+ * `checkIgnoredFailures()` (`when: "session-end"`). Debug runtimes only.
+ */
+export interface FailureIgnoredEvent {
+  readonly type: "failure.ignored"
+  /** The frame of the failed tick. */
+  readonly frame: number
+  /** The schedule holding the failing system (the first one for a tick that ran nothing). */
+  readonly schedule: string
+  /** The failing system; `undefined` when `tryTick` ran nothing (missing requirements, order). */
+  readonly system: string | undefined
+  readonly error: unknown
+  /** The systems of the tick that did not run because of the failure, in order. */
+  readonly skipped: ReadonlyArray<string>
+  readonly when: "next-tick" | "session-end"
+}
+
 /** Everything `observe` delivers. */
 export type TraceEvent =
   | FrameEvent
@@ -461,14 +610,21 @@ export type TraceEvent =
   | DeferredEvent
   | TransitionEvent
   | RestoreEvent
+  | FailureIgnoredEvent
 
 /**
- * The `debug` runtime option: `true` attaches a handle.
+ * The `debug` runtime option: `{ hostClock }` attaches a handle, timing
+ * traces with that clock. A value that may be `undefined`
+ * (`import.meta.env.DEV ? { hostClock } : undefined`) attaches it when
+ * present and types `debug` as optional, so code checks it before use.
  */
-export type Option = true
+export interface Option {
+  /** Times trace events (`ms`); see `HostClock`. */
+  readonly hostClock: HostClock
+}
 
 /**
- * The member a runtime made with `debug: true` carries.
+ * The member a runtime made with `debug: { hostClock }` carries.
  */
 export interface Member<S extends Schema.Any, Root> {
   readonly debug: Handle<S, Root>
@@ -476,4 +632,6 @@ export interface Member<S extends Schema.Any, Root> {
 
 /** Resolves the extra runtime member for a `debug` option type. */
 export type MemberFor<Enabled, S extends Schema.Any, Root> =
-  [Enabled] extends [Option] ? Member<S, Root> : {}
+  [Enabled] extends [true] ? Member<S, Root>
+  : [Enabled] extends [false | undefined] ? {}
+  : Partial<Member<S, Root>>

package/src/Decode.ts

@@ -188,7 +188,7 @@ export const struct = <const Fields extends Readonly<Record<string, Codec<any>>>
 /**
  * A stored entity handle for schema root `Root`, optionally with an intent
  * component. Decoding never proves the entity exists; resolve it with
- * `lookup.getHandle(...)` as usual.
+ * `queries.x.getHandle(...)` (through a declared query) as usual.
  */
 export const handle = <
   Root,

package/src/Descriptor.ts

@@ -16,8 +16,9 @@
  * 3. bind one `Game` with `Schema.bind(...)`
  *
  * Reach for this module first whenever you introduce a new component,
- * resource, event, or service to the game. Discrete modes whose transitions
- * matter are state machines (`Game.StateMachine(...)`), not descriptors.
+ * resource, event, or service to the game. A game-wide mode whose transitions
+ * matter is a state machine (`Game.StateMachine(...)`); a state each entity
+ * has on its own is a component (`Descriptor.EntityState(...)`).
  *
  * @module Descriptor
  * @docGroup core
@@ -165,6 +166,44 @@ export interface TransientDescriptor<
   readonly transient: true
 }
 
+/**
+ * Marks a component that is never edited in place: `Game.Query.write(...)`
+ * rejects it, and the only way to change its value is to replace it with
+ * `commands.insert(...)` (applied at `applyDeferred()`, seen by
+ * `Game.Query.changed(...)`).
+ */
+export interface Immutable {
+  readonly immutable: true
+}
+
+/**
+ * Options of the component descriptor constructors (`Component`,
+ * `ConstructedComponent`, `TransientComponent`).
+ */
+export interface ComponentOptions {
+  /**
+   * `true` for data that says what an entity is (a kind, a team, a tile) and
+   * is replaced, never edited: queries can only read it, and
+   * `commands.insert(...)` replaces it. Leave it out for state that systems
+   * update every frame.
+   */
+  readonly immutable?: true
+}
+
+/** The descriptor a component constructor returns for `Options`: `D`, plus `Immutable` when `immutable: true`. */
+export type WithComponentOptions<D, Options extends ComponentOptions> =
+  Options extends { readonly immutable: true } ? D & Immutable : D
+
+const applyComponentOptions = <D extends object>(descriptor: D, options: ComponentOptions | undefined): D =>
+  options?.immutable === true ? { ...descriptor, immutable: true } : descriptor
+
+/**
+ * Whether a component descriptor was declared `immutable: true` (readable by
+ * queries, replaced only with `commands.insert(...)`).
+ */
+export const isImmutable = (descriptor: Descriptor.Any): descriptor is Descriptor.Any & Immutable =>
+  "immutable" in descriptor && descriptor.immutable === true
+
 /**
  * Type-level helpers for working with descriptors.
  */
@@ -253,11 +292,15 @@ const makeConstructedDescriptor = <
  * @example
  * ```ts
  * const Position = Descriptor.Component<{ x: number; y: number }>()("Position")
+ * // What an entity is, replaced with commands.insert and never written by a query:
+ * const EnemyKind = Descriptor.Component<"grunt" | "boss">()("EnemyKind", { immutable: true })
  * ```
  */
-export const Component = <Value>() => <const Name extends string>(
-  name: Name
-): Descriptor<"component", Name, Value> => makeDescriptor("component", name)
+export const Component = <Value>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<Descriptor<"component", Name, Value>, Options> =>
+  applyComponentOptions(makeDescriptor("component", name), options) as WithComponentOptions<Descriptor<"component", Name, Value>, Options>
 
 /**
  * Defines a component descriptor that also knows how to validate raw values.
@@ -274,10 +317,11 @@ export const Component = <Value>() => <const Name extends string>(
  */
 export const ConstructedComponent = <Value, Raw, Error, Constructor extends {} = {}>(
   constructor: ResultConstructor<Value, Raw, Error> & Constructor
-) => <const Name extends string>(
-  name: Name
-): ConstructedFor<"component", Name, Value, Raw, Error, Constructor> =>
-  makeConstructedDescriptor("component", name, constructor) as ConstructedFor<"component", Name, Value, Raw, Error, Constructor>
+) => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<ConstructedFor<"component", Name, Value, Raw, Error, Constructor>, Options> =>
+  applyComponentOptions(makeConstructedDescriptor("component", name, constructor), options) as WithComponentOptions<ConstructedFor<"component", Name, Value, Raw, Error, Constructor>, Options>
 
 /**
  * Defines a component descriptor that snapshots skip.
@@ -290,9 +334,11 @@ export const ConstructedComponent = <Value, Raw, Error, Constructor extends {} =
  * const SpriteRef = Descriptor.TransientComponent<{ frame: number }>()("SpriteRef")
  * ```
  */
-export const TransientComponent = <Value>() => <const Name extends string>(
-  name: Name
-): TransientDescriptor<"component", Name, Value> => makeTransientDescriptor("component", name)
+export const TransientComponent = <Value>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options> =>
+  applyComponentOptions(makeTransientDescriptor("component", name), options) as WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options>
 
 /**
  * Defines a marker component: no data, only presence (`[Player, {}]`).
@@ -311,70 +357,77 @@ export const Tag = <const Name extends string>(
 ): DecodableDescriptor<"component", Name, {}, {}, DecodeModule.DecodeError> =>
   ConstructedComponent(DecodeModule.struct({}))(name)
 
-/** One state of a {@link State} component: a string or number literal. */
-export type StateValue = string | number
+/** One state of a {@link EntityState} component: a string or number literal. */
+export type EntityStateValue = string | number
 
 /**
- * The allowed moves of a {@link State} component: for every state, the
+ * The allowed moves of a {@link EntityState} component: for every state, the
  * states it may move to (`[]` for a state with no way out).
  */
-export type StateTransitions<States extends readonly [StateValue, ...Array<StateValue>]> = {
+export type EntityStateTransitions<States extends readonly [EntityStateValue, ...Array<EntityStateValue>]> = {
   readonly [From in States[number]]: ReadonlyArray<States[number]>
 }
 
 /**
  * A component whose value is one of a closed set of states, with an optional
- * graph of allowed moves. Built with {@link State}.
+ * graph of allowed moves. Built with {@link EntityState}.
  */
-export interface StateDescriptor<
+export interface EntityStateDescriptor<
   out Name extends string,
-  in out States extends readonly [StateValue, ...Array<StateValue>],
-  in out Transitions extends StateTransitions<States> | undefined
+  in out States extends readonly [EntityStateValue, ...Array<EntityStateValue>],
+  in out Transitions extends EntityStateTransitions<States> | undefined
 > extends DecodableDescriptor<"component", Name, States[number], States[number], DecodeModule.DecodeError> {
   readonly states: States
   readonly transitions: Transitions
 }
 
 /**
- * Defines a state component: its value is one of `states`, validated (so
- * snapshots reject unknown states), and it behaves like any other component
- * (storage, change detection, rollback, traces).
+ * Defines a per-entity state: a component whose value is one of `states`,
+ * validated (so snapshots reject unknown states), that behaves like any other
+ * component (storage, change detection, rollback, traces).
+ *
+ * Use this when each entity has its own state: an enemy's attack windup, a
+ * door's open/closed, a unit's AI mode. Use `Game.StateMachine(...)` instead
+ * for one game-wide mode (menu, playing, paused, game over): machines change
+ * only at `applyStateTransitions(...)`, run `onEnter`/`onExit` schedules, and
+ * gate systems with `Game.Condition.inState(...)`. An entity state does none
+ * of that; it is data on an entity.
  *
  * With `transitions`, its write cell gains `transition(from, to)`: the pair
  * is checked against the graph at compile time, and at runtime the move
- * happens only if the current state is still `from`, otherwise it returns a
- * `StateMismatch` failure. Transitions are ordinary component writes:
+ * happens only if the current state is still `from`, otherwise it returns an
+ * `EntityStateMismatch` failure. Transitions are ordinary component writes:
  * immediate, visible to later systems, rolled back with a failed system.
  *
  * @example
  * ```ts
- * const Phase = Descriptor.State("Phase", ["ready", "windup", "active"] as const, {
+ * const Attack = Descriptor.EntityState("Attack", ["ready", "windup", "active"] as const, {
  *   transitions: { ready: ["windup"], windup: ["active", "ready"], active: ["ready"] }
  * })
- * // in a system with a write slot `phase`:
- * const moved = data.phase.transition("windup", "active")   // "ready" -> "active" does not compile
+ * // in a system with a write slot `attack`:
+ * const moved = data.attack.transition("windup", "active")   // "ready" -> "active" does not compile
  * ```
  */
-export const State = <
+export const EntityState = <
   const Name extends string,
-  const States extends readonly [StateValue, ...Array<StateValue>],
-  const Transitions extends StateTransitions<States> | undefined = undefined
+  const States extends readonly [EntityStateValue, ...Array<EntityStateValue>],
+  const Transitions extends EntityStateTransitions<States> | undefined = undefined
 >(
   name: Name,
   states: States,
   options?: {
     readonly transitions: Transitions & { readonly [Key in Exclude<keyof Transitions, States[number]>]: never }
   }
-): StateDescriptor<Name, States, Transitions> => ({
+): EntityStateDescriptor<Name, States, Transitions> => ({
   ...makeConstructedDescriptor("component", name, DecodeModule.literal(...states)),
   states,
   transitions: options?.transitions
-}) as unknown as StateDescriptor<Name, States, Transitions>
+}) as unknown as EntityStateDescriptor<Name, States, Transitions>
 
-/** Whether a descriptor was built with {@link State}. */
-export const isState = (
+/** Whether a descriptor was built with {@link EntityState}. */
+export const isEntityState = (
   descriptor: Descriptor.Any
-): descriptor is StateDescriptor<string, readonly [StateValue, ...Array<StateValue>], StateTransitions<readonly [StateValue, ...Array<StateValue>]> | undefined> =>
+): descriptor is EntityStateDescriptor<string, readonly [EntityStateValue, ...Array<EntityStateValue>], EntityStateTransitions<readonly [EntityStateValue, ...Array<EntityStateValue>]> | undefined> =>
   "states" in descriptor
 
 /**
@@ -568,7 +621,9 @@ export function constructorOf<D extends Descriptor.Any>(
  * `related` is the reverse collection maintained by the runtime.
  *
  * Use hierarchy when the relationship must support ordered children,
- * ancestor/descendant traversal, and linked recursive despawn.
+ * ancestor/descendant traversal, and linked recursive despawn. Use
+ * `Game.EntityScope(...)` instead when entities only share a lifetime (a
+ * level, a menu) and need no tree, order, or traversal.
  */
 export const Hierarchy = RelationModule.Hierarchy
 

package/src/Entity.ts

@@ -56,7 +56,8 @@ import * as Result from "./Result.ts"
  * @example
  * ```ts
  * const handle = Game.Entity.handle(playerId, Player)
- * const resolved = lookup.getHandle(handle, PlayerQuery)
+ * // `players` is a query the system declares: queries: { players: PlayerQuery }
+ * const resolved = queries.players.getHandle(handle)
  * if (!resolved.ok) return
  * ```
  */
@@ -167,11 +168,23 @@ export type StagedComponent = readonly [Descriptor<"component", string, any>, un
  *
  * Query execution is the main source of `EntityRef` values.
  */
-export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown> {
+export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown, out Proves = unknown, out Lacks = never> {
   /**
    * Runtime tag for debugging and pattern matching.
    */
   readonly kind: "EntityRef"
+  /**
+   * The component descriptors the query that produced this ref proves (its
+   * required slots and `with`): what `commands.despawn`, `insert`, and
+   * `remove` check. Type-level only.
+   */
+  readonly __proves?: (_: never) => Proves
+  /**
+   * The component descriptors the producing query proves absent (its
+   * `without`): what `commands.remove` checks against `Schema.requires`.
+   * Type-level only.
+   */
+  readonly __lacks?: (_: never) => Lacks
   /**
    * The schema-bound entity identity.
    */
@@ -193,12 +206,18 @@ export interface EntityMut<
   S extends Schema.Any,
   out P extends ComponentProof,
   out W extends ComponentProof,
-  Root = unknown
+  Root = unknown,
+  out Proves = unknown,
+  out Lacks = never
 > {
   /**
    * Runtime tag for debugging and pattern matching.
    */
   readonly kind: "EntityMut"
+  /** The component descriptors the producing query proves; see `EntityRef`. */
+  readonly __proves?: (_: never) => Proves
+  /** The component descriptors the producing query proves absent; see `EntityRef`. */
+  readonly __lacks?: (_: never) => Lacks
   /**
    * The schema-bound entity identity.
    */
@@ -247,7 +266,7 @@ export type HandleTarget<S extends Schema.Any, Root = unknown> =
  * Converts a current entity into a durable handle for storage.
  *
  * The handle is storage-safe, not a proof of liveness: resolve it later with
- * `lookup.getHandle(...)`, which fails explicitly when the entity is gone.
+ * `queries.x.getHandle(...)` (through a declared query), which fails explicitly when the entity is gone.
  *
  * Pass an `intent` component when later code assumes a role such as "player"
  * or "damage source". An intent does not prove the component is still present;
@@ -283,7 +302,7 @@ export interface InvalidHandle {
  * handles, so restoring validates them like any other value.
  *
  * A handle only names an entity; it never proves the entity exists. Resolving
- * it with `lookup.getHandle(...)` stays the checked step, so any positive
+ * it with `queries.x.getHandle(...)` (through a declared query) stays the checked step, so any positive
  * integer id decodes. Object-shaped handles and other non-numeric values
  * are rejected.
  *