@typeonce/ritmo 0.8.0 → 0.9.0

package/src/Command.ts

@@ -65,6 +65,7 @@ import * as Entity from "./Entity.ts"
 import type * as EntityScope from "./EntityScope.ts"
 import type * as Relation from "./Relation.ts"
 import * as Result from "./Result.ts"
+import type { ReadonlyValue } from "./Query.ts"
 import type { RequirementPair, Schema } from "./Schema.ts"
 
 /**
@@ -102,7 +103,7 @@ export namespace Draft {
 /**
  * A typed descriptor/value pair used by the flat command authoring APIs.
  */
-export type Entry<D extends Descriptor<"component", string, any>> = readonly [D, Descriptor.Value<D>]
+export type Entry<D extends Descriptor<"component", string, any>> = readonly [D, ReadonlyValue<Descriptor.Value<D>>]
 
 /**
  * Extracts the component-descriptor union from a schema.
@@ -142,15 +143,21 @@ type EntryValue<T> =
 export type FoldEntries<
   Entries extends ReadonlyArray<SpawnEntry<any>>,
   P extends Entity.ComponentProof = {}
-> = number extends Entries["length"]
-  // A widened array (a spread of entries built at runtime): each entry may or may not be there.
-  ? P & MaybeEntries<EntryValue<Entries[number]>>
+> = Entries extends readonly [
+    infer Head extends SpawnEntry<any>,
+    ...infer Tail extends ReadonlyArray<SpawnEntry<any>>
+  ]
+  ? FoldEntries<Tail, Draft.InsertEntry<P, EntryValue<Head>>>
+  // Fixed entries after a spread are there too.
   : Entries extends readonly [
-      infer Head extends SpawnEntry<any>,
-      ...infer Tail extends Array<SpawnEntry<any>>
+      ...infer Init extends ReadonlyArray<SpawnEntry<any>>,
+      infer Last extends SpawnEntry<any>
     ]
-    ? FoldEntries<Tail, Draft.InsertEntry<P, EntryValue<Head>>>
-    : P
+    ? FoldEntries<Init, Draft.InsertEntry<P, EntryValue<Last>>>
+    : number extends Entries["length"]
+      // A widened array (a spread of entries built at runtime): each entry may or may not be there.
+      ? P & MaybeEntries<EntryValue<Entries[number]>>
+      : P
 
 /** The proof of entries that may each be present: every component they can hold, optional. */
 type MaybeEntries<Entry> = {
@@ -175,10 +182,11 @@ export type DraftFor<
   S extends Schema.Any,
   Entries extends ReadonlyArray<SpawnEntry<S>>,
   P extends Entity.ComponentProof,
-  Root
+  Root,
+  Relates = never
 > = [Extract<Entries[number], { readonly ok: boolean }>] extends [never]
-  ? Entity.EntityDraft<S, FoldEntries<Entries, P>, Root>
-  : Result.Result<Entity.EntityDraft<S, FoldEntries<Entries, P>, Root>, EntryErrors<Entries>>
+  ? Entity.EntityDraft<S, FoldEntries<Entries, P>, Root, Relates>
+  : Result.Result<Entity.EntityDraft<S, FoldEntries<Entries, P>, Root, Relates>, EntryErrors<Entries>>
 
 /**
  * A deferred world mutation.
@@ -235,6 +243,12 @@ export interface InternalWorld<S extends Schema.Any> {
    * written when an inserted component would miss one it requires.
    */
   readonly insertComponents: (id: Entity.EntityId<S, any>, entries: ReadonlyArray<Entity.StagedComponent>) => void
+  /**
+   * Reports a `despawn` or `remove` given a numeric id this run did not
+   * spawn: an id kept from an earlier run, or a raw id that erased types let
+   * through. The command is skipped.
+   */
+  readonly reportStaleTarget: (command: "despawn" | "remove", id: Entity.EntityId<S, any>) => void
   /**
    * Attempts to attach one relation edge between two live entities.
    */
@@ -270,12 +284,13 @@ const unspawnedId = Entity.makeEntityId<any, any>(-1)
  */
 export const entry = <D extends Descriptor<"component", string, any>>(
   descriptor: D,
-  value: Descriptor.Value<D>
+  value: ReadonlyValue<Descriptor.Value<D>>
 ): Entry<D> => [descriptor, value]
 
 /**
  * Validates raw input through a constructed descriptor's own validator and
- * returns an entry result for `spawn(...)` / `insert(...)`.
+ * returns an entry result for `Game.Command.spawn(...)` / `extend(...)`.
+ * `commands.insert` takes valid entries only: check the result first.
  *
  * This is the one way to put unvalidated data on an entity: the descriptor
  * owns its validator (`Descriptor.ConstructedComponent(...)`, built with
@@ -316,12 +331,13 @@ export const extend = <
   S extends Schema.Any,
   P extends Entity.ComponentProof,
   Root,
-  const Entries extends ReadonlyArray<SpawnEntry<S>>
+  const Entries extends ReadonlyArray<SpawnEntry<S>>,
+  Relates = never
 >(
-  draft: Entity.EntityDraft<S, P, Root>,
+  draft: Entity.EntityDraft<S, P, Root, Relates>,
   ...entries: Entries
-): DraftFor<S, Entries, P, Root> =>
-  build(draft.id, { ...draft.proof }, [...draft.components], draft.relations, entries) as DraftFor<S, Entries, P, Root>
+): DraftFor<S, Entries, P, Root, Relates> =>
+  build(draft.id, { ...draft.proof }, [...draft.components], draft.relations, entries) as DraftFor<S, Entries, P, Root, Relates>
 
 /**
  * Shared draft builder. Plain entries take a fast path; the first `Result`
@@ -367,7 +383,7 @@ const build = (
  *
  * Drafts are plain values: build them anywhere (including small factories),
  * then queue them with `commands.spawn(...)`. Entries may be `[Descriptor,
- * value]` pairs or results from `entryRaw(...)`; see `insert(...)` for how
+ * value]` pairs or results from `entryRaw(...)`; see `extend(...)` for how
  * failures are reported.
  *
  * @example
@@ -399,12 +415,13 @@ export const relate = <
   S extends Schema.Any,
   P extends Entity.ComponentProof,
   R extends Relation.Relation.Any,
-  Root = unknown
+  Root = unknown,
+  Relates = never
 >(
-  draft: Entity.EntityDraft<S, P, Root>,
+  draft: Entity.EntityDraft<S, P, Root, Relates>,
   relation: R,
   target: Entity.EntityId<S, Root>
-): Entity.EntityDraft<S, P, Root> =>
+): Entity.EntityDraft<S, P, Root, Relates | R> =>
   Entity.draft(draft.id, draft.proof, draft.components, [
     ...draft.relations,
     {
@@ -427,7 +444,7 @@ type ComponentDescriptor = Descriptor<"component", string, any>
  * Allows `spawn` / `spawnIn` of drafts whose components are all among `components`.
  * Use it for entities the system creates; use `extend` on a draft to build one.
  */
-export const spawns = <const Components extends ReadonlyArray<ComponentDescriptor>>(...components: Components): Permission<"spawns", Components[number]> =>
+export const spawns = <const Components extends readonly [ComponentDescriptor, ...ReadonlyArray<ComponentDescriptor>]>(...components: Components): Permission<"spawns", Components[number]> =>
   ({ permission: "spawns", values: components })
 
 /**
@@ -435,11 +452,11 @@ export const spawns = <const Components extends ReadonlyArray<ComponentDescripto
  * replace at the next `applyDeferred()`. To change a value now, on an entity
  * you matched, write through a query (`Game.Query.write`) instead.
  */
-export const inserts = <const Components extends ReadonlyArray<ComponentDescriptor>>(...components: Components): Permission<"inserts", Components[number]> =>
+export const inserts = <const Components extends readonly [ComponentDescriptor, ...ReadonlyArray<ComponentDescriptor>]>(...components: Components): Permission<"inserts", Components[number]> =>
   ({ permission: "inserts", values: components })
 
 /** Allows `remove(entity, X)` with `X` among `components`. */
-export const removes = <const Components extends ReadonlyArray<ComponentDescriptor>>(...components: Components): Permission<"removes", Components[number]> =>
+export const removes = <const Components extends readonly [ComponentDescriptor, ...ReadonlyArray<ComponentDescriptor>]>(...components: Components): Permission<"removes", Components[number]> =>
   ({ permission: "removes", values: components })
 
 /**
@@ -447,7 +464,7 @@ export const removes = <const Components extends ReadonlyArray<ComponentDescript
  * of `components` (`match.entity`), never a raw id: the system can only
  * despawn what it has proven is, for example, an `Enemy`.
  */
-export const despawns = <const Components extends ReadonlyArray<ComponentDescriptor>>(...components: Components): Permission<"despawns", Components[number]> =>
+export const despawns = <const Components extends readonly [ComponentDescriptor, ...ReadonlyArray<ComponentDescriptor>]>(...components: Components): Permission<"despawns", Components[number]> =>
   ({ permission: "despawns", values: components })
 
 /** Allows `despawnScope(scope)` for this scope. */
@@ -455,7 +472,7 @@ export const despawnsScope = <const Scope extends EntityScope.EntityScope.Any>(s
   ({ permission: "despawnsScope", values: [scope] })
 
 /** Allows `relate`, `unrelate`, and `reorderChildren` for these relations. */
-export const relates = <const Relations extends ReadonlyArray<Relation.Relation.Any>>(...relations: Relations): Permission<"relates", Relations[number]> =>
+export const relates = <const Relations extends readonly [Relation.Relation.Any, ...ReadonlyArray<Relation.Relation.Any>]>(...relations: Relations): Permission<"relates", Relations[number]> =>
   ({ permission: "relates", values: relations })
 
 type PermissionValue<Permissions, Kind extends PermissionKind> =
@@ -510,6 +527,12 @@ type Names<D> = D extends { readonly name: infer Name extends string } ? Name :
 /** Every key of every member of a union of proofs (a draft with a conditional entry is a union). */
 type AllKeys<P> = P extends unknown ? keyof P & string : never
 
+/** Relations staged on a draft need `relates`, like `commands.relate`. */
+type DraftRelationsAllowed<Relates, Declared> =
+  [Exclude<Relates, Declared>] extends [never]
+    ? unknown
+    : Fix<`${Names<Exclude<Relates, Declared>>} is related by this draft but not declared in this system's commands: add it to Game.System.relates(...)`>
+
 type DraftAllowed<P, Spawns> =
   [Exclude<AllKeys<P>, Names<Spawns>>] extends [never]
     ? unknown
@@ -523,16 +546,24 @@ type EntriesAllowed<Entries extends ReadonlyArray<readonly [ComponentDescriptor,
 type RemoveAllowed<D, Removes> =
   [D] extends [Removes] ? unknown : Fix<`${Names<D>} is not declared in this system's commands: add it to Game.System.removes(...)`>
 
-type DespawnAllowed<E, Despawns> =
-  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __proves?: (_: never) => infer Proves }
+/**
+ * Why each possible target of a despawn is not allowed (`never` when it is).
+ * Computed per member, so a target chosen from several queries
+ * (`cond ? a.entity : b.entity`) must pass for every one of them.
+ */
+type DespawnRejections<E, Despawns> =
+  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __proves?: (_: infer Proves) => void }
     ? [Extract<Proves, Despawns>] extends [never]
-      ? Fix<`despawn needs an entity from a query proving ${Names<Despawns>} (declared in despawns)`>
-      : unknown
+      ? `despawn needs an entity from a query proving ${Names<Despawns>} (declared in despawns)`
+      : never
     : E extends { readonly [spawnedTypeId]: (_: never) => infer Spawned }
       ? [Extract<Spawned, Names<Despawns>>] extends [never]
-        ? Fix<`despawn needs an entity spawned with ${Names<Despawns>} (declared in despawns)`>
-        : unknown
-      : Fix<`despawn needs an entity from a query proving ${Names<Despawns>} (declared in despawns), not a raw id: pass match.entity`>
+        ? `despawn needs an entity spawned with ${Names<Despawns>} (declared in despawns)`
+        : never
+      : `despawn needs an entity from a query proving ${Names<Despawns>} (declared in despawns), not a raw id: pass match.entity`
+
+type DespawnAllowed<E, Despawns> =
+  [DespawnRejections<E, Despawns>] extends [never] ? unknown : Fix<DespawnRejections<E, Despawns>>
 
 declare const spawnedTypeId: unique symbol
 
@@ -540,53 +571,95 @@ declare const spawnedTypeId: unique symbol
  * The id `spawn` / `spawnIn` return: an `EntityId` that also records the
  * components its draft holds in every case, so the system that queued it can
  * `despawn` it before the next `applyDeferred()` (no query can match it yet).
+ * It is valid only in the run that spawned it: kept in a closure or a
+ * resource and passed to `despawn` / `remove` in a later run, the command is
+ * skipped and reported (the `stale-target` lint). Keep the entity id or a
+ * handle and resolve it again through a query instead.
  * Stored as a plain `EntityId`, it is a raw id again.
  */
 export type SpawnedId<S extends Schema.Any, Root, Components extends string> =
   Entity.EntityId<S, Root> & { readonly [spawnedTypeId]: (_: never) => Components }
 
-/** The requirements (`[requirer, required]`) of the components in `Held` that `Held` lacks. */
-type MissingPairs<S extends Schema.Any, Held extends string> =
-  Extract<Schema.Requires<S>, readonly [Held, string]> extends infer Pair
+/** One message per missing requirement: `"Player requires Velocity"`. */
+type MissingMessages<Pairs> = Pairs extends readonly [infer From extends string, infer To extends string] ? `${From} requires ${To}` : never
+
+/** The requirements (`[requirer, required]`) of the components in `From` that `Held` lacks. */
+type MissingPairsFrom<S extends Schema.Any, From extends string, Held extends string> =
+  Extract<Schema.Requires<S>, readonly [From, string]> extends infer Pair
     ? Pair extends readonly [string, infer To extends string]
       ? To extends Held ? never : Pair
       : never
     : never
 
-/** One message per missing requirement: `"Player requires Velocity"`. */
-type MissingMessages<Pairs> = Pairs extends readonly [infer From extends string, infer To extends string] ? `${From} requires ${To}` : never
-
 /**
- * Accepts a draft holding every requirement of every component it holds.
- * Direct requirements are enough: each required component must be held
- * too, with its own requirements.
+ * The requirements a draft may break. A draft's proof is a union of
+ * alternatives when an entry is conditional, and has optional keys for
+ * spread entries: in each alternative, every component it may hold needs
+ * every component it requires surely held. Direct requirements are enough:
+ * each required component must be held too, with its own requirements.
  */
-type DraftRequirementsMet<S extends Schema.Any, Held extends string> =
-  [MissingPairs<S, Held>] extends [never]
+type DraftViolations<S extends Schema.Any, P> =
+  P extends unknown ? MissingPairsFrom<S, keyof P & string, RequiredKeys<P>> : never
+
+type DraftRequirementsMet<S extends Schema.Any, P> =
+  [DraftViolations<S, P>] extends [never]
     ? unknown
-    : Fix<`${MissingMessages<MissingPairs<S, Held>>}: add the missing entries to the draft`>
+    : Fix<`${MissingMessages<DraftViolations<S, P>>}: add the missing entries to the draft`>
 
-/** What an insert or remove target is known to hold: a query match's proof, or a `SpawnedId`'s draft. A raw id proves nothing. */
-type TargetHolds<E> =
-  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __proves?: (_: never) => infer Proves }
+/** What one possible target holds: a query match's proof, or a `SpawnedId`'s draft. A raw id proves nothing. */
+type HeldBy<E> =
+  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __proves?: (_: infer Proves) => void }
     ? Names<Proves>
     : E extends { readonly [spawnedTypeId]: (_: never) => infer Spawned extends string }
       ? Spawned
       : never
 
