@typeonce/ritmo 0.6.0 → 0.8.0

package/src/EntityScope.ts

@@ -7,6 +7,17 @@
  * build scenes without teaching the ECS runtime about menus, levels, overlays,
  * or any other game-specific scene model.
  *
+ * Use a scope when a set of entities shares one lifetime and nothing else: a
+ * level's walls, a menu's buttons. Membership is flat, unordered, and not
+ * queryable. Use `Descriptor.Hierarchy(...)` instead when entities form a
+ * parent-child tree: ordered children, `lookup.parent` / `descendants`
+ * traversal, and children despawned with their parent.
+ *
+ * A scope whose lifetime is a game state declares it:
+ * `Game.EntityScope(name, { despawnOnExit: [Flow, "Playing"] })` despawns
+ * every member when `applyStateTransitions(...)` commits that state change,
+ * with no system, permission, or marker to place.
+ *
  * @module EntityScope
  * @docGroup core
  */
@@ -19,9 +30,21 @@ export interface EntityScope<
   readonly kind: "entityScope"
   readonly name: Name
   readonly key: symbol
+  /** State changes that despawn every member, applied by `applyStateTransitions(...)`. */
+  readonly despawnOn: ReadonlyArray<Trigger>
   readonly __schemaRoot?: Root | undefined
 }
 
