@typeonce/ritmo 0.8.0 → 0.9.0

package/src/Descriptor.ts

@@ -280,6 +280,22 @@ const makeConstructedDescriptor = <
     [descriptorConstruction]: constructor
   }) as ConstructedDescriptor<Kind, Name, Value, Raw, Error>
 
+/**
+ * The message naming why `Value` cannot be the value of a descriptor of
+ * `Kind`, or `never` when it can. `any` turns off every check on the
+ * descriptor's reads and writes, and `never` erases the fragment it is listed in.
+ */
+type Article<Kind extends string> = Kind extends "event" ? "an" : "a"
+
+type ValueRejection<Kind extends string, Value> = 0 extends 1 & Value
+  ? `${Article<Kind>} ${Kind} value cannot be \`any\`: give it a type (use \`unknown\` for a value you never read)`
+  : [Value] extends [never] ? `${Article<Kind>} ${Kind} value cannot be \`never\`: give it a type (use \`{}\` for a marker)`
+  : never
+
+/** `Make`, or, when `Value` is rejected, a function whose only parameter is the message. */
+type CheckedValue<Kind extends string, Value, Make> = [ValueRejection<Kind, Value>] extends [never] ? Make
+  : (name: ValueRejection<Kind, Value>) => never
+
 /**
  * Defines a component descriptor.
  *
@@ -289,6 +305,10 @@ const makeConstructedDescriptor = <
  * Components are the only descriptor kind that can be queried directly with
  * `Game.Query.read(...)`, `write(...)`, or `optional(...)`.
  *
+ * The value is a real type: `any` and `never` do not compile (here and in
+ * every other descriptor constructor). Use `unknown` for a value no system
+ * reads, and `Descriptor.Tag` for a marker.
+ *
  * @example
  * ```ts
  * const Position = Descriptor.Component<{ x: number; y: number }>()("Position")
@@ -296,11 +316,11 @@ const makeConstructedDescriptor = <
  * const EnemyKind = Descriptor.Component<"grunt" | "boss">()("EnemyKind", { immutable: true })
  * ```
  */
-export const Component = <Value>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+export const Component = <Value>(): CheckedValue<"component", Value, <const Name extends string, const Options extends ComponentOptions = {}>(
   name: Name,
   options?: Options
-): WithComponentOptions<Descriptor<"component", Name, Value>, Options> =>
-  applyComponentOptions(makeDescriptor("component", name), options) as WithComponentOptions<Descriptor<"component", Name, Value>, Options>
+) => WithComponentOptions<Descriptor<"component", Name, Value>, Options>> =>
+  ((name: string, options?: ComponentOptions) => applyComponentOptions(makeDescriptor("component", name), options)) as never
 
 /**
  * Defines a component descriptor that also knows how to validate raw values.
@@ -334,11 +354,11 @@ export const ConstructedComponent = <Value, Raw, Error, Constructor extends {} =
  * const SpriteRef = Descriptor.TransientComponent<{ frame: number }>()("SpriteRef")
  * ```
  */
-export const TransientComponent = <Value>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+export const TransientComponent = <Value>(): CheckedValue<"component", Value, <const Name extends string, const Options extends ComponentOptions = {}>(
   name: Name,
   options?: Options
-): WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options> =>
-  applyComponentOptions(makeTransientDescriptor("component", name), options) as WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options>
+) => WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options>> =>
+  ((name: string, options?: ComponentOptions) => applyComponentOptions(makeTransientDescriptor("component", name), options)) as never
 
 /**
  * Defines a marker component: no data, only presence (`[Player, {}]`).
@@ -446,9 +466,9 @@ export const isEntityState = (
  * const Score = Descriptor.Resource<number>()("Score")
  * ```
  */
-export const Resource = <Value>() => <const Name extends string>(
+export const Resource = <Value>(): CheckedValue<"resource", Value, <const Name extends string>(
   name: Name
-): Descriptor<"resource", Name, Value> => makeDescriptor("resource", name)
+) => Descriptor<"resource", Name, Value>> => ((name: string) => makeDescriptor("resource", name)) as never
 
 /**
  * Defines a resource descriptor that also knows how to validate raw values.
@@ -469,9 +489,9 @@ export const ConstructedResource = <Value, Raw, Error, Constructor extends {} =
  * const DeltaTime = Descriptor.TransientResource<number>()("DeltaTime")
  * ```
  */
