@typeonce/ritmo 0.6.0 → 0.8.0

package/src/Command.ts

@@ -65,7 +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 { Schema } from "./Schema.ts"
+import type { RequirementPair, Schema } from "./Schema.ts"
 
 /**
  * Type-level helpers for staged entity construction.
@@ -125,7 +125,7 @@ export type SchemaEntry<S extends Schema.Any> = EntryOf<SchemaComponentDescripto
 
 /**
  * One entry accepted by `spawn(...)` and `insert(...)`: a plain descriptor/value
- * pair, or a `Result` of one (from `entryRaw(...)` or `entryResult(...)`).
+ * pair, or a `Result` of one (from `entryRaw(...)`).
  */
 export type SpawnEntry<S extends Schema.Any> = SchemaEntry<S> | Result.Result<SchemaEntry<S>, any>
 
@@ -142,12 +142,21 @@ type EntryValue<T> =
 export type FoldEntries<
   Entries extends ReadonlyArray<SpawnEntry<any>>,
   P extends Entity.ComponentProof = {}
-> = Entries extends readonly [
-  infer Head extends SpawnEntry<any>,
-  ...infer Tail extends Array<SpawnEntry<any>>
-]
-  ? FoldEntries<Tail, Draft.InsertEntry<P, EntryValue<Head>>>
-  : P
+> = 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 Array<SpawnEntry<any>>
+    ]
+    ? FoldEntries<Tail, Draft.InsertEntry<P, EntryValue<Head>>>
+    : P
+
+/** The proof of entries that may each be present: every component they can hold, optional. */
+type MaybeEntries<Entry> = {
+  readonly [E in Entry as E extends readonly [infer D extends Descriptor<"component", string, any>, unknown] ? Descriptor.Name<D> : never]?:
+    E extends readonly [infer D extends Descriptor<"component", string, any>, unknown] ? Descriptor.Value<D> : never
+}
 
 /**
  * Per-entry failures, aligned with the entries: `null` for entries that
@@ -197,9 +206,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.
    */
@@ -216,13 +226,15 @@ 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 removeComponent: (id: Entity.EntityId<S, any>, descriptor: Descriptor<"component", string, any>) => void
+  readonly removeComponents: (id: Entity.EntityId<S, any>, descriptors: ReadonlyArray<Descriptor<"component", string, any>>) => void
   /**
-   * Inserts or replaces a component on a live entity.
+   * Inserts or replaces components on a live entity, all or none: nothing is
+   * written when an inserted component would miss one it requires.
    */
-  readonly writeComponent: (id: Entity.EntityId<S, any>, descriptor: Descriptor<"component", string, any>, value: unknown) => void
+  readonly insertComponents: (id: Entity.EntityId<S, any>, entries: ReadonlyArray<Entity.StagedComponent>) => void
   /**
    * Attempts to attach one relation edge between two live entities.
    */
@@ -262,20 +274,15 @@ export const entry = <D extends Descriptor<"component", string, any>>(
 ): Entry<D> => [descriptor, value]
 
 /**
- * Lifts an already validated value into an entry result, keeping the failure
- * visible to `spawn(...)` / `insert(...)`.
- */
-export const entryResult = <D extends Descriptor<"component", string, any>, Error>(
-  descriptor: D,
-  result: Result.Result<Descriptor.Value<D>, Error>
-): Result.Result<Entry<D>, Error> =>
-  result.ok
-    ? Result.success([descriptor, result.value] as Entry<D>)
-    : Result.failure(result.error)
-
-/**
- * Validates raw input through a constructed descriptor and returns an entry
- * result.
+ * Validates raw input through a constructed descriptor's own validator and
+ * returns an entry result for `spawn(...)` / `insert(...)`.
+ *
+ * This is the one way to put unvalidated data on an entity: the descriptor
+ * owns its validator (`Descriptor.ConstructedComponent(...)`, built with
+ * `Decode` or `Descriptor.fromStandardSchema`). Values that are already
+ * valid use a plain `[Descriptor, value]` entry instead. To validate authored
+ * constants once at module load, call the constructor (`Vector2.result(...)`)
+ * and keep the carried value.
  *
  * @example
  * ```ts
@@ -290,15 +297,22 @@ export const entryResult = <D extends Descriptor<"component", string, any>, Erro
 export const entryRaw = <D extends DescriptorModule.ConstructedDescriptor<"component", string, any, any, any>>(
   descriptor: D,
   raw: Descriptor.Raw<D>
-): Result.Result<Entry<D>, Descriptor.ConstructionError<D>> =>
-  entryResult(descriptor, DescriptorModule.constructorOf(descriptor).result(raw) as Result.Result<Descriptor.Value<D>, Descriptor.ConstructionError<D>>)
+): Result.Result<Entry<D>, Descriptor.ConstructionError<D>> => {
+  const validated = DescriptorModule.constructorOf(descriptor).result(raw) as Result.Result<Descriptor.Value<D>, Descriptor.ConstructionError<D>>
+  return validated.ok
+    ? Result.success([descriptor, validated.value] as Entry<D>)
+    : Result.failure(validated.error)
+}
 
 /**
- * Adds entries to a draft. Plain entries return the new draft; if any entry is
- * a `Result`, the draft is returned as a `Result` whose error lists every
- * entry's failure (or `null`).
+ * Adds entries to a draft, a value not yet spawned. Plain entries return the
+ * new draft; if any entry is a `Result`, the draft is returned as a `Result`
+ * whose error lists every entry's failure (or `null`).
+ *
+ * Use this while building what a spawn will hold. Use `commands.insert` to
+ * add or replace components on an entity that already exists.
  */
