@vworlds/vecs 1.0.43 → 1.0.44

package/docs/README.md

@@ -14,13 +14,13 @@ Read in this order the first time through:
 3. [Execution model](./execution-model.md) — phases, the pipeline, deferred mutation, reactive
    routing. Read this before designing anything non-trivial.
 4. Subsystem guides, in any order:
-   - [Components](./components.md) — registration, hooks, exclusivity, cleanup policies,
+   - [Components](./components.md) — registration, hooks, traits, exclusivity, cleanup policies,
      interfaces, singletons.
-   - [Entities](./entities.md) — creation, lookup, the component API, lifecycle.
+   - [Entities](./entities.md) — creation, lookup, the component API, relationship targets, lifecycle.
    - [Systems](./systems.md) — membership, reactive callbacks, callback options, `each`/`run`, cadence, injection.
    - [Queries and filters](./queries-and-filters.md) — the query DSL, live queries, one-shot
      filters, grouped queries, `Bitset`.
-   - [Relationships](./relationships.md) — entity-to-entity links, hierarchy, cleanup cascades.
+   - [Relationships](./relationships.md) — links, target creation and ownership, hierarchy, cleanup cascades.
    - [Modules](./modules.md) — packaging features, composition, the built-in modules.
 5. [Design guide](./design-guide.md) — opinionated patterns and anti-patterns distilled from real
    designs. Read it once you know the machinery.
@@ -36,11 +36,11 @@ Keep the [Glossary](./glossary.md) at hand for terminology.
 | [getting-started.md](./getting-started.md)         | A runnable tutorial from `npm install` to a ticking world.                                   |
 | [concepts.md](./concepts.md)                       | The core vocabulary and how the pieces relate.                                               |
 | [execution-model.md](./execution-model.md)         | `world.progress`, the 8 built-in phases, deferred commands, flush boundaries, event routing. |
-| [components.md](./components.md)                   | `world.component`, hooks, exclusive groups, `CleanupPolicy`, `Implements`, `Singleton`.      |
-| [entities.md](./entities.md)                       | `world.entity`, `add`/`set`/`get`/`remove`/`destroy`, deferred read semantics.               |
+| [components.md](./components.md)                   | Component registration, hooks, traits, exclusivity, cleanup, aliases, and singletons.        |
+| [entities.md](./entities.md)                       | Entity creation, component mutation, relationship targets, lifecycle, deferred reads.        |
 | [systems.md](./systems.md)                         | `world.system`, `with`/`without`, `enter`/`update`/`exit`, callback options, tick sources.   |
 | [queries-and-filters.md](./queries-and-filters.md) | `QueryDSL`, `Query`, `Filter`, `groupBy`, `ignoreSource`.                                    |
-| [relationships.md](./relationships.md)             | `Relationship`, `ChildOf`/`DependsOn`, `parent`/`children`, `Traversable`, cascades.         |
+| [relationships.md](./relationships.md)             | Relationships, target creation and ownership, hierarchy, traversal, and cleanup cascades.    |
 | [modules.md](./modules.md)                         | `Module<Config>`, `world.module`, composition, built-in modules.                             |
 | [design-guide.md](./design-guide.md)               | Patterns, anti-patterns, and a Phaser render-layer case study.                               |
 | [utilities.md](./utilities.md)                     | Public helper classes: `Events`, `ArrayMap`, `IterableArrayMap`, plus `Bitset` cross-ref.    |

package/docs/components.md