-/** What a remove target is known to lack: its query's `without`. */
-type TargetLacks<E> =
-  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __lacks?: (_: never) => infer Lacks }
+/** What one possible target's query proves absent: its `without`. */
+type LackedBy<E> =
+  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly __lacks?: (_: infer Lacks) => void }
     ? Names<Lacks>
     : never
 
+/** The names in `All` that some member of `E` does not hold (or lack). */
+type MissingFromHeld<E, All> = E extends unknown ? Exclude<All, HeldBy<E>> : never
+type MissingFromLacked<E, All> = E extends unknown ? Exclude<All, LackedBy<E>> : never
+
+/**
+ * What an insert or remove target is known to hold. For a target chosen
+ * from several queries (`cond ? a.entity : b.entity`), only what every one
+ * of them proves.
+ */
+type TargetHolds<E> = Exclude<HeldBy<E>, MissingFromHeld<E, HeldBy<E>>>
+
+/** What a remove target is known to lack: its query's `without` (for several queries, what all of them exclude). */
+type TargetLacks<E> = Exclude<LackedBy<E>, MissingFromLacked<E, LackedBy<E>>>
+
 type EntryNames<Entries extends ReadonlyArray<readonly [ComponentDescriptor, unknown]>> = Names<Entries[number][0]>
 
