@typeonce/ritmo 0.7.0 → 0.9.0

package/src/Command.ts

@@ -65,7 +65,8 @@ 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 { Schema } from "./Schema.ts"
+import type { ReadonlyValue } from "./Query.ts"
+import type { RequirementPair, Schema } from "./Schema.ts"
 
 /**
  * Type-level helpers for staged entity construction.
@@ -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.
@@ -206,9 +214,10 @@ export type DeferredCommand<S extends Schema.Any> = {
 export interface InternalWorld<S extends Schema.Any> {
   /**
    * Creates the entity for an id reserved by `commands.spawn(...)` with its
-   * staged components.
+   * staged components. Returns `false`, creating nothing, when the
+   * components break a `Schema.requires` requirement.
    */
-  readonly spawnEntity: (id: Entity.EntityId<S, any>, components: ReadonlyArray<Entity.StagedComponent>) => void
+  readonly spawnEntity: (id: Entity.EntityId<S, any>, components: ReadonlyArray<Entity.StagedComponent>) => boolean
   /**
    * Removes an entity and its outgoing and incoming relations.
    */
@@ -225,13 +234,21 @@ export interface InternalWorld<S extends Schema.Any> {
    */
   readonly destroyEntityScope: (scope: EntityScope.EntityScope.Any) => void
   /**
-   * Removes a component from a live entity.
+   * Removes components from a live entity, all or none: nothing is removed
+   * when that would leave a component without one it requires.
+   */
+  readonly removeComponents: (id: Entity.EntityId<S, any>, descriptors: ReadonlyArray<Descriptor<"component", string, any>>) => void
+  /**
+   * Inserts or replaces components on a live entity, all or none: nothing is
+   * written when an inserted component would miss one it requires.
    */
-  readonly removeComponent: (id: Entity.EntityId<S, any>, descriptor: Descriptor<"component", string, any>) => void
+  readonly insertComponents: (id: Entity.EntityId<S, any>, entries: ReadonlyArray<Entity.StagedComponent>) => void
   /**
-   * Inserts or replaces a component on a live entity.
+   * 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 writeComponent: (id: Entity.EntityId<S, any>, descriptor: Descriptor<"component", string, any>, value: unknown) => void
+  readonly reportStaleTarget: (command: "despawn" | "remove", id: Entity.EntityId<S, any>) => void
   /**
    * Attempts to attach one relation edge between two live entities.
    */
@@ -267,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
@@ -313,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`
@@ -364,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
@@ -396,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,
     {
@@ -424,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 })
 
 /**
@@ -432,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 })
 
 /**
@@ -444,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. */
@@ -452,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> =
@@ -507,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
@@ -520,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
 
@@ -537,11 +571,153 @@ 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 }
 
+/** 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
+
+/**
+ * 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 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<DraftViolations<S, P>>}: add the missing entries to the draft`>
+
+/** 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 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]>
+
+/** 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]>> =
+  [InsertViolations<S, E, Entries>] extends [never]
+    ? unknown
+    : 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
+ * them is removed in the same call or proven absent by the target's query
+ * (`without`): otherwise the entity may keep a requirer without its
+ * requirement.
+ */
+type RemoveViolations<S extends Schema.Any, E, Removed extends string> =
+  Extract<Schema.Requires<S>, readonly [string, Removed]> extends infer Pair
+    ? Pair extends readonly [infer From extends string, infer To extends string]
+      ? From extends Removed | TargetLacks<E>
+        ? never
+        : `${To} is required by ${From}: remove ${From} in the same call, or match the entity with a query that has without: [${From}]`
+      : never
+    : never
+
+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, 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> }
+    ? never
+    : E extends SpawnedId<S, Root, string>
+      ? 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> =
+  [Exclude<N, Seen>] extends [never]
+    ? Seen
+    : RequiredClosure<Pairs, Extract<Pairs, readonly [Exclude<N, Seen>, string]>[1], Seen | N>
+
+/**
+ * The component descriptors that `Names` require, transitively
+ * (`Schema.requires`): what `Game.System.spawns(...)` also allows.
+ */
+export type RequiredDescriptors<S extends Schema.Any, Names extends string> =
+  // Non-literal names (an unresolved descriptor, alone or next to known ones) would never
+  // close: leave the error to the descriptor.
+  0 extends 1 & Names
+    ? never
+    : string extends Names
+    ? never
+    : [Extract<Schema.Requires<S>, readonly [Names, string]>] extends [never]
+    ? never
+    : Extract<Schema.ComponentDescriptor<S>, { readonly name: Exclude<RequiredClosure<Schema.Requires<S>, Names>, Names> }>
+
+type SchemaComponent<S extends Schema.Any> = Extract<Schema.Components<S>[keyof Schema.Components<S>], ComponentDescriptor>
+
+/** An entity a system has proven something about: `match.entity`, or the id `spawn` returned. */
+type EntityTarget<S extends Schema.Any, Root> =
+  | { readonly kind: "EntityRef" | "EntityMut"; readonly id: Entity.EntityId<S, Root> }
+  | SpawnedId<S, Root, string>
+
 /** The keys every member of a union of proofs requires (what a draft holds in every case). */
 type RequiredKeys<P> = P extends unknown ? { [K in keyof P]-?: {} extends Pick<P, K> ? never : K }[keyof P] & string : never
 type MissingSomewhere<P, All> = P extends unknown ? Exclude<All, RequiredKeys<P>> : never