@@ -71,7 +71,7 @@ Pass `idPools` to the `World` constructor to change ranges (each entry is an `Id
 released this frame is not immediately recycled. `world.peekNextEid(poolName)` returns the next id
 a pool would allocate without reserving it. Id 0 is reserved.
 
-## Hooks: `onAdd`, `onSet`, `onRemove`
+## Hooks: `onAdd`, `onSet`, `onRemove`, `onRetarget`
 
 The `Component` entity exposes lifecycle hooks fired for every entity carrying the component:
 
@@ -83,11 +83,15 @@ world
   .onRemove((entity, sprite) => sprite.destroy(scene, entity));
 ```
 
-| Hook       | Fires when…                                                                                                                                    |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `onAdd`    | The component is first attached (`add`, or `set` on an entity that lacked it).                                                                 |
-| `onSet`    | `entity.set(C, props)` applies data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` marks it dirty. |
-| `onRemove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                             |
+| Hook       | Fires when…                                                                                                                                               |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onAdd`    | The component is first attached (`add`, or `set` on an entity that lacked it).                                                                            |
+| `onSet`    | `entity.set(C, props)` applies data, `entity.attach(instance)` stores an instance, `entity.modified(C)` is called, or `getMut` / `ensure` marks it dirty. |
+| `onRemove` | The component is detached (`entity.remove(C)`), or the owning entity is destroyed.                                                                        |
+
+Relationship component entities additionally expose `onRetarget`. It fires after an existing
+relationship changes to a different target, once `target` and `children` already reflect the new
+reverse-index state. Initial assignment, same-target `set`, and removal do not fire it.
 
 Handlers receive `(entity, componentInstance)` — component instances do not carry entity
 references, so the entity is passed explicitly. Hooks fire synchronously when the corresponding
@@ -95,6 +99,59 @@ command is applied (see [Execution model](./execution-model.md#reactive-routing)
 resource management and cross-cutting reactions that aren't worth a system; use systems when the
 reaction belongs to a phase.
 
+## Component traits: policy on component entities
+
+Registered components are themselves entities. Attach a configuration component to a component
+entity to change policy for every use of that component type. vecs calls these configuration
+components **component traits**:
+
+```ts
+world.component(Gravity).add(Singleton);
+world.component(Inventory).add(OwnedTarget);
+world.component(ChildOf).add(Traversable);
+world.component(Orange).set(Implements, { interfaces: [Fruit] });
+```
+
+| Trait/declaration | Applies to                         | Effect                                                               |
+| ----------------- | ---------------------------------- | -------------------------------------------------------------------- |
+| `Singleton`       | Concrete components                | Allows at most one carrier entity                                    |
+| `Implements`      | Non-relationship components        | Exposes concrete data through abstract aliases                       |
+| `Traversable`     | Relationships                      | Maintains hierarchy depth for cascade ordering                       |
+| `OwnedTarget`     | Relationships other than `ChildOf` | Owns the active target through `ChildOf` and destructive replacement |
+
+Traits declare policy; their built-in modules install the hooks and maintain the metadata that
+enforce it. Configure traits in feature-module setup rather than opportunistically inside systems.
+Do not assume all traits have the same lifecycle:
+
+- Add `Singleton` before component instances exist.
+- Add `OwnedTarget` before relationship instances exist; it does not backfill.
+- `Traversable` backfills existing relationship instances.
+- Setting or removing `Implements` recomputes interface aliases.
+
+Treat traits as setup policy unless their documentation explicitly supports runtime changes. Before
+writing custom component-type bookkeeping, check whether an existing trait already expresses the
+invariant.
+
+Custom traits use the same mechanism. Keep the trait class as data and put its behavior in a module:
+
+```ts
+class Audited {}
+
+class AuditModule extends Module {
+  public init(): void {
+    this.world.component(Audited).onAdd((component) => {
+      component.onSet((entity) => console.log("changed", component.meta.Class.name, entity.eid));
+    });
+  }
+}
+
+world.module(AuditModule);
+world.component(Position).add(Audited);
+```
+
+Create a custom trait only when several component types need the same reusable, declarative policy.
+For one component type, register hooks directly in its owning module.
+
 ## Exclusive component groups
 
 `world.setExclusiveComponents(A, B, C)` declares a mutually exclusive group: setting one
@@ -183,7 +240,7 @@ Rules (enforced by `ImplementsModule`, `lib/vecs/src/modules/implements.ts`):
 
 - **Aliases are read/query only.** `get`, `has`, `with`, `filter`, and injection accept an
   interface type; mutation must go through the concrete component. `add`, `set`, `remove`,
-  `modified`, `getMut`, and `attach` on an interface throw at runtime (and `add`/`set` are
+  `modified`, `getMut`, `ensure`, and `attach` on an interface throw at runtime (and `add`/`set` are
   rejected by TypeScript for abstract classes).
 - **Declarations are transitive.** `Orange` implements `Fruit`, `Fruit` implements `Food`, so an
   entity with `Orange` matches `with(Food)`. Cyclic declarations throw.
@@ -249,12 +306,13 @@ interface markers for polymorphic dispatch — is in the
 A `Component<T>` is an `Entity` subclass, so the full [entity API](./entities.md#reference)
 applies. On top of it:
 
-| Member              | Description                                                      |
-| ------------------- | ---------------------------------------------------------------- |
-| `onAdd(handler)`    | Register an add hook. Returns the component entity for chaining. |
-| `onRemove(handler)` | Register a remove hook.                                          |
-| `onSet(handler)`    | Register a set/modified hook.                                    |
-| `meta`              | The `ComponentMeta` bookkeeping record.                          |
+| Member                | Description                                                          |
+| --------------------- | -------------------------------------------------------------------- |
+| `onAdd(handler)`      | Register an add hook. Returns the component entity for chaining.     |
+| `onRemove(handler)`   | Register a remove hook.                                              |
+| `onRetarget(handler)` | Register a relationship retarget hook. Throws for non-relationships. |
+| `onSet(handler)`      | Register a set/modified hook.                                        |
+| `meta`                | The `ComponentMeta` bookkeeping record.                              |
 
 ### `ComponentMeta` (`lib/vecs/src/component_meta.ts`)
 

package/docs/concepts.md

@@ -20,9 +20,10 @@ every idiom in the [Design guide](./design-guide.md) is a consequence of taking
 | **System**               | A `Query` plus per-tick logic (`update`, `each`, `run`), assigned to one pipeline phase.                    |
 | **Query**                | A reactive, always-up-to-date set of entities matching a predicate, with `enter`/`exit`/`update` callbacks. |
 | **Filter**               | A non-reactive, one-shot scan: walks all world entities on each `forEach` call.                             |
-| **Hook**                 | Lightweight `onAdd` / `onRemove` / `onSet` callbacks registered per component class.                        |
+| **Hook**                 | Lightweight component callbacks (`onAdd` / `onSet` / `onRemove`, plus relationship `onRetarget`).           |
 | **Phase**                | Marker component for entities used as pipeline ordering anchors.                                            |
 | **Relationship**         | A component whose `target` field points at another entity, with reverse lookup and cleanup cascades.        |
+| **Component trait**      | Policy attached to a component entity, configuring every use of that component type.                        |
 | **Module**               | A unit of packaging: a class whose `init()` registers components, systems, phases, and policy.              |
 | **Exclusive components** | A group of components where at most one may exist on any entity at a time.                                  |
 | **Implements**           | Declares abstract/interface component aliases for a concrete component, for polymorphic queries.            |
@@ -43,6 +44,11 @@ own. All behavior lives in systems (and, for small cross-cutting reactions, in h
 is what makes composition work: any system can operate on any entity that happens to carry the
 right components, and adding a capability to an entity is just adding a component.
 
+Because a registered component is also an entity, it can itself carry components. Built-in
+**component traits** use that meta-ECS layer to declare reusable policy: `Singleton` constrains a
+component, `Implements` declares aliases, and `Traversable` / `OwnedTarget` configure relationships.
+The trait remains data; a module owns the hooks and metadata behavior it activates.
+
 Prefer many small, single-purpose components over one large one. An entity that never rotates
 simply omits `Rotation`; absence encodes "not applicable". See
 [Components](./components.md).
@@ -77,7 +83,7 @@ on component combinations. The canonical example is the companion-component patt
 
 ## Where each topic lives
 
-- Registering, configuring, and hooking components → [Components](./components.md)
+- Registering, configuring, hooking, and applying traits to components → [Components](./components.md)
 - Creating, mutating, and destroying entities → [Entities](./entities.md)
 - System membership, callbacks, and cadence → [Systems](./systems.md)
 - The query DSL, live queries, filters, grouping → [Queries and filters](./queries-and-filters.md)

package/docs/design-guide.md

@@ -154,6 +154,31 @@ Use them for resource management and cross-cutting reactions that aren't worth a
 the difference from systems: hooks are per-component-instance and run at the mutation site;
 systems are queries that run in a phase.)
 
+### Component traits: policy on component entities
+
+A registered component is also an entity. Components attached to that component entity can declare
+policy for every use of the component type; these configuration components are **component traits**:
+
+```ts
+world.component(Gravity).add(Singleton);
+world.component(Inventory).add(OwnedTarget);
+world.component(ChildOf).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 |
+
+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
+policy, `Traversable` backfills, and `Implements` recomputes declarations. Do not assume traits are
+dynamically removable. See the [Components guide](./components.md#component-traits-policy-on-component-entities)
+for the full model and custom-trait guidance.
+
 ### Exclusive component groups
 
 `world.setExclusiveComponents(A, B, C)` declares a mutually exclusive set: setting one
@@ -178,6 +203,18 @@ entity.target(InCell); // the target entity
 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:
+
+```ts
+world.component(Inventory).add(OwnedTarget);
+const inventory = player.ensureTarget(Inventory); // inventory is 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"`
@@ -543,6 +580,86 @@ or when the callback is intentionally "future changes only."
 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.
 
+### Owned target entities (entity-valued properties)
+
+Before adding a nested object to a component or a side map from owner eid to state, ask whether the
+value is really one ECS sub-entity. Use an owned target when all of these are true:
+
+- The owner has zero or one value for the concern.
+- The value needs its own optional components, systems, or query identity.
+- The value is exclusively owned and never shared.
+- Replacement, relationship removal, and owner destruction should destroy it.
+
+```ts
+class Inventory extends Relationship {}
+class InventoryState {}
+class Capacity {
+  slots = 0;
+}
+class Weight {
+  current = 0;
+}
+
+world.component(Inventory).add(OwnedTarget);
+world.component(InventoryState);
+world.component(Capacity);
+world.component(Weight);
+
+const inventory = player.ensureTarget(Inventory);
+inventory.add(InventoryState).set(Capacity, { slots: 20 }).set(Weight, { current: 0 });
+```
+
+`Inventory` is an entity-valued property of `player`, but it remains entirely inside the ECS.
+Inventory systems operate on inventory entities without adding inventory-specific state to every
+player archetype:
+
+```ts
+world
+  .system("inventory.weight")
+  .with(InventoryState, Weight)
+  .each([Weight], (_inventory, [weight]) => {
+    void weight.current;
+  });
+```
+
+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         |
+
+Inside deferred execution, mutate the entity returned by `ensureTarget`; do not immediately re-read
+the relationship:
+
+```ts
+world.defer(() => {
+  const inventory = player.ensureTarget(Inventory);
+  inventory.set(Capacity, { slots: 20 }); // correct: pending 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                 |
+
+Good fits include an inventory aggregate, equipment loadout, character progression sheet, AI
+blackboard, quest journal, ability book, or unique vehicle subsystem. Individual inventory items,
+abilities, objectives, and other collections should remain separate entities. Networking remains
+explicit: register the relationship and replicate the target's required components; `OwnedTarget`
+itself is local lifecycle policy.
+
 ### Initialize via opt-in `update`-on-entry
 
 When an update callback owns both initialization and later changes, pass `{ onEnter: true }`. The
@@ -559,6 +676,10 @@ system after whatever produces the entity/companion.
 | 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.                                                                                                                                             |
@@ -588,6 +709,14 @@ system after whatever produces the entity/companion.
   `vecs-protocol` registers it as an `"entity"` wire field (u32 eid) at module
   load, so `Relationship` subclasses listed in `networkComponents` serialise
   correctly.
+- **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`.
+  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.
 - **`world.module(M)` runs `init` once.** Re-registering with a different config throws.
 
 ---

package/docs/entities.md

@@ -47,6 +47,8 @@ for end-of-session teardown, not selective resets.
 e.add(Position); // attach with default field values (idempotent)
 e.set(Position, { x: 100 }); // attach if needed, assign props, fire onSet/update
 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
@@ -63,10 +65,12 @@ key.
   `onSet`.
 - `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.
 
-### `getMut`: mutating in place
+### `getMut` and `ensure`: mutating in place
 
 `get` returns a `Readonly` view. To mutate, use `getMut`, which marks the component modified for
 you:
@@ -83,8 +87,50 @@ e.getMut(Velocity, (vel) => {
 });
 ```
 
-Calling `getMut(C)` without a callback outside deferred mode throws. `getMut` also throws for
-relationship components (retarget with `set` instead — see
+Use `ensure` when absence should mean "create with defaults, then mutate":
+
+```ts
+e.ensure(Velocity, (vel) => {
+  vel.vx = 2;
+});
+```
+
+`ensure` always returns a component for a live entity. Calling it on a destroyed entity throws.
+When several calls ensure the same missing component during one deferred scope, they return the
+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.
 
 ### `attach`: storing an existing instance
@@ -111,6 +157,8 @@ Inside a system body, a `forEach`, or a `world.defer` block, all of the mutators
 commands instead of applying immediately, and reads return the pre-mutation state until the queue
 drains. The exact read-after-write rules are tabulated in
 [Execution model — deferred mutation](./execution-model.md#deferred-mutation-and-flush-boundaries).
+`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.
 
 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
@@ -135,6 +183,7 @@ Any entity can serve as a component key: `other.add(keyEntity)` attaches a marke
 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(...)`.
 
 ## Relationships, in brief
 
@@ -164,6 +213,8 @@ is in [Relationships](./relationships.md).
 | `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`.                                           |
@@ -174,4 +225,5 @@ is in [Relationships](./relationships.md).
 | `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"`.                                                                                |

package/docs/execution-model.md

@@ -97,9 +97,9 @@ built-in taxonomy.
 ## Deferred mutation and flush boundaries
 
 Inside a system body, a `Query.forEach` / `Filter.forEach` iteration, or any `world.defer(...)`
-block, the world is in **deferred mode**: entity mutations (`add` / `attach` / `set` / `remove` /
-`destroy` / `modified`, and `world.entity()` creation) are queued as commands instead of applied
-inline. The queue drains when the scope that opened deferral ends.
+block, the world is in **deferred mode**: entity mutations (`add` / `attach` / `set` / `ensure` /
+`ensureTarget` / `remove` / `destroy` / `modified`, and `world.entity()` creation) are queued as
+commands instead of applied inline. The queue drains when the scope that opened deferral ends.
 
 For the pipeline this means: **a structural change made by system A is applied in the flush
 immediately after A finishes, so it is visible to every later system in the same tick** — later in
@@ -116,8 +116,12 @@ While a mutation is queued but not yet applied, reads return the pre-mutation st
 | `entity.add(C)`           | `undefined` — no instance has been created yet.            |
 | `entity.attach(instance)` | `undefined`, if `C` was absent before.                     |
 | `entity.set(C, props)`    | The **previous** value (or `undefined` if `C` was absent). |
+| `entity.ensure(C)`        | A mutable component, even when newly created.              |
 | `entity.remove(C)`        | Still the component instance.                              |
 
+`entity.ensureTarget(R)` similarly returns one shared pending target while `entity.target(R)`
+continues to return the previously committed target until flush.
+
 Outside any deferred scope (top-level user code), the same calls execute inline and effects are
 visible immediately.
 
@@ -156,7 +160,7 @@ Three routing rules worth memorizing:
 - **`exit` reads a snapshot.** Components injected into an `exit` callback are captured when the
   exit is routed, so they are still resolvable even though they are being (or have been) removed.
 - **In-place mutation needs `modified`.** Assigning to component fields directly notifies no one.
-  Call `entity.modified(C)` (or use `set` / `getMut`) to route the change.
+  Call `entity.modified(C)` (or use `set` / `getMut` / `ensure`) to route the change.
 
 ## Why the patterns work
 

package/docs/glossary.md

@@ -50,8 +50,9 @@ entity lifecycle API. [Utilities](./utilities.md#events).
 **Filter** — a non-reactive, one-shot predicate that scans world entities on each `forEach`.
 [Queries and filters](./queries-and-filters.md#filters-one-shot-scans).
 
-**Hook** — an `onAdd` / `onSet` / `onRemove` callback registered per component class, fired
-synchronously at the mutation site. [Components](./components.md#hooks-onadd-onset-onremove).
+**Hook** — an `onAdd` / `onSet` / `onRemove` callback registered per component class, or an
+`onRetarget` callback for relationships, fired synchronously at the mutation site.
+[Components](./components.md#hooks-onadd-onset-onremove-onretarget).
 
 **Implements / interface alias** — a declaration that a concrete component is queryable through
 abstract/interface component types; aliases are read-only views of the same instance.
@@ -71,6 +72,10 @@ visited entity and the source entity of each injected slot.
 **Module** — a packaging unit (`class M extends Module<Config>`) whose `init()` registers
 components, systems, and policy once per world. [Modules](./modules.md).
 
+**Owned target entity** — a zero-or-one aggregate entity targeted through a relationship carrying
+the `OwnedTarget` trait. It is parented to the source and destroyed when displaced, when the
+relationship is removed, or when the source dies. [Relationships](./relationships.md#owned-targets).
+
 **Phase** — an entity used as a pipeline ordering anchor (tagged with the `Phase` component);
 systems attach to exactly one phase via `DependsOn`.
 [Execution model](./execution-model.md#phases-the-pipeline-spine).
@@ -102,6 +107,10 @@ assigned to one phase. [Systems](./systems.md).
 **Tick source** — a clock (`IntervalTickSource`, `RateTickSource`, or another system) that gates
 how often a system fires. [Systems](./systems.md#cadence-interval-rate-and-tick-sources).
 
+**Trait (component trait)** — policy attached as a component to a registered component entity,
+configuring every use of that component type. Built-ins include `Singleton`, `Implements`,
+`Traversable`, and `OwnedTarget`. [Components](./components.md#component-traits-policy-on-component-entities).
+
 **Watchlist** — the set of component types a query or system reacts to via `update`, stored as a
 bitmask. [Systems](./systems.md#reactive-callbacks-enter-update-exit).
 

package/docs/modules.md

@@ -89,13 +89,13 @@ Guidelines:
 Every `World` constructor installs these (`lib/vecs/src/world/world.ts`); you interact with their
 _components_, not with the module objects:
 
-| Module                | Provides                                                                                                                                                  |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `IdentityModule`      | The `Identity` name component and the name → entity index behind `world.entity("name")` / `entity.name`.                                                  |
-| `ImplementsModule`    | Maintains [`Implements` interface aliases](./components.md#interface-aliases-with-implements) and their transitive closure.                               |
-| `SingletonModule`     | Enforces the [`Singleton`](./components.md#singletons-and-world-global-data) one-carrier constraint.                                                      |
-| `RelationshipsModule` | Registers `ChildOf` (with the `Delete` cascade) and maintains [`Traversable` depth tracking](./relationships.md#traversal-order-traversable-and-cascade). |
-| `PipelineModule`      | Creates the eight [built-in phases](./execution-model.md#phases-the-pipeline-spine) and installs the default pipeline query.                              |
+| Module                | Provides                                                                                                                                                                                             |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IdentityModule`      | The `Identity` name component and the name → entity index behind `world.entity("name")` / `entity.name`.                                                                                             |
+| `ImplementsModule`    | Maintains [`Implements` interface aliases](./components.md#interface-aliases-with-implements) and their transitive closure.                                                                          |
+| `SingletonModule`     | Enforces the [`Singleton`](./components.md#singletons-and-world-global-data) one-carrier constraint.                                                                                                 |
+| `RelationshipsModule` | Registers `ChildOf`, installs [`OwnedTarget`](./relationships.md#owned-targets) ownership, and maintains [`Traversable` depth tracking](./relationships.md#traversal-order-traversable-and-cascade). |
+| `PipelineModule`      | Creates the eight [built-in phases](./execution-model.md#phases-the-pipeline-spine) and installs the default pipeline query.                                                                         |
 
 All are exported, so a custom world setup can reuse them.