-/** Inserted components with requirements neither inserted alongside nor proven held by the target. */
+/** The names one entry surely holds: none when it is conditional between descriptors. */
+type SureEntryNames<Entry, All extends string = EntryNamesOf<Entry>> =
+  Exclude<All, Entry extends unknown ? Exclude<All, EntryNamesOf<Entry>> : never>
+type EntryNamesOf<Entry> = Entry extends readonly [infer D, unknown] ? Names<D> : never
+
+/** The names surely inserted: fixed entries, not spread or conditional ones. */
+type SurelyInserted<Entries> =
+  Entries extends readonly [infer Head, ...infer Tail]
+    ? SureEntryNames<Head> | SurelyInserted<Tail>
+    : Entries extends readonly [...infer Init, infer Last]
+      ? SureEntryNames<Last> | SurelyInserted<Init>
+      : never
+
+/**
+ * Inserted components (any entry may be one) with requirements neither
+ * surely inserted alongside nor proven held by the target.
+ */
+type InsertViolations<S extends Schema.Any, E, Entries extends ReadonlyArray<readonly [ComponentDescriptor, unknown]>> =
+  MissingPairsFrom<S, EntryNames<Entries>, SurelyInserted<Entries> | TargetHolds<E>>
+
 type InsertRequirementsMet<S extends Schema.Any, E, Entries extends ReadonlyArray<readonly [ComponentDescriptor, unknown]>> =