@@ -557,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.
@@ -574,33 +751,48 @@ export interface CommandsApi<
 > {
   /**
    * Queues a staged entity for spawning and returns its stable runtime id.
+   *
+   * 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>) => 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(...)`).
+   * 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>
+        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
    * at the next `applyDeferred()`. To change a value now, on an entity you
-   * matched, write through a query (`Game.Query.write`) instead.
+   * matched, write through a query (`Game.Query.write`) instead; components
+   * declared `immutable: true` change only through `insert`.
+   *
+   * Pass `match.entity`: its query proves what the entity holds, which must
+   * cover what the inserted components require (`Schema.requires`) together
+   * with the entries inserted in the same call. The id `spawn` returned in
+   * this run proves its draft. A raw `EntityId` proves nothing, so it only
+   * inserts components without requirements.
    *
    * Entries must already be valid; validate raw input with
    * `Game.Command.entryRaw(...)` first.
    */
   readonly insert: [Inserts] extends [never]
     ? MethodNotDeclared<"insert", "inserts">
-    : <const Entries extends ReadonlyArray<SchemaEntry<S>>>(
-        entity: Entity.EntityId<S, Root>,
-        ...entries: Entries & EntriesAllowed<Entries, Inserts>
+    : <const E extends Entity.EntityId<S, Root> | EntityTarget<S, Root>, const Entries extends ReadonlyArray<SchemaEntry<S>>>(
+        entity: E,
+        ...entries: Entries & EntriesAllowed<Entries, Inserts> & InsertRequirementsMet<S, E, Entries>
       ) => Entity.EntityId<S, Root>
   /**
    * Queues an entity removal. A despawned entity stays visible to queries
@@ -613,7 +805,7 @@ export interface CommandsApi<
    */
   readonly despawn: [Despawns] extends [never]
     ? MethodNotDeclared<"despawn", "despawns">
-    : <const E>(entity: E & DespawnAllowed<E, Despawns>) => void
+    : <const E>(entity: unknown extends DespawnAllowed<E, Despawns> ? E : DespawnAllowed<E, Despawns>) => void
   /**
    * Queues removal of every entity owned by one lifetime scope.
    */
@@ -621,13 +813,22 @@ export interface CommandsApi<
     ? MethodNotDeclared<"despawnScope", "despawnsScope">
     : (scope: Scopes) => void
   /**
-   * Queues a component removal on an existing entity.
+   * Queues the removal of one or more components from an existing entity,
+   * applied together at the next `applyDeferred()`.
+   *
+   * Pass `match.entity` from a query, or the id `spawn` returned in this run;
+   * never a raw id. A component another one requires (`Schema.requires`) can
+   * only go together with that requirer, in the same call, or from an
+   * entity whose query has `without: [Requirer]`.
    */
   readonly remove: [Removes] extends [never]
     ? MethodNotDeclared<"remove", "removes">
-    : <D extends Extract<Schema.Components<S>[keyof Schema.Components<S>], ComponentDescriptor>>(
-        entity: Entity.EntityId<S, Root>,
-        descriptor: D & RemoveAllowed<D, Removes>
+    : <
+        const E,
+        const Ds extends readonly [SchemaComponent<S>, ...Array<SchemaComponent<S>>]
+      >(
+        entity: unknown extends RemoveTargetAllowed<S, Root, E> ? E : RemoveTargetAllowed<S, Root, E>,
+        ...descriptors: Ds & RemoveAllowed<Ds[number], Removes> & RemoveRequirementsMet<S, E, Names<Ds[number]>>
       ) => Entity.EntityId<S, Root>
   /**
    * Queues one live relation mutation for deferred application.
@@ -662,12 +863,12 @@ 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 insert: (entity: Entity.EntityId<S, Root>, ...entries: ReadonlyArray<SchemaEntry<S>>) => 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
-  readonly remove: (entity: Entity.EntityId<S, Root>, descriptor: ComponentDescriptor) => Entity.EntityId<S, Root>
+  readonly remove: (entity: Entity.EntityId<S, Root> | { readonly id: Entity.EntityId<S, Root> }, ...descriptors: ReadonlyArray<ComponentDescriptor>) => Entity.EntityId<S, Root>
   readonly relate: (entity: Entity.EntityId<S, Root>, relation: Relation.Relation.Any, target: Entity.EntityId<S, Root>) => void
   readonly unrelate: (entity: Entity.EntityId<S, Root>, relation: Relation.Relation.Any) => void
   readonly reorderChildren: (entity: Entity.EntityId<S, Root>, relation: Relation.Relation.Hierarchy, children: ReadonlyArray<Entity.EntityId<S, Root>>) => void
@@ -693,14 +894,21 @@ 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) {
-          world.spawnEntity(id, draft.components)
+          if (!world.spawnEntity(id, draft.components)) return
           for (const stagedRelation of draft.relations) {
             world.tryRelate(id, stagedRelation.relation, stagedRelation.target)
           }
@@ -710,10 +918,11 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
     },
     spawnIn(scope, draft) {
       const id = allocateId()
+      spawnedThisRun.add(id)
       queue.push({
         tag: "spawnIn",
         apply(world) {
-          world.spawnEntity(id, draft.components)
+          if (!world.spawnEntity(id, draft.components)) return
           world.assignEntityScope(id, scope)
           for (const stagedRelation of draft.relations) {
             world.tryRelate(id, stagedRelation.relation, stagedRelation.target)
@@ -722,23 +931,24 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
       })
       return id
     },
-    insert(entity, ...entries) {
+    insert(target, ...entries) {
+      const entity = typeof target === "object" ? target.id : target
       queue.push({
         tag: "insert",
         apply(world) {
-          for (const [descriptor, value] of entries) {
-            world.writeComponent(entity, descriptor, value)
-          }
+          world.insertComponents(entity, entries)
         }
       })
       return entity
     },
     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)
         }
       })
     },
@@ -750,11 +960,14 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
         }
       })
     },
-    remove(entity, descriptor) {
+    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.removeComponent(entity, descriptor)
+          if (stale) world.reportStaleTarget("remove", entity)
+          else world.removeComponents(entity, descriptors)
         }
       })
       return entity
@@ -784,6 +997,7 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
       })
     },
     flush() {
+      spawnedThisRun.clear()
       return queue.splice(0, queue.length)
     }
   }

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. */