@typeonce/ritmo 0.6.0 → 0.7.0

package/src/Command.ts

@@ -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
@@ -262,20 +271,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 +294,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 +410,267 @@ 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 })
+
 /**
- * Public command API exposed to systems.
+ * 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 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.
    */
-  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>) => 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(...)`).
    */
-  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>
+      ) => 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.
    *
    * 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 Entries extends ReadonlyArray<SchemaEntry<S>>>(
+        entity: Entity.EntityId<S, Root>,
+        ...entries: Entries & EntriesAllowed<Entries, Inserts>
+      ) => 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: 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.
    */
-  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">
+    : <D extends Extract<Schema.Components<S>[keyof Schema.Components<S>], ComponentDescriptor>>(
+        entity: Entity.EntityId<S, Root>,
+        descriptor: D & RemoveAllowed<D, Removes>
+      ) => 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>, ...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 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 +685,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,7 +695,7 @@ 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",
@@ -508,10 +708,7 @@ 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",
@@ -537,10 +734,11 @@ export const makeCommands = <S extends Schema.Any, Root = unknown>(
       return entity
     },
     despawn(entity) {
+      const id = typeof entity === "object" ? entity.id : entity
       queue.push({
         tag: "despawn",
         apply(world) {
-          world.destroyEntity(entity)
+          world.destroyEntity(id)
         }
       })
     },

package/src/Debug.ts

@@ -1,7 +1,7 @@
 /**
  * Opt-in runtime introspection for tools, tests, and coding agents.
  *
- * A runtime made with `debug: true` carries a `debug` handle. Runtimes made
+ * A runtime made with `debug: { hostClock }` carries a `debug` handle. Runtimes made
  * without it have no handle at all, so production code cannot reach into
  * internals by accident and pays nothing for them.
  *
@@ -35,7 +35,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, resources, debug: true })
+ * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } })
  * runtime.debug.nameSchedules({ setup: setupSchedule, update: updateSchedule })
  *
  * const stop = runtime.debug.observe((event) => {
@@ -46,15 +46,16 @@
  * stop()
  * ```
  */
+import type { HostClock } from "./HostClock.ts"
 import type * as Machine from "./Machine.ts"
-import type { ExecutableScheduleDefinition } from "./Schedule.ts"
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "./Schedule.ts"
 import type { Schema } from "./Schema.ts"
 
 /** Version of the description, dump, and trace formats. */
 export const formatVersion = 1 as const
 
 /**
- * The debug handle of a runtime made with `debug: true`.
+ * The debug handle of a runtime made with `debug: { hostClock }`.
  */
 export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
   /**
@@ -64,8 +65,15 @@ export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
    * `onEnter(Game/Flow=Playing)`. Naming again replaces earlier names.
    */
   readonly nameSchedules: (
-    schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>>
+    schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
   ) => void
+  /**
+   * Declares the events the host publishes with `runtime.send`, so
+   * `describe()` counts them as written (`event-never-written`) before the
+   * first send happens. Events actually sent count as well. Declaring again
+   * replaces the list.
+   */
+  readonly declareHostEvents: (events: ReadonlyArray<Schema.EventDescriptor<S>>) => void
   /** The static description of the schema and the named schedules. */
   readonly describe: () => Description
   /** The current world as plain data. */