-  [MissingPairs<S, EntryNames<Entries> | TargetHolds<E>> & readonly [EntryNames<Entries>, string]] extends [never]
+  [InsertViolations<S, E, Entries>] extends [never]
     ? unknown
-    : Fix<`${MissingMessages<MissingPairs<S, EntryNames<Entries> | TargetHolds<E>> & readonly [EntryNames<Entries>, string]>}: insert it in the same call, or pass match.entity from a query that proves it`>
+    : Fix<`${MissingMessages<InsertViolations<S, E, Entries>>}: insert it in the same call, or pass match.entity from a query that proves it`>
 
 /**
  * Removing `Removed` is sound when every component that requires one of
@@ -606,13 +679,16 @@ type RemoveViolations<S extends Schema.Any, E, Removed extends string> =
 type RemoveRequirementsMet<S extends Schema.Any, E, Removed extends string> =
   [RemoveViolations<S, E, Removed>] extends [never] ? unknown : Fix<RemoveViolations<S, E, Removed>>
 
-/** A remove target: `match.entity`, or the id `spawn` returned in this run; never a raw id. */
-type RemoveTargetAllowed<S extends Schema.Any, Root, E> =
+/** A remove target: `match.entity`, or the id `spawn` returned in this run; never a raw id, not even as one of several. */
+type RemoveTargetRejections<S extends Schema.Any, Root, E> =
   E extends { readonly kind: "EntityRef" | "EntityMut"; readonly id: Entity.EntityId<S, Root> }