-export const TransientResource = <Value>() => <const Name extends string>(
+export const TransientResource = <Value>(): CheckedValue<"resource", Value, <const Name extends string>(
   name: Name
-): TransientDescriptor<"resource", Name, Value> => makeTransientDescriptor("resource", name)
+) => TransientDescriptor<"resource", Name, Value>> => ((name: string) => makeTransientDescriptor("resource", name)) as never
 
 /**
  * Defines an event descriptor.
@@ -491,9 +511,9 @@ export const TransientResource = <Value>() => <const Name extends string>(
  * const Hit = Descriptor.Event<{ target: number; amount: number }>()("Hit")
  * ```
  */
-export const Event = <Value>() => <const Name extends string>(
+export const Event = <Value>(): CheckedValue<"event", Value, <const Name extends string>(
   name: Name
-): Descriptor<"event", Name, Value> => makeDescriptor("event", name)
+) => Descriptor<"event", Name, Value>> => ((name: string) => makeDescriptor("event", name)) as never
 
 /**
  * Defines a service descriptor.
@@ -512,9 +532,9 @@ export const Event = <Value>() => <const Name extends string>(
  * const Logger = Descriptor.Service<{ log: (message: string) => void }>()("Logger")
  * ```
  */
-export const Service = <Value>() => <const Name extends string>(
+export const Service = <Value>(): CheckedValue<"service", Value, <const Name extends string>(
   name: Name
-): Descriptor<"service", Name, Value> => makeDescriptor("service", name)
+) => Descriptor<"service", Name, Value>> => ((name: string) => makeDescriptor("service", name)) as never
 
 /**
  * Checks whether one descriptor is transient (skipped by snapshots).
@@ -625,7 +645,10 @@ export function constructorOf<D extends Descriptor.Any>(
  * `Game.EntityScope(...)` instead when entities only share a lifetime (a
  * level, a menu) and need no tree, order, or traversal.
  */
-export const Hierarchy = RelationModule.Hierarchy
+export const Hierarchy = <const Name extends string, const RelatedName extends string>(
+  name: Name,
+  relatedName: RelatedName
+) => makePair("hierarchy", name, relatedName)
 
 /**
  * Defines a general relationship pair with direct edges and reverse lookups.
@@ -634,7 +657,10 @@ export const Hierarchy = RelationModule.Hierarchy
  * reverse lookup, but not hierarchy-only behavior such as tree traversal or
  * child reordering.
  */
-export const Relation = RelationModule.Relation
+export const Relation = <const Name extends string, const RelatedName extends string>(
+  name: Name,
+  relatedName: RelatedName
+) => makePair("relation", name, relatedName)
 import * as DecodeModule from "./Decode.ts"
-import * as RelationModule from "./Relation.ts"
+import { makePair } from "./internal/relations.ts"
 import * as ResultModule from "./Result.ts"

package/src/Entity.ts

