@typeonce/ritmo 0.7.0 → 0.9.0

package/src/FixedLoop.ts

@@ -0,0 +1,218 @@
+/**
+ * Deterministic fixed-step timing for any host: browsers, native shells,
+ * desktop runtimes, and headless tests.
+ *
+ * The loop owns the timing policy that is easy to get subtly wrong in every
+ * game: frame clamping, catch-up limits, interpolation, cancellation, and
+ * typed update failures. It does not know about an ECS runtime, a renderer,
+ * or a platform: frames arrive through a `TickSource` that the host supplies.
+ * Use a platform adapter such as `BrowserTickSource.make(window)` from
+ * `@typeonce/ritmo-browser`, or wrap a renderer's own ticker with `source`.
+ *
+ * @example
+ * ```ts
+ * const loop = FixedLoop.start({
+ *   source: BrowserTickSource.make(window),
+ *   step: Clock.hz(60),
+ *   maxFrameSeconds: 0.25,
+ *   maxStepsPerFrame: 5,
+ *   update: () => runtime.tick(update),
+ *   render: (frame) => draw(frame.alpha),
+ *   onFailure: (failure) => console.error(failure)
+ * })
+ * ```
+ *
+ * @module FixedLoop
+ * @docGroup runtime
+ */
+import type * as Clock from "./Clock.ts"
+import * as Result from "./Result.ts"
+
+/** One host frame: milliseconds elapsed since the previous one. */
+export interface Tick {
+  readonly deltaMS: number
+}
+
+/** A stoppable host subscription. Calling `stop` more than once is safe. */
+export interface Subscription {
+  stop(): void
+}
+
+/**
+ * Where host frames come from. Implemented by platform adapters
+ * (`BrowserTickSource.make(window)`), by `source` around a renderer's ticker,
+ * and by deterministic tests.
+ */
+export interface TickSource<TTick extends Tick = Tick> {
+  subscribe(onTick: (tick: TTick) => void): Subscription
+}
+
+/** Validated fixed-step timing policy. */
+export interface Options {
+  /**
+   * The fixed step every update advances (`Clock.hz(60)`): the same value
+   * the game's clock resource runs at, so the loop and the clock agree.
+   */
+  readonly step: Clock.Step
+  /** Maximum host-frame duration admitted into the accumulator. */
+  readonly maxFrameSeconds: number
+  /** Maximum number of simulation updates performed for one host frame. */
+  readonly maxStepsPerFrame: number
+}
+
+/** Configuration error returned before a loop subscribes to its host. */
+export interface InvalidOptions {
+  readonly kind: "InvalidFixedLoopOptions"
+  readonly field: keyof Options
+  readonly reason: "mustBeFiniteAndPositive" | "mustBePositiveInteger"
+  readonly value: number
+}
+
+/** Data passed to the renderer after all fixed updates for one host frame. */
+export interface Frame {
+  /** Clamped time admitted for this host frame. */
+  readonly elapsedSeconds: number
+  /** Number of fixed updates completed for this host frame. */
+  readonly fixedSteps: number
+  /** Remaining accumulator fraction in the range `[0, 1)`. */
+  readonly alpha: number
+  /** Time discarded by frame clamping or the catch-up limit. */
+  readonly droppedSeconds: number
+}
+
+/** Failure delivered by an active loop before it stops itself. */
+export type Failure<UpdateError> =
+  | {
+      readonly kind: "InvalidTickDelta"
+      readonly deltaMS: number
+    }
+  | {
+      readonly kind: "UpdateFailure"
+      readonly error: UpdateError
+    }
+
+/** A running fixed-step driver. */
+export interface Driver extends Subscription {
+  /** Clears accumulated partial time without removing the host subscription. */
+  reset(): void
+}
+
+/** Input for a fixed-step driver. */
+export interface StartOptions<TTick extends Tick, UpdateError> extends Options {
+  readonly source: TickSource<TTick>
+  readonly update: (stepSeconds: number) => Result.Result<void, UpdateError>
+  readonly render: (frame: Frame) => void
+  readonly onFailure: (failure: Failure<UpdateError>) => void
+}
+
+/** Wraps a host-specific subscription function in the canonical source type. */
+export const source = <TTick extends Tick>(
+  subscribe: TickSource<TTick>["subscribe"]
+): TickSource<TTick> => ({ subscribe })
+
+const validate = (options: Options): Result.Result<void, InvalidOptions> => {
+  for (const field of ["maxFrameSeconds"] as const) {
+    const value = options[field]
+    if (!Number.isFinite(value) || value <= 0) {
+      return Result.failure({
+        kind: "InvalidFixedLoopOptions",
+        field,
+        reason: "mustBeFiniteAndPositive",
+        value
+      })
+    }
+  }
+  if (!Number.isInteger(options.maxStepsPerFrame) || options.maxStepsPerFrame <= 0) {
+    return Result.failure({
+      kind: "InvalidFixedLoopOptions",
+      field: "maxStepsPerFrame",
+      reason: "mustBePositiveInteger",
+      value: options.maxStepsPerFrame
+    })
+  }
+  return Result.success(undefined)
+}
+
+/**
+ * Starts a fixed-step loop after validating its timing policy.
+ *
+ * Update failures and malformed host ticks are delivered to `onFailure`, then
+ * the driver stops. Render defects are deliberately not caught: they are
+ * programmer defects, not expected game outcomes.
+ */
+export const start = <TTick extends Tick, UpdateError>(
+  options: StartOptions<TTick, UpdateError>
+): Result.Result<Driver, InvalidOptions> => {
+  const validity = validate(options)
+  if (!validity.ok) {
+    return validity
+  }
+
+  let accumulator = 0
+  let stopped = false
+  let hostSubscription: Subscription | undefined
+
+  const stop = (): void => {
+    if (stopped) {
+      return
+    }
+    stopped = true
+    hostSubscription?.stop()
+  }
+
+  const fail = (failure: Failure<UpdateError>): void => {
+    stop()
+    options.onFailure(failure)
+  }
+
+  const onTick = (tick: TTick): void => {
+    if (stopped) {
+      return
+    }
+    if (!Number.isFinite(tick.deltaMS) || tick.deltaMS < 0) {
+      fail({ kind: "InvalidTickDelta", deltaMS: tick.deltaMS })
+      return
+    }
+
+    const rawSeconds = tick.deltaMS / 1000
+    const elapsedSeconds = Math.min(rawSeconds, options.maxFrameSeconds)
+    let droppedSeconds = rawSeconds - elapsedSeconds
+    accumulator += elapsedSeconds
+
+    let fixedSteps = 0
+    while (accumulator >= options.step.dt && fixedSteps < options.maxStepsPerFrame) {
+      const update = options.update(options.step.dt)
+      if (!update.ok) {
+        fail({ kind: "UpdateFailure", error: update.error })
+        return
+      }
+      accumulator -= options.step.dt
+      fixedSteps += 1
+    }
+
+    if (accumulator >= options.step.dt) {
+      const droppedWholeSteps = Math.floor(accumulator / options.step.dt) * options.step.dt
+      accumulator -= droppedWholeSteps
+      droppedSeconds += droppedWholeSteps
+    }
+
+    options.render({
+      elapsedSeconds,
+      fixedSteps,
+      alpha: accumulator / options.step.dt,
+      droppedSeconds
+    })
+  }
+
+  hostSubscription = options.source.subscribe(onTick)
+  if (stopped) {
+    hostSubscription.stop()
+  }
+
+  return Result.success({
+    stop,
+    reset() {
+      accumulator = 0
+    }
+  })
+}