-    ? unknown
+    ? never
     : E extends SpawnedId<S, Root, string>
-      ? unknown
-      : Fix<"remove needs an entity from a query (pass match.entity) or the id spawn returned in this run, not a raw id">
+      ? never
+      : "remove needs an entity from a query (pass match.entity) or the id spawn returned in this run, not a raw id"
+
+type RemoveTargetAllowed<S extends Schema.Any, Root, E> =
+  [RemoveTargetRejections<S, Root, E>] extends [never] ? unknown : Fix<RemoveTargetRejections<S, Root, E>>
 
 /** The transitive closure of the names `N` require (cycles stop). */
 type RequiredClosure<Pairs extends RequirementPair, N extends string, Seen extends string = never> =
@@ -657,7 +733,8 @@ type HeldNames<P> = Exclude<AllKeys<P>, MissingSomewhere<P, AllKeys<P>>>
  * `spawn` needs `Game.System.spawns(...)` listing every component of the
  * draft, `insert` needs `inserts`, `remove` needs `removes`, `despawn` needs
  * `despawns` and an entity from a query proving one of them, `despawnScope`
- * needs `despawnsScope`, and relation edits need `relates`.
+ * needs `despawnsScope`, and relation edits need `relates`, including
+ * relations a spawned draft stages with `Game.Command.relate(...)`.
  *
  * Resource and event writes are not commands: they go through the
  * `writeResource(...)` / `writeEvent(...)` access a system declares.