@@ -131,7 +131,7 @@ export namespace Handle {
  * Drafts exist before the command queue is flushed. This is the place where the
  * API can safely carry exact structural information.
  */
-export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof, Root = unknown> {
+export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof, Root = unknown, out Relates = never> {
   /**
    * Runtime tag for debugging and pattern matching.
    */
@@ -156,6 +156,11 @@ export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof,
    * Staged relationship edges attached to the entity before spawn.
    */
   readonly relations: ReadonlyArray<StagedRelation<S, Root>>
+  /**
+   * The relations `Game.Command.relate(...)` staged on this draft: spawning
+   * it needs them in the system's `Game.System.relates(...)`. Type-level only.
+   */
+  readonly __relates?: (_: never) => Relates
 }
 
 /**
@@ -168,7 +173,7 @@ export type StagedComponent = readonly [Descriptor<"component", string, any>, un
  *
  * Query execution is the main source of `EntityRef` values.
  */
-export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown, out Proves = unknown, out Lacks = never> {
+export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown, in Proves = never, in Lacks = never> {
   /**
    * Runtime tag for debugging and pattern matching.
    */
@@ -176,15 +181,17 @@ export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, R
   /**
    * The component descriptors the query that produced this ref proves (its
    * required slots and `with`): what `commands.despawn`, `insert`, and
-   * `remove` check. Type-level only.
+   * `remove` check. Type-level only. Contravariant on purpose: a ref proving
+   * more is a subtype, so a union of refs (`cond ? a.entity : b.entity`)
+   * keeps only what both prove.
    */
-  readonly __proves?: (_: never) => Proves
+  readonly __proves?: (_: Proves) => void
   /**
    * The component descriptors the producing query proves absent (its
    * `without`): what `commands.remove` checks against `Schema.requires`.
    * Type-level only.
    */
-  readonly __lacks?: (_: never) => Lacks
+  readonly __lacks?: (_: Lacks) => void
   /**
    * The schema-bound entity identity.
    */
@@ -207,17 +214,17 @@ export interface EntityMut<
   out P extends ComponentProof,
   out W extends ComponentProof,
   Root = unknown,
-  out Proves = unknown,
-  out Lacks = never
+  in Proves = never,
+  in Lacks = never
 > {
   /**
    * Runtime tag for debugging and pattern matching.
    */
   readonly kind: "EntityMut"
   /** The component descriptors the producing query proves; see `EntityRef`. */
-  readonly __proves?: (_: never) => Proves
+  readonly __proves?: (_: Proves) => void
   /** The component descriptors the producing query proves absent; see `EntityRef`. */
-  readonly __lacks?: (_: never) => Lacks
+  readonly __lacks?: (_: Lacks) => void
   /**
    * The schema-bound entity identity.
    */

package/src/FixedLoop.ts

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

package/src/HostClock.ts

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

package/src/Machine.ts

@@ -418,7 +418,10 @@ export const inState = <M extends StateMachine.Any>(
 })
 
 /**
- * Creates a condition that passes when the machine changed during the current schedule execution.
+ * Creates a condition that passes when the machine changed during the current schedule execution:
+ * from the `applyStateTransitions(...)` that committed the change to the end of
+ * that schedule (or the next `applyStateTransitions(...)`), not for the rest of
+ * the tick call or the next schedule.
  */
 export const stateChanged = <M extends StateMachine.Any>(
   machine: M

package/src/Query.ts

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

package/src/Relation.ts

@@ -10,11 +10,9 @@
  *
  * @example
  * ```ts
- * // Model a scene-graph style parent/children relationship.
- * const Parent = Relation.Hierarchy("Parent", "Children")
- *
- * // Model another directed gameplay relationship.
- * const Target = Relation.Relation("Target", "TargetedBy")
+ * // Relations are defined with Descriptor.Hierarchy and Descriptor.Relation.
+ * const { relation: ChildOf } = Descriptor.Hierarchy("ChildOf", "Children")
+ * const { relation: Targeting } = Descriptor.Relation("Targeting", "TargetedBy")
  * ```
  *
  * @module Relation
@@ -44,7 +42,8 @@ const relationTypeId: RelationTypeId = "~ritmo/Relation"
 
 export type RelationKind = "hierarchy" | "relation"
 
-type PairBrand<Name extends string, RelatedName extends string, Kind extends RelationKind> = {
+/** The nominal brand tying a relation to its reverse side. */
+export type PairBrand<Name extends string, RelatedName extends string, Kind extends RelationKind> = {
   readonly relation: Name
   readonly related: RelatedName
   readonly kind: Kind
@@ -281,67 +280,6 @@ export const mutationFailure = <
   error
 })
 
-const makePair = <
-  const Name extends string,
-  const RelatedName extends string,
-  const Kind extends RelationKind
->(
-  kind: Kind,
-  name: Name,
-  relatedName: RelatedName
-): {
-  readonly relation: RelationDefinition<Name, RelatedName, Kind, PairBrand<Name, RelatedName, Kind>>
-  readonly related: RelatedDefinition<RelatedName, Name, Kind, PairBrand<Name, RelatedName, Kind>>
-} => {
-  type Pair = PairBrand<Name, RelatedName, Kind>
-  const related = {
-    kind: "related",
-    relatedName,
-    relationName: name,
-    key: Symbol.for(`ritmo/related/${name}`),
-    relationKind: kind,
-    [relationTypeId]: {
-      _Pair: (_: never) => undefined as unknown as Pair
-    }
-  } as RelatedDefinition<RelatedName, Name, Kind, Pair>
-
-  const relation = {
-    kind: "relation",
-    name,
-    relatedName,
-    key: Symbol.for(`ritmo/relation/${name}`),
-    relationKind: kind,
-    linkedDespawn: kind === "hierarchy",
-    allowSelf: false,
-    ordered: kind === "hierarchy",
-    related,
-    [relationTypeId]: {
-      _Pair: (_: never) => undefined as unknown as Pair
-    }
-  } as RelationDefinition<Name, RelatedName, Kind, Pair>
-
-  return {
-    relation,
-    related
-  }
-}
-
-export const Hierarchy = <
-  const Name extends string,
-  const RelatedName extends string
->(
-  name: Name,
-  relatedName: RelatedName
-) => makePair("hierarchy", name, relatedName)
-
-export const Relation = <
-  const Name extends string,
-  const RelatedName extends string
->(
-  name: Name,
-  relatedName: RelatedName
-) => makePair("relation", name, relatedName)
-
 export interface RelationReadAccess<
   R extends Relation.Any,
   S extends Schema.Any,