@vworlds/vecs 1.0.44 → 1.0.46

package/docs/design-guide.md

@@ -130,7 +130,7 @@ component set _is_ the lifecycle; queries drive create/destroy; reset is free.
 const obj = scene.add.arc(0, 0); // a Phaser GameObject
 entity.attach(obj); // the GameObject is now a component, keyed by its class
 
-world.component(Phaser.GameObjects.Arc).onRemove((_entity, obj) => obj.destroy());
+world.component(Phaser.GameObjects.Arc).on("remove", (_entity, obj) => obj.destroy());
 ```
 
 `onRemove` (below) releases the resource whenever it leaves — whether removed explicitly or
@@ -144,15 +144,17 @@ beside the resource.
 `world.component(C)` returns a handle with hooks fired on every entity:
 
 ```ts
-world.component(Impulse).onSet((entity, impulse) => {
+world.component(Impulse).on("set", (entity, impulse) => {
   /* accumulate */
 });
-world.component(Phaser.GameObjects.Arc).onRemove((_entity, obj) => obj.destroy());
+world.component(Phaser.GameObjects.Arc).on("remove", (_entity, obj) => obj.destroy());
 ```
 
 Use them for resource management and cross-cutting reactions that aren't worth a system. (Note
 the difference from systems: hooks are per-component-instance and run at the mutation site;
-systems are queries that run in a phase.)
+systems are queries that run in a phase.) Multiple handlers may be registered per event; they fire
+in registration order and are removed with `off(event, handler)` by reference (see
+[Components — hooks](./components.md#hooks-component-and-relationship-edges)).
 
 ### Component traits: policy on component entities
 
@@ -161,17 +163,19 @@ policy for every use of the component type; these configuration components are *
 
 ```ts
 world.component(Gravity).add(Singleton);
-world.component(Inventory).add(OwnedTarget);
-world.component(ChildOf).add(Traversable);
+world.component(Inventory).add(Exclusive).add(OwnedTarget);
+world.component(ChildOf).add(Exclusive).add(Traversable);
 world.component(Orange).set(Implements, { interfaces: [Fruit] });
 ```
 
-| Trait/declaration | Reach for it when                                                          |
-| ----------------- | -------------------------------------------------------------------------- |
-| `Singleton`       | At most one entity may carry the component                                 |
-| `Implements`      | Concrete components should be queryable through abstract aliases           |
-| `Traversable`     | A relationship hierarchy needs depth or cascade ordering                   |
-| `OwnedTarget`     | A relationship is an exclusively owned, zero-or-one entity-valued property |
+| Trait/declaration | Reach for it when                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `Singleton`       | At most one entity may carry the component                                         |
+| `Implements`      | Concrete components should be queryable through abstract aliases                   |
+| `Exclusive`       | A relationship must have at most one target                                        |
+| `Traversable`     | An exclusive relationship hierarchy needs depth or cascade ordering                |
+| `OwnedTarget`     | An exclusive relationship owns its explicitly added target                         |
+| `OneOf`           | A relationship's targets must be direct children of a declared parent (enum-style) |
 
 Traits declare policy; modules implement it through hooks and metadata. Configure them in module
 setup, not inside systems. Lifecycle differs by trait: `OwnedTarget` and `Singleton` are setup-time
@@ -194,38 +198,52 @@ entity.set(Rectangle, { width: 2, height: 1 }); // Arc auto-removed
 
 ### Relationships
 
-A relationship is a component whose value points at another entity:
+A relationship is a component that stores edges from its source entity to one or more target
+entities. Add and remove those edges explicitly:
 
 ```ts
 class InCell extends Relationship {}
-entity.set(InCell, { target: cell }); // retarget freely
-entity.target(InCell); // the target entity
+entity.add(InCell, cell);
+entity.add(InCell, neighboringCell);
+entity.remove(InCell, cell);
+
+entity.target(InCell); // one current target, or undefined
+entity.targets(InCell); // readonly snapshot of every target
+entity.hasTarget(InCell, neighboringCell); // true
 world.query("ByCell").with(Networked, Position).groupBy(InCell); // index by target
 ```
 
-Use `entity.ensureTarget(InCell)` when an absent relationship should default to a new independent
-entity. For aggregate parts whose lifetime should remain bound to the source once assigned, attach
-`OwnedTarget` during setup:
+Relationships are multi-target by default. Add the `Exclusive` relationship trait when a source may
+have at most one target; adding a different edge then replaces the old edge. This cardinality trait
+is separate from `world.setExclusiveComponents(...)`, which prevents different component types from
+coexisting on one entity.
+
+For a zero-or-one aggregate whose lifetime remains bound to its source, create the target explicitly
+and configure the relationship with both `Exclusive` and `OwnedTarget` during setup:
 
 ```ts
-world.component(Inventory).add(OwnedTarget);
-const inventory = player.ensureTarget(Inventory); // inventory is ChildOf player
+world.component(Inventory).add(Exclusive).add(OwnedTarget);
+const inventory = world.entity();
+player.add(Inventory, inventory); // inventory becomes ChildOf player
 ```
 
-`OwnedTarget` destroys displaced targets on retarget and destroys the current target when the
-relationship is removed, keeping aggregate cleanup aligned with the active relationship.
-
-- **`Relationship.target` is an `Entity` — not directly serialisable, but
-  relationships can be networked** when listed in `networkComponents`.
-  `vecs-protocol` registers `Relationship.prototype.target` as an `"entity"`
-  wire field (u32 eid), so subclasses serialise their target as a raw entity
-  id. The client resolves the id to a live entity (creating a ghost
-  placeholder if the parent hasn't arrived yet). Use a dedicated relationship
-  class per concern — e.g. `ChildOf` for server-local ownership/lifecycle,
-  `DrawIn` (in vecs-phaser) for networked display hierarchy — so the two
-  concerns don't overload a single relationship.
-- **Retargeting is a plain data change** (no archetype churn). Prefer retargeting a relationship
-  over swapping marker components to express "which bucket this entity is in."
+`OwnedTarget` requires `Exclusive`, never creates a target implicitly, destroys the displaced target
+when a new edge replaces it, and destroys the current target when its edge or relationship is
+removed. `Traversable` also requires `Exclusive` because hierarchy depth needs one parent. Edge
+hooks, `onTargetAdd` and `onTargetRemove`, observe each explicit edge transition and compose with
+these policies.
+
+- **Target storage is private.** Read edges with `target` / `targets` / `hasTarget`; mutate them only
+  with `add(Rel, target)` and `remove(Rel, target)` (or `remove(Rel)` for all edges). There is no
+  public `Relationship.target` field.
+- **Relationships can be networked** when listed in `networkComponents`. A relationship snapshot
+  carries all target eids plus the relationship's ordinary wire fields. The client reconciles the
+  complete edge set and creates ghost targets that have not arrived yet. Use a dedicated
+  relationship class per concern so ownership, hierarchy, and display links do not overload one
+  relationship.
+- **Edge changes do not change the source archetype** while at least one edge remains. Prefer
+  replacing an exclusive edge, or adding/removing multi-target edges, over swapping marker
+  components to express membership.
 
 ---
 
@@ -253,7 +271,8 @@ classes or DSL objects (`{ all: [...] }`, `{ any: [...] }`, `{ parent: X }`, `{
 ### Reactive callbacks: `enter` / `update` / `exit`
 
 - **`enter`** — fires once when an entity _becomes_ a member. Use it for one-time setup
-  (create the resource).
+  (create the resource). It fires only when the entity remains a member when the system drains;
+  vecs drops a transient entry and its paired exit, so setup code does not need a `destroyed` guard.
 - **`update(C, …)`** — adds `C` to the predicate and fires when watched component `C` is modified.
   Pass `{ onEnter: true }` when it should also fire on entry for an already-present watched
   component. Use that to initialize on entry _and_ react to changes; leave it off when a separate
@@ -406,7 +425,7 @@ Guidelines:
   export class PhaserRenderModule extends Module<{ scene; pixelsPerMeter? }> {
     public init(cfg): void {
       const coords = new CoordSpace(cfg.scene, cfg.pixelsPerMeter);
-      this.world.component(GameObject).onRemove((_e, obj) => obj.destroy()); // GameObject: Implements marker over every Phaser object
+      this.world.component(GameObject).on("remove", (_e, obj) => obj.destroy()); // GameObject: Implements marker over every Phaser object
       this.world.module(ArcModule, { scene: cfg.scene, coords });
       this.world.module(RectangleModule, { scene: cfg.scene, coords });
       // … shape modules first …
@@ -516,7 +535,7 @@ live object as its own component** and let a remove hook release it — no wrapp
 
 ```ts
 // Release the resource whenever its component leaves (explicit remove or entity destroy):
-world.component(Phaser.GameObjects.Arc).onRemove((_e, obj) => obj.destroy());
+world.component(Phaser.GameObjects.Arc).on("remove", (_e, obj) => obj.destroy());
 
 // CREATE: a renderable that has no object yet
 world
@@ -541,7 +560,7 @@ world
 
 // TEARDOWN: when the shape data leaves (type swap) or the entity dies, drop the object.
 // A component remove hook keeps this declarative — no exit system, no phase to coordinate:
-world.component(Arc).onRemove((e) => {
+world.component(Arc).on("remove", (e) => {
   if (e.has(Phaser.GameObjects.Arc)) e.remove(Phaser.GameObjects.Arc);
 });
 ```
@@ -575,10 +594,12 @@ the current `A` as soon as the entity enters the sync system:
 Leave `onEnter: true` off (or set `onEnter: false`) only when a separate `.enter(...)` already initializes `B`,
 or when the callback is intentionally "future changes only."
 
-### Relationship retargeting + grouped queries for spatial/interest indexing
+### Relationship edges + grouped queries for spatial/interest indexing
 
 Bucket entities by a relationship target (or a derived key) and look up buckets in O(1) instead of
-scanning. Moving between buckets is a retarget (data change), not a component swap.
+scanning. `groupBy(Rel)` places a source in every bucket targeted through `Rel`; adding or removing
+an edge reconciles only the affected buckets. Use `Exclusive` when the model permits one bucket and
+multi-target relationships when a source legitimately belongs to several.
 
 ### Owned target entities (entity-valued properties)
 
@@ -600,12 +621,13 @@ class Weight {
   current = 0;
 }
 
-world.component(Inventory).add(OwnedTarget);
+world.component(Inventory).add(Exclusive).add(OwnedTarget);
 world.component(InventoryState);
 world.component(Capacity);
 world.component(Weight);
 
-const inventory = player.ensureTarget(Inventory);
+const inventory = world.entity();
+player.add(Inventory, inventory);
 inventory.add(InventoryState).set(Capacity, { slots: 20 }).set(Weight, { current: 0 });
 ```
 
@@ -624,35 +646,36 @@ world
 
 The lifecycle follows from the relationship and trait:
 
-| Operation                              | Result                                   |
-| -------------------------------------- | ---------------------------------------- |
-| First `player.ensureTarget(Inventory)` | Creates and returns the inventory entity |
-| Later `ensureTarget(Inventory)`        | Returns the same target                  |
-| Retarget `Inventory`                   | Destroys the displaced inventory         |
-| Remove `Inventory`                     | Destroys the current inventory           |
-| Destroy `player`                       | `ChildOf` destroys the inventory         |
+| Operation                             | Result                                                                    |
+| ------------------------------------- | ------------------------------------------------------------------------- |
+| `player.add(Inventory, inventory)`    | Parents the explicit inventory entity                                     |
+| `player.add(Inventory, replacement)`  | Destroys the displaced inventory                                          |
+| `player.remove(Inventory, inventory)` | Destroys that inventory and removes `Inventory` when it was the sole edge |
+| `player.remove(Inventory)`            | Destroys every current target                                             |
+| Destroy `player`                      | `ChildOf` destroys the inventory                                          |
 
-Inside deferred execution, mutate the entity returned by `ensureTarget`; do not immediately re-read
-the relationship:
+Inside deferred execution, keep and mutate the target you created; the queued edge is not visible
+through `target` until flush:
 
 ```ts
 world.defer(() => {
-  const inventory = player.ensureTarget(Inventory);
-  inventory.set(Capacity, { slots: 20 }); // correct: pending entity is usable
+  const inventory = world.entity();
+  player.add(Inventory, inventory);
+  inventory.set(Capacity, { slots: 20 }); // the newly created entity is usable
   player.target(Inventory); // still undefined until flush
 });
 ```
 
 Use the narrowest model that fits:
 
-| Need                                                | Model                                      |
-| --------------------------------------------------- | ------------------------------------------ |
-| A few fields sharing the owner's identity/lifecycle | Components directly on the owner           |
-| One composable, exclusively owned sub-entity        | `ensureTarget` + `OwnedTarget`             |
-| One shared or independently living linked entity    | Relationship without `OwnedTarget`         |
-| Zero-to-many subobjects                             | Child entities with identifying components |
-| A non-ECS runtime object                            | `attach(instance)`                         |
-| World-global state                                  | Singleton/component entity                 |
+| Need                                                | Model                                         |
+| --------------------------------------------------- | --------------------------------------------- |
+| A few fields sharing the owner's identity/lifecycle | Components directly on the owner              |
+| One composable, exclusively owned sub-entity        | Explicit target + `Exclusive` + `OwnedTarget` |
+| One shared or independently living linked entity    | Relationship without `OwnedTarget`            |
+| Zero-to-many subobjects                             | Child entities with identifying components    |
+| A non-ECS runtime object                            | `attach(instance)`                            |
+| World-global state                                  | Singleton/component entity                    |
 
 Good fits include an inventory aggregate, equipment loadout, character progression sheet, AI
 blackboard, quest journal, ability book, or unique vehicle subsystem. Individual inventory items,
@@ -670,22 +693,22 @@ system after whatever produces the entity/companion.
 
 ## 8. Anti-patterns (keep ECS semantics)
 
-| Smell                                                                  | Do instead                                                                                                                                                                                                |
-| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A side `Map<eid, resource>`                                            | Store the resource in a **companion component**; let queries drive its lifecycle; release in `onRemove`.                                                                                                  |
-| An imperative runtime object with `start()/stop()/track/enable`        | A **module** + the world's own lifecycle (`clearAllEntities()`, closing the world). Systems live on the world; they don't need a wrapper to turn on.                                                      |
-| Builder/factory helpers that _create entities_ (`createArc(world, …)`) | Let callers `world.entity().add(Networked).set(Arc, …).set(FillStyle, …)`. Components are small and optional; the caller adds exactly what it wants.                                                      |
-| A god component with many optional fields                              | Split into small single-purpose components; absence encodes "not applicable."                                                                                                                             |
-| A large nested `inventory`, `brain`, or progression object             | Use an owned target entity when the subobject needs its own components, systems, and lifecycle.                                                                                                           |
-| A side `Map<ownerEid, SubsystemState>`                                 | Use `owner.ensureTarget(Rel)`; add `OwnedTarget` only for exclusive destructive ownership.                                                                                                                |
-| `OwnedTarget` on `CurrentEnemy`, `InCell`, `Team`, or shared state     | Use a normal relationship; retargeting or removal of an owned relationship destroys its target.                                                                                                           |
-| One owned target used as a collection                                  | Use multiple child/item entities; owned targets model zero-or-one aggregates.                                                                                                                             |
-| Duplicated `enter` + `update` doing the same thing                     | One `update({ watch: C, onEnter: true })` when update owns initialization.                                                                                                                                |
-| One system trying to act in two phases                                 | Split into two systems, one per phase.                                                                                                                                                                    |
-| Custom phases for app/render logic                                     | Use the standard taxonomy; only engine modules insert phases.                                                                                                                                             |
-| `.each` scanning every entity to detect change                         | Reactive `.update(C)` — fires only on change.                                                                                                                                                             |
-| Networking a relationship                                              | Relationships can be networked when listed in `networkComponents`: `Relationship.target` serialises as a u32 entity id. List `ChildOf` (or custom subclasses) explicitly to replicate parent-child links. |
-| A `registerFooSystem(world)` wrapper per system                        | Declare the system inline in the module's `init`.                                                                                                                                                         |
+| Smell                                                                  | Do instead                                                                                                                                           |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A side `Map<eid, resource>`                                            | Store the resource in a **companion component**; let queries drive its lifecycle; release in `onRemove`.                                             |
+| An imperative runtime object with `start()/stop()/track/enable`        | A **module** + the world's own lifecycle (`clearAllEntities()`, closing the world). Systems live on the world; they don't need a wrapper to turn on. |
+| Builder/factory helpers that _create entities_ (`createArc(world, …)`) | Let callers `world.entity().add(Networked).set(Arc, …).set(FillStyle, …)`. Components are small and optional; the caller adds exactly what it wants. |
+| A god component with many optional fields                              | Split into small single-purpose components; absence encodes "not applicable."                                                                        |
+| A large nested `inventory`, `brain`, or progression object             | Use an owned target entity when the subobject needs its own components, systems, and lifecycle.                                                      |
+| A side `Map<ownerEid, SubsystemState>`                                 | Create a target entity and add an explicit edge; use `Exclusive` + `OwnedTarget` only for destructive ownership.                                     |
+| `OwnedTarget` on `CurrentEnemy`, `InCell`, `Team`, or shared state     | Use a normal relationship; replacing or removing an owned edge destroys its target.                                                                  |
+| One owned target used as a collection                                  | Use multiple child/item entities; owned targets model zero-or-one aggregates.                                                                        |
+| Duplicated `enter` + `update` doing the same thing                     | One `update({ watch: C, onEnter: true })` when update owns initialization.                                                                           |
+| One system trying to act in two phases                                 | Split into two systems, one per phase.                                                                                                               |
+| Custom phases for app/render logic                                     | Use the standard taxonomy; only engine modules insert phases.                                                                                        |
+| `.each` scanning every entity to detect change                         | Reactive `.update(C)` — fires only on change.                                                                                                        |
+| Treating target storage as component data                              | Use `add(Rel, target)` / `remove(Rel, target)` and read with `target` / `targets` / `hasTarget`; target storage is private.                          |
+| A `registerFooSystem(world)` wrapper per system                        | Declare the system inline in the module's `init`.                                                                                                    |
 
 ---
 
@@ -699,24 +722,37 @@ system after whatever produces the entity/companion.
   when `.enter(...)` already owns initialization.
 - **Membership is fixed by `.with(...)` / `.without(...)` / `.update(C)`;** `update(C)` watches `C`
   and requires it.
-- **`exit` reads a snapshot** of the injected components captured at exit (they're being removed).
+- **`exit` retains injected references captured at exit** (components are not deep-cloned).
 - **Within a phase, order = registration order;** across phases, the spine guarantees order. Don't
   use registration order for cross-module correctness — use phases.
 - **Networked component order = wire protocol.** Reordering breaks the protocol.
 - **`@wireType` must survive esbuild's standard decorators** when components load from
   source (tsx/Vite). Otherwise fields silently don't register.
-- **`Relationship.target` is an `Entity`** — not directly wire-encodable, but
-  `vecs-protocol` registers it as an `"entity"` wire field (u32 eid) at module
-  load, so `Relationship` subclasses listed in `networkComponents` serialise
-  correctly.
+- **Relationships are multi-target by default.** `target(R)` returns one current target for singular
+  code but is not a stable selection policy; `targets(R)` snapshots all targets with unspecified
+  ordering; `hasTarget(R, target)` tests one edge.
+- **Relationship edges are explicit.** Add with `add(R, target)`, remove one with
+  `remove(R, target)`, and remove all with `remove(R)`. Do not use `set` for target storage.
+- **Relationship cardinality and component exclusivity are different.** Add the `Exclusive` trait
+  to a relationship for at-most-one target; use `setExclusiveComponents` for mutually exclusive
+  component types.
+- **Target queries are existential.** `{ target: [R, q] }` matches when any `R` target matches `q`.
+  Singular `{ target: ... }` injection projects one current target; plural `{ targets: ... }`
+  injection returns one projected row per target.
+- **Relationship grouping is multi-bucket.** `groupBy(R)` places an entity in every current target
+  bucket and reconciles buckets as edges change.
+- **Network relationship snapshots contain all targets.** Register the relationship in
+  `networkComponents`; the client reconciles the full edge set and relationship data.
 - **Component traits have trait-specific setup semantics.** In particular, configure `OwnedTarget`
   before creating relationship instances; it does not backfill.
-- **`OwnedTarget` is destructive and exclusive.** Retargeting destroys the old target, removing the
-  relationship destroys the current target, and owner destruction cascades through `ChildOf`.
+- **`OwnedTarget` requires `Exclusive` and explicit target creation.** Replacing an edge destroys
+  the old target, removing the relationship destroys the current target, and owner destruction
+  cascades through `ChildOf`.
   Never use it for shared teams, cells, enemies, definitions, or other world entities.
-- **Owned targets are zero-or-one.** Use child entities for collections, and during deferred
-  execution mutate the entity returned by `ensureTarget` instead of re-reading `target(R)` before
-  flush.
+- **`Traversable` requires `Exclusive`.** Depth and cascade ordering need one parent per source.
+- **Owned targets are zero-or-one.** Use child entities for collections, create the aggregate target
+  explicitly, and during deferred execution keep that entity instead of re-reading `target(R)`
+  before flush.
 - **`world.module(M)` runs `init` once.** Re-registering with a different config throws.
 
 ---
@@ -742,14 +778,14 @@ render code**.
   systems drives every renderable polymorphically. Per shape: a **creation** system
   (`.with(Shape).without(Phaser.GameObjects.Kind).enter` → `scene.add.*` + `entity.attach`) in
   `ON_STORE`; a **geometry** system (`.with(Shape, m.Geometry).update`) in `ON_STORE`; and a
-  shape-data **remove hook** (`component(Shape).onRemove` → remove the Phaser object) instead of a
+  shape-data **remove hook** (`component(Shape).on("remove", ...)` → remove the Phaser object) instead of a
   teardown system. Shared transform/style **sync** systems
   (`.with(Component, m.Marker).update({ watch: Component, onEnter: true })`) apply
   position/rotation/scale/alpha/depth/size/fill/stroke through the markers — initialization is
   explicit via `onEnter: true`, and the umbrella loads shape modules _before_ the sync module so
   creation precedes sync within `ON_STORE`.
 - **Lifecycle that falls out for free:** destruction is a single hook —
-  `component(GameObject).onRemove((_e, obj) => obj.destroy())`. A renderable **type swap**
+  `component(GameObject).on("remove", (_e, obj) => obj.destroy())`. A renderable **type swap**
   (exclusivity removes the old shape data → its remove hook drops the attached object → it's
   destroyed → the new shape's creation system rebinds) and a **baseline reset / disconnect**
   (`clearAllEntities()` → entities destroyed → attached objects removed → destroyed) both work with

package/docs/entities.md

@@ -46,9 +46,10 @@ for end-of-session teardown, not selective resets.
 ```ts
 e.add(Position); // attach with default field values (idempotent)
 e.set(Position, { x: 100 }); // attach if needed, assign props, fire onSet/update
+e.add(FriendOf, friend); // relationship edges require an explicit target
+e.remove(FriendOf, friend); // remove one relationship edge
 e.get(Position); // Readonly<Position> | undefined
 e.ensure(Position, (pos) => (pos.x += 1)); // create if needed, then mutate and notify
-e.ensureTarget(FriendOf); // get or create an independent relationship target
 e.has(Position); // boolean
 e.remove(Position); // detach; fires exit callbacks, then onRemove
 e.modified(Position); // mark changed after in-place mutation
@@ -57,19 +58,26 @@ e.destroy(); // remove everything and unregister the entity
 
 All mutators return the entity for chaining (`remove` and `destroy` return `void`). Component
 references can be a registered class, a numeric component id, or an entity used as a component
-key.
+key. Relationship `target` arguments accept the same `ComponentRef` shapes (class, numeric id, or
+entity) and are resolved eagerly via `world.entity(target)`, so the target entity must already
+exist when the call is made.
 
 ### `set` vs `add` vs `modified`
 
 - `add(C)` attaches with defaults and fires `onAdd` only. It is idempotent and does **not** fire
   `onSet`.
-- `set(C, props)` attaches if needed (firing `onAdd`), copies `props` onto the instance, and fires
-  `onSet` plus `update` callbacks.
+- For ordinary components, `set(C, props)` attaches if needed (firing `onAdd`), copies `props` onto
+  the instance, and fires `onSet` plus `update` callbacks.
 - `ensure(C, callback)` creates the component if missing, then lets you mutate it and fires
   `onAdd` followed by one `onSet`. When the component already exists, it behaves like `getMut`.
 - `modified(C)` fires `onSet`/`update` for data you already mutated in place. Repeated calls are
   coalesced until the world routes the notification.
 
+Relationships use a stricter API: `add(R, target)` creates a unique edge, `remove(R, target)`
+removes one edge, and `remove(R)` removes every edge. `set(R, props)` updates only ordinary fields
+on an existing relationship and never creates or changes edges. See
+[Relationships](./relationships.md#adding-removing-and-setting).
+
 ### `getMut` and `ensure`: mutating in place
 
 `get` returns a `Readonly` view. To mutate, use `getMut`, which marks the component modified for
@@ -100,38 +108,10 @@ When several calls ensure the same missing component during one deferred scope,
 same pending instance. The instance remains hidden from `get` and queries until the queue drains,
 but every ensure callback mutates that shared pending value.
 
-Use `ensureTarget` for the corresponding get-or-create operation on a registered relationship:
-
-```ts
-world.component(FriendOf);
-
-const friend = entity.ensureTarget(FriendOf);
-entity.ensureTarget(FriendOf) === friend; // true
-entity.target(FriendOf) === friend; // true after deferred changes flush
-```
-
-When the relationship is absent, `ensureTarget` creates an independent entity and points the
-relationship at it. It does not add `ChildOf`; destroying the source does not destroy the generated
-target. Repeated calls during one deferred scope return the same pending target, while `target`
-continues to expose only committed state until the queue drains.
-
-Mark the relationship with `OwnedTarget` during world setup when its targets should instead be
-owned by their sources:
-
-```ts
-world.component(Inventory).add(OwnedTarget);
-
-const inventory = player.ensureTarget(Inventory);
-inventory.parent === player; // true after deferred changes flush
-```
-
-The relationship module adds `ChildOf` whenever `Inventory` is set, destroys displaced targets on
-retarget, and destroys the current target when the relationship is removed. Destroying `player`
-therefore also destroys `inventory`. See [Relationships](./relationships.md#owned-targets).
-
 Calling `getMut(C)` or `ensure(C)` without a callback outside deferred mode throws. Both methods
-also throw for relationship components (retarget with `set` instead — see
-[Relationships](./relationships.md#retargeting)) and for `Implements` interface aliases.
+also throw for relationship components (change edges with `add` / `remove` and ordinary data with
+`set`) and for `Implements` interface aliases. `attach` rejects relationships for the same reason:
+their private edge storage must remain under vecs's control.
 
 ### `attach`: storing an existing instance
 
@@ -160,6 +140,9 @@ drains. The exact read-after-write rules are tabulated in
 `ensure(C)` is the exception for mutable access: it returns a mutable component immediately, but a
 newly created component does not appear in `get(C)` until the queue drains.
 
+Relationship edge commands share the same FIFO queue. Until it drains, `has(R)`, `target(R)`,
+`targets(R)`, `hasTarget(R, target)`, and `children(R)` expose only committed edges.
+
 Deferred entity creation is idempotent within one deferred scope: if `world.entity()` or
 `getOrCreateEntity(eid)` creates a new entity, `getEntity(eid)`, `entity(eid)`, and later
 `getOrCreateEntity(eid)` calls before the drain return that same pending entity. Collection-style
@@ -177,53 +160,60 @@ not be used.
 If the entity is itself in use as a component key, `destroy` honors `meta.onDelete` — by default
 it throws while carriers remain ([Components — cleanup policies](./components.md#cleanup-policies-destroying-a-component-entity)).
 
+A `destroy()` thrown synchronously (a `Throw`-policy component entity still in use) leaves the world
+usable because nothing has been mutated. A throw during deferred drain or a relationship cleanup
+cascade — an impossible policy combination, a `Throw`-policy component reached via a cascade, or a
+hook that throws — propagates out of `progress()` / `flush()` and leaves the world in a partial
+state. Treat this as a programming error: recreate the world or stop.
+
 ## Entities as component keys
 
 Any entity can serve as a component key: `other.add(keyEntity)` attaches a marker component whose
 type id is the key entity's eid. The key entity's `meta` (created lazily) carries the same hook
-and policy surface as a registered class, and `keyEntity.onAdd/onSet/onRemove(...)` register hooks
-directly. This is how tag-like, runtime-created component types work without declaring a class.
-Registered relationship component entities additionally expose `onRetarget(...)`.
+and policy surface as a registered class, and `keyEntity.on("add" / "set" / "remove" / "targetAdd" /
+"targetRemove", handler)` registers its lifecycle handlers directly. This is how tag-like,
+runtime-created component types work without declaring a class.
 
 ## Relationships, in brief
 
-`e.target(Rel)` returns the target of a relationship component, `e.children(Rel)` the set of
-entities targeting `e` through it, and `e.childOf(parent)` is shorthand for
-`e.set(ChildOf, { target: parent })`. The full model — retargeting, cleanup cascades, traversal —
-is in [Relationships](./relationships.md).
+`e.target(Rel)` returns one current target, `e.targets(Rel)` a readonly snapshot of every target,
+`e.hasTarget(Rel, target)` tests one edge, and `e.children(Rel)` returns the sources targeting `e`.
+`e.childOf(parent)` is shorthand for `e.add(ChildOf, parent)`. The full model is in
+[Relationships](./relationships.md).
 
 ## Reference
 
 `lib/vecs/src/entity/` (split across `entity.base.ts`, `entity.components.ts`,
 `entity.lifecycle.ts`, `entity.relationships.ts`):
 
-| Property / Method                              | Description                                                                                         |
-| ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `eid`                                          | Unique numeric entity id.                                                                           |
-| `world`                                        | The `World` that owns this entity.                                                                  |
-| `name`                                         | Identity name (getter/setter backed by the `Identity` component); `undefined` when unnamed.         |
-| `componentBitmask`                             | `Bitset` of component type ids attached. Used for archetype matching.                               |
-| `components`                                   | Read-only `ArrayMap` view of attached instances keyed by type id (`forEach`, `get`, `has`, `size`). |
-| `empty`                                        | `true` when no components are attached.                                                             |
-| `properties`                                   | Free-form `Map<string, any>` for module-level bookkeeping.                                          |
-| `meta`                                         | `ComponentMeta` for using this entity as a component key (created lazily).                          |
-| `instanceCount()`                              | Number of entities currently carrying this entity's eid as a component.                             |
-| `add(ref)`                                     | Attach a component with default values (idempotent). Returns `this`.                                |
-| `attach(instance)` / `attach(Class, instance)` | Store an existing instance, replacing any previous one; fires set-side events. Returns `this`.      |
-| `set(ref, props)`                              | Attach if needed and assign `props`; fires `onSet` and `update` callbacks. Returns `this`.          |
-| `get(ref)`                                     | Read-only component lookup, or `undefined`.                                                         |
-| `getMut(ref)` / `getMut(ref, callback)`        | Mutable lookup that marks the component modified. Callback form required outside deferred mode.     |
-| `ensure(ref)` / `ensure(ref, callback)`        | Mutable lookup that creates when missing. Callback form required outside deferred mode.             |
-| `ensureTarget(Relationship)`                   | Return a relationship target, creating an independent target when absent.                           |
-| `has(ref)`                                     | `true` when the component is attached.                                                              |
-| `modified(ref)`                                | Queue an `onSet`/`update` notification; coalesced while pending. Returns `this`.                    |
-| `remove(ref)`                                  | Detach a component; routes `exit`, then fires `onRemove`.                                           |
-| `destroy()`                                    | Remove all components, unregister, and apply incoming relationship cleanup.                         |
-| `target(rel)`                                  | Target entity of relationship `rel`, or `undefined`.                                                |
-| `children(rel)`                                | `ReadonlySet<Entity>` of entities targeting this one through `rel`.                                 |
-| `childOf(parent)`                              | Shorthand for `set(ChildOf, { target: parent })`. Returns `this`.                                   |
-| `parent` / `parent = p`                        | Getter/setter for the built-in `ChildOf` target; assigning `undefined` removes `ChildOf`.           |
-| `destroyed` / `alive`                          | `true` when the entity has been / has not been destroyed (marked for deletion).                     |
-| `onAdd/onSet/onRemove(handler)`                | Register hooks for this entity used as a component key. Return `this`.                              |
-| `onRetarget(handler)`                          | Register a retarget hook on a relationship component entity.                                        |
-| `toString()`                                   | Returns `"EntityN"`.                                                                                |
+| Property / Method                              | Description                                                                                                                                                           |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eid`                                          | Unique numeric entity id.                                                                                                                                             |
+| `world`                                        | The `World` that owns this entity.                                                                                                                                    |
+| `name`                                         | Identity name (getter/setter backed by the `Identity` component); `undefined` when unnamed.                                                                           |
+| `componentBitmask`                             | `Bitset` of component type ids attached. Used for archetype matching.                                                                                                 |
+| `components`                                   | Read-only `ArrayMap` view of attached instances keyed by type id (`forEach`, `get`, `has`, `size`).                                                                   |
+| `empty`                                        | `true` when no components are attached.                                                                                                                               |
+| `properties`                                   | Free-form `Map<string, any>` for module-level bookkeeping.                                                                                                            |
+| `meta`                                         | `ComponentMeta` for using this entity as a component key (created lazily).                                                                                            |
+| `instanceCount()`                              | Number of entities currently carrying this entity's eid as a component.                                                                                               |
+| `add(ref)` / `add(Relationship, target)`       | Attach an ordinary component, or add one explicit relationship edge. `target` accepts any `ComponentRef` resolved eagerly via `world.entity(target)`. Returns `this`. |
+| `attach(instance)` / `attach(Class, instance)` | Store an existing instance, replacing any previous one; fires set-side events. Returns `this`.                                                                        |
+| `set(ref, props)`                              | Attach/set ordinary data; relationships must exist and only ordinary fields are assigned.                                                                             |
+| `get(ref)`                                     | Read-only component lookup, or `undefined`.                                                                                                                           |
+| `getMut(ref)` / `getMut(ref, callback)`        | Mutable lookup that marks the component modified. Callback form required outside deferred mode.                                                                       |
+| `ensure(ref)` / `ensure(ref, callback)`        | Mutable lookup that creates when missing. Callback form required outside deferred mode.                                                                               |
+| `has(ref)`                                     | `true` when the component is attached.                                                                                                                                |
+| `modified(ref)`                                | Queue an `onSet`/`update` notification; coalesced while pending. Returns `this`.                                                                                      |
+| `remove(ref)` / `remove(Relationship, target)` | Detach a component/all edges, or remove one relationship edge. `target` accepts any `ComponentRef` resolved eagerly via `world.entity(target)`.                       |
+| `destroy()`                                    | Remove all components, unregister, and apply incoming relationship cleanup.                                                                                           |
+| `target(rel)`                                  | One current target entity of relationship `rel`, or `undefined`; not a stable selection policy.                                                                       |
+| `targets(rel)`                                 | Readonly snapshot of all targets; ordering is unspecified.                                                                                                            |
+| `hasTarget(rel, target)`                       | `true` when the specific relationship edge exists.                                                                                                                    |
+| `children(rel)`                                | `ReadonlySet<Entity>` of entities targeting this one through `rel`.                                                                                                   |
+| `childOf(parent)`                              | Shorthand for `add(ChildOf, parent)`. Returns `this`.                                                                                                                 |
+| `parent` / `parent = p`                        | Getter/setter for the built-in `ChildOf` target; assigning `undefined` removes `ChildOf`.                                                                             |
+| `destroyed` / `alive`                          | `true` when the entity has been / has not been destroyed (marked for deletion).                                                                                       |
+| `on(event, handler, insert?)`                  | Register a handler for a hook event on this component's meta. `insert` defaults to `false` (append); `true` prepends. Returns `this`.                                 |
+| `off(event, handler)`                          | Remove a previously-registered handler by reference. Idempotent. Returns `this`.                                                                                      |
+| `toString()`                                   | Returns `"EntityN"`.                                                                                                                                                  |