@@ -678,19 +755,23 @@ export interface CommandsApi<
    * The draft must hold every component its components require
    * (`Schema.requires`); drafts are checked here, so a partial draft built
    * with `Game.Command.spawn(...)` and completed with `extend(...)` is fine.
+   * A component the draft may hold (a conditional or spread entry) needs
+   * what it requires surely held.
    */
   readonly spawn: [Spawns] extends [never]
     ? MethodNotDeclared<"spawn", "spawns">
-    : <P extends Entity.ComponentProof>(draft: Entity.EntityDraft<S, P, Root> & DraftAllowed<P, Spawns> & DraftRequirementsMet<S, HeldNames<P>>) => SpawnedId<S, Root, HeldNames<P>>
+    : <P extends Entity.ComponentProof, R = never>(
+        draft: Entity.EntityDraft<S, P, Root, R> & DraftAllowed<P, Spawns> & DraftRequirementsMet<S, P> & DraftRelationsAllowed<R, Relates>
+      ) => SpawnedId<S, Root, HeldNames<P>>
   /**
    * Queues an entity spawn owned by one lifetime scope (removed together
    * with `despawnScope(...)`). The draft is checked like `spawn(...)`.
    */
   readonly spawnIn: [Spawns] extends [never]
     ? MethodNotDeclared<"spawnIn", "spawns">