-export const insert = <
+export const extend = <
   S extends Schema.Any,
   P extends Entity.ComponentProof,
   Root,
@@ -399,78 +413,384 @@ export const relate = <
     }
   ])
 
+/** One permission of `Game.System.commands(...)`: a kind of command, and what it may touch. */
+export interface Permission<out Kind extends PermissionKind, out Value> {
+  readonly permission: Kind
+  readonly values: ReadonlyArray<Value>
+}
+
+export type PermissionKind = "spawns" | "inserts" | "removes" | "despawns" | "despawnsScope" | "relates"
+
+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]> =>
+  ({ permission: "spawns", values: components })
+
+/**
+ * Allows `insert(entity, [X, value])` with `X` among `components`: add or
+ * 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]> =>
+  ({ 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]> =>
+  ({ permission: "removes", values: components })
+
+/**
+ * Allows `despawn(entity)` where `entity` comes from a query match proving one
+ * 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]> =>
+  ({ permission: "despawns", values: components })
+
+/** Allows `despawnScope(scope)` for this scope. */
+export const despawnsScope = <const Scope extends EntityScope.EntityScope.Any>(scope: Scope): Permission<"despawnsScope", Scope> =>
+  ({ 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]> =>
+  ({ permission: "relates", values: relations })
+
+type PermissionValue<Permissions, Kind extends PermissionKind> =
+  Permissions extends Permission<Kind, infer Value> ? Value : never
+
+/**
+ * The commands a system may queue, declared in its spec as
+ * `commands: Game.System.commands(...)`. Without it, the system has no
+ * `commands`.
+ */
+export interface CommandAccess<
+  out Spawns = never,
+  out Inserts = never,
+  out Removes = never,
+  out Despawns = never,
+  out Scopes = never,
+  out Relates = never
+> {
+  readonly kind: "commands"
+  readonly permissions: ReadonlyArray<Permission<PermissionKind, unknown>>
+  readonly __permissions?: (_: never) => readonly [Spawns, Inserts, Removes, Despawns, Scopes, Relates]
+}
+
+export namespace CommandAccess {
+  export type Any = CommandAccess<any, any, any, any, any, any>
+}
+
+/** Declares the commands a system may queue; see the permission builders. */
+export const commands = <const Permissions extends ReadonlyArray<Permission<PermissionKind, unknown>>>(
+  ...permissions: Permissions
+): CommandAccess<
+  PermissionValue<Permissions[number], "spawns">,
+  PermissionValue<Permissions[number], "inserts">,
+  PermissionValue<Permissions[number], "removes">,
+  PermissionValue<Permissions[number], "despawns">,
+  PermissionValue<Permissions[number], "despawnsScope">,
+  PermissionValue<Permissions[number], "relates">
+> => ({ kind: "commands", permissions })
+
+/** The `commands` of a system that declares none. */
+export type NotDeclared =
+  "commands are not declared for this system: add commands: Game.System.commands(...) to its spec, with the permissions it needs (spawns, inserts, removes, despawns, despawnsScope, relates)"
+
+/** A method whose permission is not declared: any call fails with an argument error naming the fix. */
+type MethodNotDeclared<Method extends string, Builder extends string> =
+  (...fix: ReadonlyArray<`${Method} is not declared in this system's commands: add Game.System.${Builder}(...) to Game.System.commands(...)`>) => never
+
+type Fix<Message extends string> = { readonly __fixCommands__: Message }
+
+type Names<D> = D extends { readonly name: infer Name extends string } ? Name : never
+
+/** 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
+
+type DraftAllowed<P, Spawns> =
+  [Exclude<AllKeys<P>, Names<Spawns>>] extends [never]
+    ? unknown
+    : Fix<`${Exclude<AllKeys<P>, Names<Spawns>>} is not declared in this system's commands: add it to Game.System.spawns(...)`>
+
+type EntriesAllowed<Entries extends ReadonlyArray<readonly [ComponentDescriptor, unknown]>, Inserts> =
+  [Exclude<Entries[number][0], Inserts>] extends [never]
+    ? unknown
+    : Fix<`${Names<Exclude<Entries[number][0], Inserts>>} is not declared in this system's commands: add it to Game.System.inserts(...)`>
+
+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 }
+    ? [Extract<Proves, Despawns>] extends [never]
+      ? Fix<`despawn needs an entity from a query proving ${Names<Despawns>} (declared in despawns)`>
+      : unknown
+    : 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`>
+
+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).
+ * 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
+    ? 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.
+ */
+type DraftRequirementsMet<S extends Schema.Any, Held extends string> =
+  [MissingPairs<S, Held>] extends [never]
+    ? unknown
+    : Fix<`${MissingMessages<MissingPairs<S, Held>>}: 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 }
+    ? 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 }
+    ? Names<Lacks>
+    : never
+
+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. */
+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]
+    ? 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`>
+
+/**
+ * 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. */
+type RemoveTargetAllowed<S extends Schema.Any, Root, E> =
+  E extends { readonly kind: "EntityRef" | "EntityMut"; readonly id: Entity.EntityId<S, Root> }
+    ? unknown
+    : 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">
+
+/** 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>
+
 /**
- * Public command API exposed to systems.
+ * 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
+type HeldNames<P> = Exclude<AllKeys<P>, MissingSomewhere<P, AllKeys<P>>>
+
+/**
+ * The command API a system gets for its declared permissions. Commands are
+ * the structural mutation entrypoint: spawns, inserts, removals, despawns,
+ * and relation edits. They are queued in order and applied only at the next
+ * `applyDeferred()` (or `applyStateTransitions(...)`) schedule step.
  *
- * Commands are the structural mutation entrypoint: spawns, inserts, removals,
- * despawns, and relation edits. They are queued in order and applied only at
- * the next `applyDeferred()` (or `applyStateTransitions(...)`) schedule step.
+ * Each method exists only with its permission, and only for what it names:
+ * `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`.
  *
  * Resource and event writes are not commands: they go through the
  * `writeResource(...)` / `writeEvent(...)` access a system declares.
  */
-export interface CommandsApi<S extends Schema.Any, Root = unknown> {
+export interface CommandsApi<
+  S extends Schema.Any,
+  Root = unknown,
+  Spawns = never,
+  Inserts = never,
+  Removes = never,
+  Despawns = never,
+  Scopes = never,
+  Relates = never
+> {
   /**
    * 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.
    */
-  readonly spawn: <P extends Entity.ComponentProof>(draft: Entity.EntityDraft<S, P, Root>) => Entity.EntityId<S, Root>
+  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>>
   /**
-   * Queues an entity spawn owned by one lifetime scope.
-   *
-   * Scoped entities can later be removed together with `despawnScope(...)`.
+   * Queues an entity spawn owned by one lifetime scope (removed together
+   * with `despawnScope(...)`). The draft is checked like `spawn(...)`.
    */
-  readonly spawnIn: <P extends Entity.ComponentProof>(
-    scope: EntityScope.EntityScope<string, Root>,
-    draft: Entity.EntityDraft<S, P, Root>
-  ) => Entity.EntityId<S, Root>
+  readonly spawnIn: [Spawns] extends [never]
+    ? MethodNotDeclared<"spawnIn", "spawns">
+    : <P extends Entity.ComponentProof>(
+        scope: EntityScope.EntityScope<string, Root>,
+        draft: Entity.EntityDraft<S, P, Root> & DraftAllowed<P, Spawns> & DraftRequirementsMet<S, HeldNames<P>>
+      ) => SpawnedId<S, Root, HeldNames<P>>
   /**
-   * Queues component inserts (or replacements) on an existing entity.
+   * 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; 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: (
-    entity: Entity.EntityId<S, Root>,
-    ...entries: ReadonlyArray<SchemaEntry<S>>
-  ) => Entity.EntityId<S, Root>
+  readonly insert: [Inserts] extends [never]
+    ? MethodNotDeclared<"insert", "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.
+   * Queues an entity removal. A despawned entity stays visible to queries
+   * until the next `applyDeferred()`, and despawns never count as writers for
+   * `Game.System.thisTick` query reads.
+   *
+   * Pass `match.entity` from a query proving one of the `despawns`
+   * components, or the id `spawn` returned in this run (it holds its draft's
+   * components); never a raw id.
    */
-  readonly despawn: (entity: Entity.EntityId<S, Root>) => void
+  readonly despawn: [Despawns] extends [never]
+    ? MethodNotDeclared<"despawn", "despawns">
+    : <const E>(entity: unknown extends DespawnAllowed<E, Despawns> ? E : DespawnAllowed<E, Despawns>) => void
   /**
    * Queues removal of every entity owned by one lifetime scope.
    */
-  readonly despawnScope: (scope: EntityScope.EntityScope<string, Root>) => void
+  readonly despawnScope: [Scopes] extends [never]
+    ? 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: <D extends Extract<Schema.Components<S>[keyof Schema.Components<S>], Descriptor<"component", string, any>>>(
-    entity: Entity.EntityId<S, Root>,
-    descriptor: D
-  ) => Entity.EntityId<S, Root>
+  readonly remove: [Removes] extends [never]
+    ? MethodNotDeclared<"remove", "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.
    */
-  readonly relate: <R extends Extract<Schema.Relations<S>[keyof Schema.Relations<S>], Relation.Relation.Any>>(
-    entity: Entity.EntityId<S, Root>,
-    relation: R,
-    target: Entity.EntityId<S, Root>
-  ) => void
+  readonly relate: [Relates] extends [never]
+    ? MethodNotDeclared<"relate", "relates">
+    : <R extends Extract<Relates, Relation.Relation.Any>>(
+        entity: Entity.EntityId<S, Root>,
+        relation: R,
+        target: Entity.EntityId<S, Root>
+      ) => void
   /**
    * Queues removal of one outgoing relation when present.
    */
-  readonly unrelate: <R extends Extract<Schema.Relations<S>[keyof Schema.Relations<S>], Relation.Relation.Any>>(
-    entity: Entity.EntityId<S, Root>,
-    relation: R
-  ) => void
+  readonly unrelate: [Relates] extends [never]
+    ? MethodNotDeclared<"unrelate", "relates">
+    : <R extends Extract<Relates, Relation.Relation.Any>>(
+        entity: Entity.EntityId<S, Root>,
+        relation: R
+      ) => void
   /**
    * Queues a hierarchy-only reorder of one parent's current children.
    */
-  readonly reorderChildren: <R extends Extract<Schema.Relations<S>[keyof Schema.Relations<S>], Relation.Relation.Hierarchy>>(
-    entity: Entity.EntityId<S, Root>,
-    relation: R,
-    children: ReadonlyArray<Entity.EntityId<S, Root>>
-  ) => void
+  readonly reorderChildren: [Relates] extends [never]
+    ? MethodNotDeclared<"reorderChildren", "relates">
+    : <R extends Extract<Relates, Relation.Relation.Hierarchy>>(
+        entity: Entity.EntityId<S, Root>,
+        relation: R,
+        children: ReadonlyArray<Entity.EntityId<S, Root>>
+      ) => void
+}
+
+/** 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> | { 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> | { 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
   /**
    * Drains the queued commands in insertion order.
    */
@@ -485,7 +805,7 @@ export interface CommandsApi<S extends Schema.Any, Root = unknown> {
  */
 export const makeCommands = <S extends Schema.Any, Root = unknown>(
   allocateId: () => Entity.EntityId<S, Root>
-): CommandsApi<S, Root> => {
+): CommandQueue<S, Root> => {
   /**
    * The per-system command buffer.
    *
@@ -495,12 +815,12 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
   const queue: Array<DeferredCommand<S>> = []
 
   return {
-    spawn<P extends Entity.ComponentProof>(draft: Entity.EntityDraft<S, P, Root>): Entity.EntityId<S, Root> {
+    spawn(draft) {
       const id = allocateId()
       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)
           }
@@ -508,15 +828,12 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
       })
       return id
     },
-    spawnIn<P extends Entity.ComponentProof>(
-      scope: EntityScope.EntityScope<string, Root>,
-      draft: Entity.EntityDraft<S, P, Root>
-    ): Entity.EntityId<S, Root> {
+    spawnIn(scope, draft) {
       const id = allocateId()
       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)
@@ -525,22 +842,22 @@ 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
       queue.push({
         tag: "despawn",
         apply(world) {
-          world.destroyEntity(entity)
+          world.destroyEntity(id)
         }
       })
     },
@@ -552,11 +869,12 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
         }
       })
     },
-    remove(entity, descriptor) {
+    remove(target, ...descriptors) {
+      const entity = typeof target === "object" ? target.id : target
       queue.push({
         tag: "remove",
         apply(world) {
-          world.removeComponent(entity, descriptor)
+          world.removeComponents(entity, descriptors)
         }
       })
       return entity