package/src/HostClock.ts

@@ -13,7 +13,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } })
+ * const runtime = Game.Runtime.make({ services, debug: { hostClock: HostClock.standard } }).value
  * ```
  *
  * @module HostClock
@@ -33,6 +33,7 @@ export interface HostClock {
  * 0. Prefer a monotonic platform clock when there is one
  * (`BrowserHostClock.make(window)`).
  */
+// oxlint-disable-next-line ritmo/use-clock-for-time -- HostClock is host time, for hosts and tools; systems read Clock.
 export const standard: HostClock = { now: () => Date.now() }
 
 /** `adjust` must leave a finite clock reading and never move backwards. */

package/src/Machine.ts

@@ -39,6 +39,7 @@
  */
 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"
 
@@ -56,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>
 }
 
 /**
@@ -263,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>
@@ -271,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
@@ -314,6 +343,9 @@ export type MachineNeedsFromConditions<C extends ReadonlyArray<Condition>> =
  *
  * 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,
@@ -321,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>
 
 /**
@@ -384,7 +418,10 @@ export const inState = <M extends StateMachine.Any>(
 })
 
 /**
- * Creates a condition that passes when the machine changed during the current schedule execution.
+ * Creates a condition that passes when the machine changed during the current schedule execution:
+ * from the `applyStateTransitions(...)` that committed the change to the end of
+ * that schedule (or the next `applyStateTransitions(...)`), not for the rest of
+ * the tick call or the next schedule.
  */
 export const stateChanged = <M extends StateMachine.Any>(
   machine: M

package/src/Query.ts

@@ -69,6 +69,7 @@
  * Query authoring helpers for selecting components and declaring explicit filters.
  */
 import type { DecodeError } from "./Decode.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"
@@ -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
@@ -265,7 +298,8 @@ export const added = <D extends ComponentDescriptor>(descriptor: D): AddedFilter
  *
  * Any write through a write cell counts, even when the value is equal to the
  * previous one. Writes from a system whose run failed are rolled back and do
- * not count.
+ * not count. A system never sees its own writes as changes on its next run
+ * (it does see the events it emitted).
  *
  * @example
  * ```ts