+/**
+ * One state change that despawns a scope: leaving (`exit`) or entering
+ * (`enter`) `state` of `machine`.
+ */
+export interface Trigger {
+  readonly phase: "enter" | "exit"
+  readonly machine: { readonly key: symbol; readonly name: string }
+  readonly state: string | number
+}
+
 /** Type-level helpers for entity scopes. */
 export namespace EntityScope {
   export type Any = EntityScope<string, any>
@@ -36,11 +59,13 @@ export namespace EntityScope {
  * branded to that game's root.
  */
 export const make = <const Name extends string, Root = unknown>(
-  name: Name
+  name: Name,
+  despawnOn: ReadonlyArray<Trigger> = []
 ): EntityScope<Name, Root> => ({
   kind: "entityScope",
   name,
-  key: keyOf(name)
+  key: keyOf(name),
+  despawnOn
 })
 
 const keyPrefix = "ritmo/entityScope/"

package/src/HostClock.ts

@@ -0,0 +1,64 @@
+/**
+ * The host's wall clock, as an injected contract.
+ *
+ * Core and the generic devtools modules never read a platform clock
+ * (`performance`, `Date`) themselves: whatever measures host time (debug
+ * trace durations, session timings, replay windows) takes a `HostClock`.
+ * Platform packages provide implementations (`BrowserHostClock.make(window)`
+ * in the browser package); `standard` works in every JavaScript engine, and
+ * `test()` is a manual clock for deterministic tests.
+ *
+ * Host time is for measuring the host (how long a tick took), never for game
+ * logic: simulation time is a resource the schedule advances.
+ *
+ * @example
+ * ```ts
+ * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } })
+ * ```
+ *
+ * @module HostClock
+ * @docGroup runtime
+ */
+import * as Result from "./Result.ts"
+
+/** A host clock: `now()` in milliseconds, from an arbitrary origin. */
+export interface HostClock {
+  readonly now: () => number
+}
+
+/**
+ * `Date.now`, which every JavaScript engine provides. Its readings can jump
+ * (the system clock is adjusted, or the device sleeps), so a duration
+ * computed from two readings can be negative: consumers clamp durations to
+ * 0. Prefer a monotonic platform clock when there is one
+ * (`BrowserHostClock.make(window)`).
+ */
+export const standard: HostClock = { now: () => Date.now() }
+
+/** `adjust` must leave a finite clock reading and never move backwards. */
+export interface InvalidAdjustment {
+  readonly _tag: "InvalidAdjustment"
+  readonly ms: number
+}
+
+/** A manual clock for tests: starts at 0 and moves only through `adjust`. */
+export interface TestHostClock extends HostClock {
+  /** Moves the clock forward by `ms` (0 or more). */
+  readonly adjust: (ms: number) => Result.Result<void, InvalidAdjustment>
+}
+
+/** A test clock at 0. Every reading is the same until `adjust` moves it. */
+export const test = (): TestHostClock => {
+  let current = 0
+  return {
+    now: () => current,
+    adjust: (ms) => {
+      if (!Number.isFinite(ms) || ms < 0 || !Number.isFinite(current + ms)) return Result.failure({ _tag: "InvalidAdjustment", ms })
+      current += ms
+      return Result.success(undefined)
+    }
+  }
+}
+
+/** A duration between two readings, clamped to 0 when the clock went backwards. */
+export const elapsed = (from: number, to: number): number => Math.max(0, to - from)

package/src/Inspector.ts

@@ -6,6 +6,12 @@
  * They run on demand through `runtime.inspect(...)` and return a value without
  * advancing schedule visibility.
  *
+ * An inspector is the one typed read-only view of the world: tests, saves, UI,
+ * `Game.Condition.check(...)` projections, and devtools invariants
+ * (`Invariant.fromInspector(...)`) are all built from it. `runtime.inspect`
+ * rejects at compile time an inspector that reads a resource, service, or
+ * machine the runtime was not given.
+ *
  * @module Inspector
  * @docGroup runtime
  */
@@ -74,7 +80,7 @@ export interface InspectorDefinition<
 > {
   readonly kind: "inspector"
   readonly name: Name
-  readonly system: System.SystemDefinition<Spec, void, never, Root, Name, Needs>
+  readonly system: System.SystemDefinition<Spec, never, Root, Name, Needs>
   readonly requirements: ReadonlyArray<Needs>
   readonly read: (context: InspectorContext<Spec>) => Value
   readonly __schemaRoot?: Root | undefined
@@ -111,7 +117,6 @@ export const make = <
     () => undefined
   ) as unknown as System.SystemDefinition<
     System.SystemSpec<S, Access, Root>,
-    void,
     never,
     Root,
     Name,

package/src/Machine.ts

@@ -9,6 +9,10 @@
  * run around that boundary. Menus, rounds, encounter phases, pause flows, and
  * restart/reset pipelines are the canonical cases.
  *
+ * A machine holds one value for the whole game. A state that each entity has
+ * on its own (an enemy's attack windup, a door's open/closed) is not a
+ * machine: use a `Descriptor.EntityState(...)` component instead.
+ *
  * @example
  * ```ts
  * // Model a gameplay phase whose transition timing matters.
@@ -33,8 +37,9 @@
  * @groupDescription Functions
  * Public constructors for machines, conditions, and explicit transition bundles.
  */
-import type { Schedule } from "./Schedule.ts"
+import type { AnyScheduleOrder, Schedule } from "./Schedule.ts"
 import * as Requirement from "./Requirement.ts"
+import type * as Result from "./Result.ts"
 import type { Schema } from "./Schema.ts"
 import type { SystemFailure } from "./System.ts"
 
@@ -52,60 +57,71 @@ export type StateValue = string | number
 export interface StateMachineDefinition<
   out Name extends string = string,
   out Values extends readonly [StateValue, ...StateValue[]] = readonly [StateValue, ...StateValue[]],
-  out Root = unknown
+  out Root = unknown,
+  out Parent = unknown
 > {
   readonly kind: "stateMachine"
   readonly name: Name
   readonly key: symbol
   readonly values: Values
+  /** For a sub-state: the machine and the state it exists in. */
+  readonly within?: SubStateParent | undefined
   readonly __schemaRoot?: Root | undefined
+  /** The machine a sub-state exists within; `unknown` for a top-level machine. */
+  readonly __parent?: (_: never) => Parent
+}
+
+/** Where a sub-state exists: while `machine` is in `state`. */
+export interface SubStateParent {
+  readonly machine: StateMachine.Any
+  readonly state: StateValue
 }
 
 /**
- * The runtime-visible transition payload for one machine.
+ * Whether `M` is a sub-state (declared with `within`): it has no value while
+ * its parent machine is in another state.
  */
-export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
-  readonly from: StateMachine.Value<M>
-  readonly to: StateMachine.Value<M>
-}
+export type IsSubState<M> =
+  M extends { readonly __parent?: (_: never) => infer Parent } ? unknown extends Parent ? false : true : false
 
 /**
- * A typed read-only view over the current committed state.
+ * The committed value of `M`. A sub-state has none (`undefined`) while its
+ * parent machine is not in the state it exists in; a top-level machine
+ * always has one.
  */
-export interface MachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-  get(): StateMachine.Value<M>
-  is(value: StateMachine.Value<M>): boolean
-}
+export type CurrentValue<M extends StateMachine.Any> =
+  IsSubState<M> extends true ? StateMachine.Value<M> | undefined : StateMachine.Value<M>
 
 /**
- * A typed queued-write view over the next state.
+ * Why queuing a sub-state's next value failed: its parent machine is not in
+ * the state the sub-state exists in, so there is nothing to change.
  */
-export interface NextMachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-  getPending(): StateMachine.Value<M> | undefined
-  set(value: StateMachine.Value<M>): void
-  setIfChanged(value: StateMachine.Value<M>): void
-  reset(): void
+export interface SubStateInactive {
+  readonly _tag: "SubStateInactive"
+  /** The sub-state's name. */
+  readonly machine: string
+  /** The parent machine's name. */
+  readonly parent: string
+  /** The parent state the sub-state exists in. */
+  readonly requires: StateValue
 }
 
 /**
- * A typed read-only view over the last applied transition.
- *
- * This view is only meaningful inside transition schedules and is therefore
- * only exposed to systems that explicitly declare transition access.
+ * What `nextMachines.x.set(...)` returns: nothing for a top-level machine,
+ * and for a sub-state a `Result` that fails with `SubStateInactive` when its
+ * parent is in another state.
  */
-export interface TransitionView<M extends StateMachineDefinition = StateMachineDefinition> {
-  get(): TransitionSnapshot<M>
-}
+export type SetResult<M extends StateMachine.Any> =
+  IsSubState<M> extends true ? Result.Result<void, SubStateInactive> : void
 
 /**
- * A typed read-only stream of committed machine transition events.
- *
- * These snapshots are published by `applyStateTransitions(...)` when a
- * transition commits. Like events, each reader sees the transitions published
- * since its own previous run.
+ * The runtime-visible transition payload for one machine. For a sub-state,
+ * `from` is `undefined` when it starts existing (its parent entered its
+ * state) and `to` is `undefined` when it stops.
  */
-export interface TransitionEventView<M extends StateMachineDefinition = StateMachineDefinition> {
-  all(): ReadonlyArray<TransitionSnapshot<M>>
+export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
+  readonly from: CurrentValue<M>
+  readonly to: CurrentValue<M>
 }
 
 /**
@@ -235,13 +251,16 @@ export interface TransitionScheduleDefinition<
   M extends StateMachineDefinition = StateMachineDefinition,
   Needs extends Requirement.Requirement = Requirement.Requirement,
   Root = unknown,
-  Failure extends SystemFailure = never
+  Failure extends SystemFailure = never,
+  Order extends AnyScheduleOrder = AnyScheduleOrder
 > {
   readonly steps: ReadonlyArray<Schedule.Step>
   readonly systems: ReadonlyArray<unknown>
   readonly schema: S
   readonly requirements: ReadonlyArray<Needs>
   readonly __failure?: (_: never) => Failure
+  /** The plan's order, for `Game.System.thisTick` checks of the tick that applies it. */
+  readonly __order?: (_: never) => Order
   readonly __schemaRoot?: Root | undefined
   readonly transition: {
     readonly machine: M
@@ -256,7 +275,7 @@ export interface TransitionScheduleDefinition<
  * Type-level and value-level helpers for finite-state machines.
  */
 export namespace StateMachine {
-  export type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown>
+  export type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown, unknown>
   export type Value<M extends Any> = M["values"][number]
   export type Root<M extends Any> = M extends StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], infer R> ? R : never
   export type AnyCondition<Root = unknown> = Condition<Root>
@@ -264,6 +283,23 @@ export namespace StateMachine {
     TransitionScheduleDefinition<S, Any, Requirement.Requirement, Root, SystemFailure>
 }
 
+/**
+ * `unknown` when `M` was defined by the game rooted at `Root`; otherwise a
+ * type naming the fix, so passing another game's machine fails with that
+ * message.
+ */
+export type SameGame<M, Root> =
+  M extends StateMachineDefinition<infer Name, readonly [StateValue, ...StateValue[]], infer MachineRoot>
+    ? [Root] extends [MachineRoot]
+      ? [MachineRoot] extends [Root]
+        ? unknown
+        : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`>
+      : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`>
+    : unknown
+
+/** The message type `SameGame` resolves to: a type error prints `Message`. */
+type ForeignMachine<Message extends string> = { readonly __foreignMachine__: Message }
+
 /** Extracts the machine token from one declared machine access slot. */
 type MachineFromAccess<Access> =
   Access extends { readonly machine: infer M extends StateMachine.Any } ? M : never
@@ -293,7 +329,7 @@ export type MachineNeedsFromConditions<C extends ReadonlyArray<Condition>> =
   MachineNeedsFromCondition<C[number]>
 
 /**
- * Creates a schema-bound finite-state machine definition.
+ * Creates a schema-bound finite-state machine definition: one game-wide mode.
  *
  * This is the intended default for gameplay phases and other discrete modes
  * where the transition boundary itself matters.
@@ -304,6 +340,12 @@ export type MachineNeedsFromConditions<C extends ReadonlyArray<Condition>> =
  * - explicit `applyStateTransitions(...)`
  * - `inState(...)` gating
  * - transition events or enter/exit schedules
+ *
+ * Use `Descriptor.EntityState(...)` instead when every entity carries its own
+ * state (per-entity, written immediately, no enter/exit schedules).
+ *
+ * Pass `within` for a sub-state: a machine that exists only while another
+ * machine is in one state (`Game.StateMachine(name, values, { within })`).
  */
 export const StateMachine = <
   const Name extends string,
@@ -311,12 +353,14 @@ export const StateMachine = <
   Root = unknown
 >(
   name: Name,
-  values: Values
+  values: Values,
+  within?: SubStateParent
 ): StateMachineDefinition<Name, Values, Root> => ({
   kind: "stateMachine",
   name,
   key: Symbol.for(`ritmo/stateMachine/${name}`),
-  values
+  values,
+  ...(within === undefined ? {} : { within })
 }) as StateMachineDefinition<Name, Values, Root>
 
 /**

package/src/Query.ts

@@ -69,7 +69,8 @@
  * Query authoring helpers for selecting components and declaring explicit filters.
  */
 import type { DecodeError } from "./Decode.ts"
-import type { Descriptor, StateValue } from "./Descriptor.ts"
+import * as DescriptorModule from "./Descriptor.ts"
+import type { Descriptor, EntityStateValue } from "./Descriptor.ts"
 import type { EntityId, EntityMut, EntityRef } from "./Entity.ts"
 import type * as Result from "./Result.ts"
 import type * as Relation from "./Relation.ts"
@@ -179,10 +180,24 @@ export interface ChangedFilter<D extends ComponentDescriptor> {
   readonly descriptor: D
 }
 
-export type Filter<D extends ComponentDescriptor> =
+/** An `added` or `changed` filter: the filters `anyOf` combines. */
+export type LifecycleFilter<D extends ComponentDescriptor> =
   | AddedFilter<D>
   | ChangedFilter<D>
 
+/**
+ * A filter that matches entities passing at least one of its `added` /
+ * `changed` filters since the reading system's previous run.
+ */
+export interface AnyOfFilter<D extends ComponentDescriptor> {
+  readonly kind: "anyOf"
+  readonly filters: ReadonlyArray<LifecycleFilter<D>>
+}
+
+export type Filter<D extends ComponentDescriptor> =
+  | LifecycleFilter<D>
+  | AnyOfFilter<D>
+
 /**
  * Declares read-only access to a component in a query selection.
  *
@@ -203,11 +218,29 @@ export const read = <D extends ComponentDescriptor>(descriptor: D): ReadAccess<D
  * place. A write slot both requires component presence and exposes the slot as
  * a `WriteCell`, so mutation capability stays visible in the query spec rather
  * than appearing ad hoc in the loop body.
+ *
+ * Components declared `immutable: true` cannot be written: replace them with
+ * `commands.insert(...)` instead.
  */
-export const write = <D extends ComponentDescriptor>(descriptor: D): WriteAccess<D> => ({
-  mode: "write",
-  descriptor
-})
+export const write = <D extends ComponentDescriptor>(descriptor: D & Writable<D>): WriteAccess<D> => {
+  if (DescriptorModule.isImmutable(descriptor)) {
+    throw new Error(immutableMessage(descriptor.name))
+  }
+  return { mode: "write", descriptor }
+}
+
+const immutableMessage = (name: string) =>
+  `${name} is immutable: replace it with commands.insert(entity, Game.Command.entry(${name}, ...))`
+
+type NameOf<D> = D extends { readonly name: infer Name extends string } ? Name : never
+
+/**
+ * `unknown` for a component a query may write; for one declared
+ * `immutable: true`, an argument error naming the fix.
+ */
+export type Writable<D> = D extends DescriptorModule.Immutable
+  ? { readonly __immutable__: `${NameOf<D>} is immutable: replace it with commands.insert(entity, Game.Command.entry(${NameOf<D>}, ...))` }
+  : unknown
 
 /**
  * Declares maybe-present read-only access to a component in a query
@@ -282,6 +315,34 @@ export const changed = <D extends ComponentDescriptor>(descriptor: D): ChangedFi
   descriptor
 })
 
+/**
+ * Declares a filter that matches entities passing at least one of `filters`
+ * (`added` / `changed`) since the reading system's previous run. Each entity
+ * is matched once, however many of its filters pass.
+ *
+ * Filters listed side by side in `filters: [...]` must all pass; use `anyOf`
+ * when any one of them is enough, for example to redraw when either the
+ * position or the sprite changed.
+ *
+ * @example
+ * ```ts
+ * const RedrawQuery = Game.Query({
+ *   selection: { position: Game.Query.read(Position), sprite: Game.Query.read(Sprite) },
+ *   filters: [Game.Query.anyOf(Game.Query.changed(Position), Game.Query.changed(Sprite))]
+ * })
+ * ```
+ */
+export const anyOf = <
+  const Filters extends readonly [
+    LifecycleFilter<ComponentDescriptor>,
+    LifecycleFilter<ComponentDescriptor>,
+    ...ReadonlyArray<LifecycleFilter<ComponentDescriptor>>
+  ]
+>(...filters: Filters): AnyOfFilter<Filters[number]["descriptor"]> => ({
+  kind: "anyOf",
+  filters
+})
+
 /**
  * A fully explicit query specification.
  *
@@ -384,6 +445,12 @@ export namespace Query {
     ? false
     : true
 
+  /** The component descriptors a query proves its matches have: required selection slots and `with`. */
+  export type Proven<T extends Any> = RequiredSelectionDescriptors<T> | T["with"][number]
+
+  /** The component descriptors a query proves its matches lack: its `without`. */
+  export type Excluded<T extends Any> = T["without"][number]
+
   /**
    * The readable proof produced by a query.
    */
@@ -488,24 +555,20 @@ export interface ReadCell<T> {
  * A mutable cell returned from query or resource access.
  *
  * This gives a narrow mutation surface instead of exposing raw storage objects.
+ * Values written here are already valid. Data that still needs validation
+ * goes through its descriptor's own validator: declare the descriptor with
+ * `Descriptor.ConstructedComponent` / `ConstructedResource` and write with
+ * `setRaw` / `updateRaw` on its {@link ConstructedWriteCell}.
  */
 export interface WriteCell<T> extends ReadCell<T> {
   /**
    * Replaces the current value.
    */
   set(value: T): void
-  /**
-   * Replaces the current value from an explicit result.
-   */
-  setResult<E>(result: Result.Result<T, E>): Result.Result<void, E>
   /**
    * Updates the current value based on the previous one.
    */
   update(f: (current: ReadonlyValue<T>) => T): void
-  /**
-   * Updates the current value from an explicit result-producing callback.
-   */
-  updateResult<E>(f: (current: ReadonlyValue<T>) => Result.Result<T, E>): Result.Result<void, E>
 }
 
 /**
@@ -540,13 +603,13 @@ export interface ConstructedWriteCell<T, Raw, Error> extends WriteCell<T> {
 }
 
 /**
- * A `transition(from, to)` found the state component in another state, so
+ * A `transition(from, to)` found the entity state in another state, so
  * nothing was written.
  */
-export interface StateMismatchError<T> {
-  readonly _tag: "StateMismatch"
-  /** Name of the state component. */
-  readonly state: string
+export interface EntityStateMismatchError<T> {
+  readonly _tag: "EntityStateMismatch"
+  /** Name of the `Descriptor.EntityState` component. */
+  readonly component: string
   /** The `from` state the transition expected. */
   readonly expected: T
   /** The state the component was actually in. */
@@ -554,20 +617,20 @@ export interface StateMismatchError<T> {
 }
 
 /**
- * Writable cell for a state component (`Descriptor.State`).
+ * Writable cell for an entity state component (`Descriptor.EntityState`).
  *
  * `transition(from, to)` is a compare-and-set: it writes `to` only while the
- * current state is `from`, and otherwise returns `StateMismatch` without
+ * current state is `from`, and otherwise returns `EntityStateMismatch` without
  * writing. With a transition graph, `to` must be one of the moves the graph
  * allows from `from`; without one, any pair of states is accepted.
  */
-export interface StateWriteCell<T, Transitions> extends ConstructedWriteCell<T, T, DecodeError> {
+export interface EntityStateWriteCell<T, Transitions> extends ConstructedWriteCell<T, T, DecodeError> {
   /**
    * Moves from `from` to `to` if the component is still in `from`.
    *
    * @example
    * ```ts
-   * const moved = data.phase.transition("windup", "active")
+   * const moved = data.attack.transition("windup", "active")
    * if (!moved.ok) {
    *   // moved.error.actual is the state some earlier write left
    * }
@@ -575,19 +638,19 @@ export interface StateWriteCell<T, Transitions> extends ConstructedWriteCell<T,
    */
   transition<const From extends T & keyof Transitions>(
     from: From,
-    to: StateTarget<T, Transitions, From>
-  ): Result.Result<void, StateMismatchError<T>>
+    to: EntityStateTarget<T, Transitions, From>
+  ): Result.Result<void, EntityStateMismatchError<T>>
 }
 