-    : <P extends Entity.ComponentProof>(
+    : <P extends Entity.ComponentProof, R = never>(
         scope: EntityScope.EntityScope<string, Root>,
-        draft: Entity.EntityDraft<S, P, Root> & DraftAllowed<P, Spawns> & DraftRequirementsMet<S, HeldNames<P>>
+        draft: Entity.EntityDraft<S, P, Root, R> & DraftAllowed<P, Spawns> & DraftRequirementsMet<S, P> & DraftRelationsAllowed<R, Relates>
       ) => SpawnedId<S, Root, HeldNames<P>>
   /**
    * Queues component inserts (or replacements) on an existing entity, applied
@@ -782,8 +863,8 @@ export interface CommandsApi<
 
 /** The command queue the runtime gives each system: every command, unchecked, and `flush`. */
 export interface CommandQueue<S extends Schema.Any, Root = unknown> {
-  readonly spawn: (draft: Entity.EntityDraft<S, any, Root>) => Entity.EntityId<S, Root>
-  readonly spawnIn: (scope: EntityScope.EntityScope<string, Root>, draft: Entity.EntityDraft<S, any, Root>) => Entity.EntityId<S, Root>
+  readonly spawn: (draft: Entity.EntityDraft<S, any, Root, any>) => Entity.EntityId<S, Root>
+  readonly spawnIn: (scope: EntityScope.EntityScope<string, Root>, draft: Entity.EntityDraft<S, any, Root, any>) => Entity.EntityId<S, Root>
   readonly insert: (entity: Entity.EntityId<S, Root> | { readonly id: Entity.EntityId<S, Root> }, ...entries: ReadonlyArray<SchemaEntry<S>>) => Entity.EntityId<S, Root>
   readonly despawn: (entity: Entity.EntityId<S, Root> | { readonly id: Entity.EntityId<S, Root> }) => void
   readonly despawnScope: (scope: EntityScope.EntityScope<string, Root>) => void
@@ -813,10 +894,17 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
    * the system effect completes.
    */
   const queue: Array<DeferredCommand<S>> = []
+  /**
+   * Ids this run spawned: the only numeric targets `despawn` and `remove`
+   * accept. Their types reject raw ids, so any other number is an id kept
+   * from an earlier run (or erased types), and proves nothing now.
+   */
+  const spawnedThisRun = new Set<number>()
 
   return {
     spawn(draft) {
       const id = allocateId()
+      spawnedThisRun.add(id)
       queue.push({
         tag: "spawn",
         apply(world) {
@@ -830,6 +918,7 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
     },
     spawnIn(scope, draft) {
       const id = allocateId()
+      spawnedThisRun.add(id)
       queue.push({
         tag: "spawnIn",
         apply(world) {
@@ -854,10 +943,12 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
     },
     despawn(entity) {
       const id = typeof entity === "object" ? entity.id : entity
+      const stale = typeof entity !== "object" && !spawnedThisRun.has(id)
       queue.push({
         tag: "despawn",
         apply(world) {
-          world.destroyEntity(id)
+          if (stale) world.reportStaleTarget("despawn", id)
+          else world.destroyEntity(id)
         }
       })
     },
@@ -871,10 +962,12 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
     },
     remove(target, ...descriptors) {
       const entity = typeof target === "object" ? target.id : target
+      const stale = typeof target !== "object" && !spawnedThisRun.has(entity)
       queue.push({
         tag: "remove",
         apply(world) {
-          world.removeComponents(entity, descriptors)
+          if (stale) world.reportStaleTarget("remove", entity)
+          else world.removeComponents(entity, descriptors)
         }
       })
       return entity
@@ -904,6 +997,7 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
       })
     },
     flush() {
+      spawnedThisRun.clear()
       return queue.splice(0, queue.length)
     }
   }

package/src/Debug.ts

@@ -35,7 +35,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } })
+ * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } }).value
  * runtime.debug.nameSchedules({ setup: setupSchedule, update: updateSchedule })
  *
  * const stop = runtime.debug.observe((event) => {
@@ -206,7 +206,11 @@ export interface SystemDescription {
    * names for despawnsScope, relation names for relates.
    */
   readonly commands: CommandPermissions
-  /** Run conditions, rendered, for example `stateChanged(Game/Flow)`. */
+  /**
+   * Run conditions, rendered, for example `stateChanged(Game/Flow)`. A system
+   * placed under several `Schedule.when` / `pauseWhen` groups is described
+   * once, with the conditions of every placement.
+   */
   readonly when: ReadonlyArray<string>
   /** Pause conditions, rendered: while one fails the system waits and holds its stream entries. */
   readonly pauseWhen: ReadonlyArray<string>
@@ -243,7 +247,12 @@ export interface ScheduleDescription {
  * `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
+ * because they would have broken a `Schema.requires` requirement,
+ * `next-state-replaced` lists next states one system queued and another
+ * replaced with a different value before the marker (the last wins),
+ * `stale-target` lists `despawn` / `remove` commands given a `SpawnedId`
+ * kept from an earlier run (skipped), `stream-loss-unread` lists stream
+ * readers that never check `lagged()` and lost entries (or are paused), so
  * describe after the game has run for a while. `scope-trigger-never-applied`
  * also reads which machines the runtime provides.
  */
@@ -260,6 +269,9 @@ export interface Lint {
     | "this-tick-order"
     | "command-permission-unused"
     | "requirement-violated"
+    | "next-state-replaced"
+    | "stale-target"
+    | "stream-loss-unread"
     | "scope-trigger-never-applied"
   readonly message: string
   readonly subject: string
@@ -430,6 +442,21 @@ export type Effect =
       readonly component: string
       readonly missing: string
     }
+  /** A `despawn` / `remove` skipped because it was given a `SpawnedId` from an earlier run. */
+  | { readonly kind: "staleTarget"; readonly entity: number; readonly command: StaleTarget["command"] }
+
+/**
+ * A next state one system queued and another replaced with a different value
+ * before the same `applyStateTransitions(...)`: the `next-state-replaced`
+ * lint. Only the last value is committed.
+ */
+export interface NextStateReplacement {
+  readonly machine: string
+  readonly replaced: { readonly system: string; readonly value: Machine.StateValue }
+  readonly by: { readonly system: string; readonly value: Machine.StateValue }
+  /** How many times it happened. */
+  readonly count: number
+}
 
 /**
  * Commands of one system skipped because applying them would have left a
@@ -449,6 +476,37 @@ export interface RequirementViolation {
   readonly count: number
 }
 
+/**
+ * Commands of one system skipped because they were given a `SpawnedId` kept
+ * from an earlier run, whose entity may since have been despawned and its id
+ * reused: the `stale-target` lint.
+ */
+export interface StaleTarget {
+  readonly system: string
+  readonly command: "despawn" | "remove"
+  /** The last entity id it happened to. */
+  readonly entity: number
+  /** How many commands were skipped this way. */
+  readonly count: number
+}
+
+/**
+ * One system's reads of one stream (events, transition events, removed,
+ * despawned, relation failures) on a debug runtime: the
+ * `stream-loss-unread` lint.
+ */
+export interface StreamLoss {
+  readonly system: string
+  /** The stream, as `events Hit`, `removed Sprite`, `despawned`, ... */
+  readonly stream: string
+  /** Runs that read it after entries were dropped before they were read. */
+  readonly lostRuns: number
+  /** Whether the system called `lagged()` on it. */
+  readonly checksLagged: boolean
+  /** Whether the system has `pauseWhen` conditions (a long pause can drop entries). */
+  readonly paused: boolean
+}
+
 export interface AppliedCommand {
   readonly tag: string
   readonly system: string
@@ -629,9 +687,3 @@ export interface Option {
 export interface Member<S extends Schema.Any, Root> {
   readonly debug: Handle<S, Root>
 }
-
-/** Resolves the extra runtime member for a `debug` option type. */
-export type MemberFor<Enabled, S extends Schema.Any, Root> =
-  [Enabled] extends [true] ? Member<S, Root>
-  : [Enabled] extends [false | undefined] ? {}
-  : Partial<Member<S, Root>>