@@ -282,6 +316,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.
  *
@@ -366,6 +428,8 @@ export namespace Query {
    */
   export type Root<T extends Any> = T extends QuerySpec<any, any, any, any, any, any, any, any, infer R> ? R : never
 
+  type FilteredDescriptors<F> = F extends { readonly kind: "added" | "changed"; readonly descriptor: infer D } ? D : never
+
   type RequiredSelectionDescriptors<T extends Any> = {
     readonly [K in keyof T["selection"]]:
       T["selection"][K] extends ReadAccess<infer D> | WriteAccess<infer D> ? D : never
@@ -380,12 +444,19 @@ export namespace Query {
   export type ProvesComponent<
     T extends Any,
     D extends ComponentDescriptor
-  > = [Extract<RequiredSelectionDescriptors<T> | T["with"][number], D>] extends [never]
+  > = [Extract<Proven<T>, D>] extends [never]
     ? 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 have: required
+   * selection slots, `with`, and the component of each `added` / `changed`
+   * filter (a match has it). A `Query.anyOf` member proves nothing alone.
+   */
+  export type Proven<T extends Any> = RequiredSelectionDescriptors<T> | T["with"][number] | FilteredDescriptors<T["filters"][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.
@@ -498,13 +569,14 @@ export interface ReadCell<T> {
  */
 export interface WriteCell<T> extends ReadCell<T> {
   /**
-   * Replaces the current value.
+   * Replaces the current value. Takes the readonly shape reads return, so a
+   * value read from any cell can be written back as it is.
    */
-  set(value: T): void
+  set(value: ReadonlyValue<T>): void
   /**
    * Updates the current value based on the previous one.
    */
-  update(f: (current: ReadonlyValue<T>) => T): void
+  update(f: (current: ReadonlyValue<T>) => ReadonlyValue<T>): void
 }
 
 /**
@@ -562,7 +634,10 @@ export interface EntityStateMismatchError<T> {
  */
 export interface EntityStateWriteCell<T, Transitions> extends ConstructedWriteCell<T, T, DecodeError> {
   /**
-   * Moves from `from` to `to` if the component is still in `from`.
+   * Moves from `from` to `to` if the component is still in `from`. Use it for
+   * every move the transition table describes; `set` writes any state
+   * without checking the table, for resets that must not depend on the
+   * current state.
    *
    * @example
    * ```ts
@@ -596,6 +671,8 @@ export type WriteCellForDescriptor<D extends ComponentDescriptor> =
  */
 export interface PresentOptionalReadCell<T> extends ReadCell<T> {
   readonly present: true
+  /** The value, which is present. */
+  value(): T
 }
 
 /**
@@ -603,12 +680,17 @@ export interface PresentOptionalReadCell<T> extends ReadCell<T> {
  */
 export interface AbsentOptionalReadCell {
   readonly present: false
+  /** `undefined`: the entity does not hold the component. */
+  value(): undefined
 }
 
 /**
  * A query slot that may or may not be present on the matched entity.
  *
- * Callers must narrow on `present` before reading the value.
+ * Read it with `value()`: the value, or `undefined` when the entity does not
+ * hold the component. Narrow on `present` (then `get()`) only when the
+ * component's own value can be `undefined`, where `value()` cannot tell the
+ * two apart.
  */
 export type OptionalReadCell<T> = PresentOptionalReadCell<T> | AbsentOptionalReadCell
 
@@ -621,11 +703,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>, Query.Proven<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>, Query.Proven<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>
       }
 
@@ -692,6 +774,25 @@ export const multipleEntitiesError = (count: number): Query.MultipleEntitiesErro
 // `T` appears only as the check type, which inference never reads.
 export type Uninferred<T, Bound> = [T] extends [infer U extends Bound] ? U : never
 
+type DescriptorName<D> = D extends { readonly name: infer Name extends string } ? Name : never
+
+/** The names a query requires: its read and write slots, `with`, and plain `added` / `changed` filters. */
+type RequiredNames<Selection, With extends ReadonlyArray<unknown>, Filters extends ReadonlyArray<unknown>> =
+  | DescriptorName<{ readonly [K in keyof Selection]: Selection[K] extends { readonly mode: "read" | "write"; readonly descriptor: infer D } ? D : never }[keyof Selection]>
+  | DescriptorName<With[number]>
+  | DescriptorName<Filters[number] extends infer F ? F extends { readonly kind: "added" | "changed"; readonly descriptor: infer D } ? D : never : never>
+
+/**
+ * Rejects a `without` naming a component the query also requires: such a
+ * query can never match. Use it on the `without` list of a query spec.
+ */
+export type ExclusionsPossible<Selection, With extends ReadonlyArray<unknown>, Without extends ReadonlyArray<unknown>, Filters extends ReadonlyArray<unknown>> =
+  [Extract<DescriptorName<Without[number]>, RequiredNames<Selection, With, Filters>>] extends [never]
+    ? unknown
+    : {
+      readonly __fixQuery__: `${Extract<DescriptorName<Without[number]>, RequiredNames<Selection, With, Filters>>} is both required and excluded (without): this query can never match; remove it from one side`
+    }
+
 export const Query = <
   const Selection extends Record<string, SelectionAccess<any, Root>>,
   const With extends ReadonlyArray<ComponentDescriptor> = [],
@@ -705,7 +806,7 @@ export const Query = <
 >(spec: {
   readonly selection: Selection
   readonly with?: With
-  readonly without?: Without
+  readonly without?: Without & ExclusionsPossible<Selection, With, Without, Filters>
   readonly filters?: Filters
   readonly withRelations?: WithRelations
   readonly withoutRelations?: WithoutRelations