-type StateTarget<T, Transitions, From extends keyof Transitions> =
+type EntityStateTarget<T, Transitions, From extends keyof Transitions> =
   Transitions[From] extends ReadonlyArray<infer To> ? To & T : never
 
 /**
  * Write-cell surface produced for one queried component descriptor.
  */
 export type WriteCellForDescriptor<D extends ComponentDescriptor> =
-  D extends import("./Descriptor.ts").StateDescriptor<string, infer States extends readonly [StateValue, ...Array<StateValue>], any>
-    ? StateWriteCell<States[number], D["transitions"] extends undefined ? { readonly [K in States[number]]: States } : D["transitions"]>
+  D extends import("./Descriptor.ts").EntityStateDescriptor<string, infer States extends readonly [EntityStateValue, ...Array<EntityStateValue>], any>
+    ? EntityStateWriteCell<States[number], D["transitions"] extends undefined ? { readonly [K in States[number]]: States } : D["transitions"]>
     : D extends import("./Descriptor.ts").ConstructedDescriptor<"component", string, infer Value, infer Raw, infer Error>
     ? ConstructedWriteCell<Value, Raw, Error>
     : WriteCell<Descriptor.Value<D>>
@@ -622,11 +685,11 @@ export type OptionalReadCell<T> = PresentOptionalReadCell<T> | AbsentOptionalRea
 export type QueryMatch<S extends Schema.Any, Q extends Query.Any> =
   keyof Query.WriteProof<Q> extends never
     ? {
-        readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>>
+        readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>
         readonly data: Query.Cells<Q>
       }
     : {
-        readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>>
+        readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>
         readonly data: Query.Cells<Q>
       }
 