@@ -75,6 +83,21 @@ export interface Handle<S extends Schema.Any = Schema.Any, Root = unknown> {
    * active only while at least one listener is registered.
    */
   readonly observe: (listener: (event: TraceEvent) => void) => () => void
+  /**
+   * Delivers what the host does to the runtime, until the returned function
+   * is called: each tick's start and end (with the schedule values it runs)
+   * and each `runtime.send`. Unlike `observe`, it turns no tracing on, so a
+   * tool can listen for a whole play session (replay recorders do).
+   */
+  readonly observeHost: (listener: (event: HostEvent<S, Root>) => void) => () => void
+  /**
+   * Reports the last failed tick result if nobody read its `ok`, as a
+   * `failure.ignored` event (to `observe` and `observeHost` listeners), with
+   * `when: "session-end"`. Call it when a session ends; the start of the
+   * next tick checks the same with `when: "next-tick"`. Emits nothing to a
+   * console.
+   */
+  readonly checkIgnoredFailures: () => void
   /** Retention and reader state of every stream that has readers or entries. */
   readonly streams: () => ReadonlyArray<StreamStatus>
   /** Live entity count and, per component, how many entities have it. Cheap enough to sample every frame. */
@@ -153,7 +176,15 @@ export interface SystemDescription {
   readonly removed: ReadonlyArray<string>
   readonly despawned: boolean
   readonly relationFailures: ReadonlyArray<string>
+  /** Events and resources read with `Game.System.thisTick`, and query slots as `queries.<slot>`. */
+  readonly thisTick: ReadonlyArray<string>
   readonly services: ReadonlyArray<string>
+  /**
+   * The declared command permissions (`Game.System.commands(...)`), by
+   * kind: component names for spawns, inserts, removes and despawns, scope
+   * names for despawnsScope, relation names for relates.
+   */
+  readonly commands: CommandPermissions
   /** Run conditions, rendered, for example `stateChanged(Game/Flow)`. */
   readonly when: ReadonlyArray<string>
   /** Pause conditions, rendered: while one fails the system waits and holds its stream entries. */
@@ -162,6 +193,16 @@ export interface SystemDescription {
   readonly local: boolean
 }
 
+/** Declared command permissions of one system, by kind. Empty lists when it declares none. */
+export interface CommandPermissions {
+  readonly spawns: ReadonlyArray<string>
+  readonly inserts: ReadonlyArray<string>
+  readonly removes: ReadonlyArray<string>
+  readonly despawns: ReadonlyArray<string>
+  readonly despawnsScope: ReadonlyArray<string>
+  readonly relates: ReadonlyArray<string>
+}
+
 export type StepDescription =
   | { readonly kind: "system"; readonly system: string }
   | { readonly kind: "applyDeferred" }
@@ -175,17 +216,28 @@ export interface ScheduleDescription {
 /**
  * A finding about the described schedules. `warning` is almost certainly a
  * bug; `info` is worth a look but can be intentional.
+ *
+ * Most lints read declarations only. Two also use what the runtime has seen
+ * so far: events sent with `runtime.send(...)` count as written, and
+ * `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, so describe after the game has run for a while.
  */
 export interface Lint {
   readonly severity: "warning" | "info"
   readonly code:
     | "event-never-read"
+    | "relation-failure-never-read"
     | "event-never-written"
     | "next-state-never-applied"
     | "component-never-read"
     | "read-before-write"
+    | "this-tick-order"
+    | "command-permission-unused"
   readonly message: string
   readonly subject: string
+  /** What to change to resolve it (or, for `info`, when it is fine as it is). */
+  readonly fix: string
 }
 
 /** Readers and writers of one component, resource, or event. */
@@ -207,7 +259,8 @@ export interface Description {
   readonly systems: ReadonlyArray<SystemDescription>
   /**
    * Readers and writers across the named schedules. Component writers are
-   * systems with a write query slot; command inserts are not static.
+   * systems with a write query slot or a declared `spawns`, `inserts`, or
+   * `removes` permission for it.
    */
   readonly access: {
     readonly components: ReadonlyArray<AccessIndexEntry>
@@ -450,6 +503,45 @@ export interface RestoreEvent {
   readonly ok: boolean
 }
 
+/** What `observeHost` delivers. */
+export type HostEvent<S extends Schema.Any = Schema.Any, Root = unknown> =
+  | {
+      readonly type: "tick.start"
+      /** The schedule values passed to this `tick(...)` (or `tryTick`) call, in order. */
+      readonly schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>
+      readonly frame: number
+    }
+  | {
+      readonly type: "tick.end"
+      readonly schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>
+      readonly frame: number
+      /** `failed`: a system returned `Result.failure`; `defect`: one threw (rethrown after this event). */
+      readonly outcome: "ok" | "failed" | "defect"
+      readonly error?: unknown
+    }
+  | { readonly type: "send"; readonly event: string; readonly value: unknown }
+  | FailureIgnoredEvent
+
+/**
+ * A failed `tick` / `tryTick` result whose `ok` nobody read: the failure
+ * went unnoticed, and the systems after the failing one did not run that
+ * tick. Found at the start of the next tick (`when: "next-tick"`) or by
+ * `checkIgnoredFailures()` (`when: "session-end"`). Debug runtimes only.
+ */
+export interface FailureIgnoredEvent {
+  readonly type: "failure.ignored"
+  /** The frame of the failed tick. */
+  readonly frame: number
+  /** The schedule holding the failing system (the first one for a tick that ran nothing). */
+  readonly schedule: string
+  /** The failing system; `undefined` when `tryTick` ran nothing (missing requirements, order). */
+  readonly system: string | undefined
+  readonly error: unknown
+  /** The systems of the tick that did not run because of the failure, in order. */
+  readonly skipped: ReadonlyArray<string>
+  readonly when: "next-tick" | "session-end"
+}
+
 /** Everything `observe` delivers. */
 export type TraceEvent =
   | FrameEvent
@@ -461,14 +553,21 @@ export type TraceEvent =
   | DeferredEvent
   | TransitionEvent
   | RestoreEvent
+  | FailureIgnoredEvent
 
 /**
- * The `debug` runtime option: `true` attaches a handle.
+ * The `debug` runtime option: `{ hostClock }` attaches a handle, timing
+ * traces with that clock. A value that may be `undefined`
+ * (`import.meta.env.DEV ? { hostClock } : undefined`) attaches it when
+ * present and types `debug` as optional, so code checks it before use.
  */
-export type Option = true
+export interface Option {
+  /** Times trace events (`ms`); see `HostClock`. */
+  readonly hostClock: HostClock
+}
 
 /**
- * The member a runtime made with `debug: true` carries.
+ * The member a runtime made with `debug: { hostClock }` carries.
  */
 export interface Member<S extends Schema.Any, Root> {
   readonly debug: Handle<S, Root>
@@ -476,4 +575,6 @@ export interface Member<S extends Schema.Any, Root> {
 
 /** Resolves the extra runtime member for a `debug` option type. */
 export type MemberFor<Enabled, S extends Schema.Any, Root> =
-  [Enabled] extends [Option] ? Member<S, Root> : {}
+  [Enabled] extends [true] ? Member<S, Root>
+  : [Enabled] extends [false | undefined] ? {}
+  : Partial<Member<S, Root>>