@@ -685,6 +748,14 @@ export const multipleEntitiesError = (count: number): Query.MultipleEntitiesErro
  * })
  * ```
  */
+/**
+ * `T` itself, but not a place inference reads from: a list a query omits
+ * stays `[]` even when the call sits where a wider query type is expected
+ * (`queries: { ... }` in a spec). Unlike `NoInfer`, it prints as `T`.
+ */
+// `T` appears only as the check type, which inference never reads.
+export type Uninferred<T, Bound> = [T] extends [infer U extends Bound] ? U : never
+
 export const Query = <
   const Selection extends Record<string, SelectionAccess<any, Root>>,
   const With extends ReadonlyArray<ComponentDescriptor> = [],
@@ -704,14 +775,15 @@ export const Query = <
   readonly withoutRelations?: WithoutRelations
   readonly withRelated?: WithRelated
   readonly withoutRelated?: WithoutRelated
-}): QuerySpec<Selection, With, Without, Filters, WithRelations, WithoutRelations, WithRelated, WithoutRelated, Root> => ({
+  // Uninferred: an omitted list is `[]`, never inferred from the spec it is written in (`queries: { ... }`).
+}): QuerySpec<Selection, Uninferred<With, ReadonlyArray<ComponentDescriptor>>, Uninferred<Without, ReadonlyArray<ComponentDescriptor>>, Uninferred<Filters, ReadonlyArray<Filter<ComponentDescriptor>>>, Uninferred<WithRelations, ReadonlyArray<Relation.Relation.Any>>, Uninferred<WithoutRelations, ReadonlyArray<Relation.Relation.Any>>, Uninferred<WithRelated, ReadonlyArray<Relation.Relation.Any>>, Uninferred<WithoutRelated, ReadonlyArray<Relation.Relation.Any>>, Root> => ({
   selection: spec.selection,
-  with: (spec.with ?? []) as With,
-  without: (spec.without ?? []) as Without,
-  filters: (spec.filters ?? []) as Filters,
-  withRelations: (spec.withRelations ?? []) as WithRelations,
-  withoutRelations: (spec.withoutRelations ?? []) as WithoutRelations,
-  withRelated: (spec.withRelated ?? []) as WithRelated,
-  withoutRelated: (spec.withoutRelated ?? []) as WithoutRelated,
+  with: (spec.with ?? []) as unknown as Uninferred<With, ReadonlyArray<ComponentDescriptor>>,
+  without: (spec.without ?? []) as unknown as Uninferred<Without, ReadonlyArray<ComponentDescriptor>>,
+  filters: (spec.filters ?? []) as unknown as Uninferred<Filters, ReadonlyArray<Filter<ComponentDescriptor>>>,
+  withRelations: (spec.withRelations ?? []) as unknown as Uninferred<WithRelations, ReadonlyArray<Relation.Relation.Any>>,
+  withoutRelations: (spec.withoutRelations ?? []) as unknown as Uninferred<WithoutRelations, ReadonlyArray<Relation.Relation.Any>>,
+  withRelated: (spec.withRelated ?? []) as unknown as Uninferred<WithRelated, ReadonlyArray<Relation.Relation.Any>>,
+  withoutRelated: (spec.withoutRelated ?? []) as unknown as Uninferred<WithoutRelated, ReadonlyArray<Relation.Relation.Any>>,
   __schemaRoot: undefined as unknown as Root
 })