@forgeax/engine-ecs 0.0.0-dev.8d955ade1c79

package/src/entity-handle.ts

@@ -0,0 +1,104 @@
+// @forgeax/engine-ecs — Entity handle.
+//
+// Encoding: u32 = (generation << 24) | (index & 0xFFFFFF)
+//   - index:      24 bits — supports up to 16_777_215 simultaneous entities.
+//   - generation:  8 bits — retirement when gen exceeds 255 (gen 255 usable);
+//     index permanently retired when bumped generation would reach 256.
+//
+// Key difference from @forgeax/engine-ecs: generation does NOT wrap 255 → 0.
+// When generation would exceed 255 (256), the index is permanently retired
+// from the free list to prevent handle aliasing (D-08).
+//
+// feat-20260623-asset-handle-generation M2 / w4: encodeEntity/decodeEntity/
+// entityIndex/entityGeneration are now thin wrappers over the shared gen-slot
+// codec in @forgeax/engine-types (pack / unpackSlot / unpackGen). The
+// `EntityIndexOverflowError` throw and `ENTITY_NULL_RAW` sentinel stay in ecs
+// (D-1). Constants re-export codec values for backward-compatible names.
+
+import { MAX_GEN, MAX_SLOT, pack, unpackGen, unpackSlot } from '@forgeax/engine-types';
+import { EntityIndexOverflowError } from './errors';
+
+/**
+ * Branded `number` representing an Entity handle. Stored as a JS `number` but
+ * holds the u32 bit pattern (generation << 24) | index.
+ *
+ * The phantom `__entity` brand prevents accidental mixing with other numbers.
+ *
+ * Naming: the type-space alias is `EntityHandle` (the branded number that
+ * identifies a row). The same-named value-space `Entity` re-exported from the
+ * package barrel is the id=0 component token (see `./entity`).
+ */
+export type EntityHandle = number & { readonly __entity: unique symbol };
+
+/** Maximum representable entity index (2^24 - 1 = 16_777_215). Re-exports codec MAX_SLOT. */
+export const ENTITY_MAX_INDEX = MAX_SLOT;
+
+/** Maximum representable generation (2^8 - 1 = 255). Re-exports codec MAX_GEN. */
+export const ENTITY_MAX_GENERATION = MAX_GEN;
+
+/**
+ * Sentinel u32 value reserved for the "null entity" slot in `entity`-typed
+ * component fields.
+ *
+ * The encoding `(gen << 24) | index` yields `0xFFFFFFFF` only at the very
+ * last valid (gen=255, index=0xFFFFFF) entity, which retires permanently on
+ * its first despawn (D-08). Carving out this single bit pattern as the null
+ * sentinel costs at most one slot at the far edge of the entity space.
+ *
+ * Stored u32 column reads compare against `ENTITY_NULL_RAW` first; the
+ * column-level `Entity | null` decode lives in `world.readRow`.
+ *
+ * Scene-as-World-Blueprint anchor (feat-20260514 w12, R-8 lockdown):
+ *   This module (`packages/ecs/src/entity.ts`) is the canonical export site
+ *   for the entity null sentinel. Downstream consumers (M2 instantiate
+ *   layer 3 fallback for `'entity'`-typed component fields, w22) must import
+ *   from the package barrel:
+ *
+ *     import { ENTITY_NULL_RAW } from '@forgeax/engine-ecs'
+ *
+ *   The raw `0xFFFFFFFF` literal MUST NOT be duplicated at consumer sites
+ *   (charter proposition 1: SSOT lives here). The decoded JS-side value is
+ *   `null` (returned by `world.get(e, C).<entityField>`). Layer 3 default
+ *   for `'entity'` keyword fields stores `ENTITY_NULL_RAW` into the u32
+ *   column, which decodes back to `null` on read. ecs-managed-buffer feat
+ *   export verification (w12 grep): see `packages/ecs/src/index.ts` line
+ *   re-exporting this constant alongside `ENTITY_MAX_GENERATION /
+ *   ENTITY_MAX_INDEX`. No add-only fallback re-export is required at this
+ *   time.
+ */
+export const ENTITY_NULL_RAW = 0xffffffff;
+
+/**
+ * Encode (index, generation) into a u32 entity handle.
+ *
+ * Delegates to shared codec `pack(index, generation)` after ecs-specific
+ * overflow validation. The `>>> 0` anti-ToInt32 guard is inherited from the
+ * codec (D-7 hard constraint).
+ *
+ * @throws EntityIndexOverflowError when `index > ENTITY_MAX_INDEX` or `index < 0`.
+ */
+export function encodeEntity(index: number, generation: number): EntityHandle {
+  if (index < 0 || index > ENTITY_MAX_INDEX) {
+    throw new EntityIndexOverflowError(index);
+  }
+  return pack(index, generation) as EntityHandle;
+}
+
+/** Decode a u32 entity handle into its (index, generation) pair via shared codec. */
+export function decodeEntity(entity: EntityHandle): { index: number; generation: number } {
+  const e = entity as unknown as number;
+  return {
+    index: unpackSlot(e),
+    generation: unpackGen(e),
+  };
+}
+
+/** Extract just the index slot from an entity handle via shared codec. */
+export function entityIndex(entity: EntityHandle): number {
+  return unpackSlot(entity as unknown as number);
+}
+
+/** Extract just the generation slot from an entity handle via shared codec. */
+export function entityGeneration(entity: EntityHandle): number {
+  return unpackGen(entity as unknown as number);
+}

package/src/entity.ts

@@ -0,0 +1,140 @@
+// @forgeax/engine-ecs - Entity component (feat-20260602-archetype-stores-full-packed-entity M1 / w1).
+//
+// Entity identity is modelled as a real id=0 ECS component `Entity`, whose sole
+// field `self` stores the full 32-bit packed entity handle (generation << 24 |
+// index). Every archetype carries this column unconditionally (it is essential
+// and cannot be removed), so an entity's own handle is read through the exact
+// same query / read path as Transform / MeshRenderer columns:
+//
+//   const query = world.query({ read: [Transform] }).unwrap();
+//   for (const row of query) row.entity;
+//   world.get(e, Entity).unwrap().self === e
+//
+// This retires the "entity is an archetype side-array + three-step rebuild"
+// implementation detail (index slot -> generation lookup -> encodeEntity) in
+// favour of a single uniform column read.
+//
+// id=0 structural guarantee: `Entity` MUST be the first `defineComponent`
+// evaluated in the process so the owner identity assigns it 0. The package
+// barrel (packages/ecs/src/index.ts) force-evaluates this module before any
+// other component-defining module and asserts the invariant fail-fast.
+// See plan-strategy D-1 / D-6b (LP-1): the hard-coded 0 + barrel forced
+// registration + startup throw is the locked design; no UECS-style runtime
+// token lookup is introduced (the hot-path archetype column key stays a numeric
+// owner-assigned component identity).
+//
+// charter mapping: P4 (consistent abstraction -- reading the entity handle is
+// reading any other column) + P3 (id=0 drift surfaces as a structured startup
+// throw, never a silent runtime mis-id) + P1 (single top-level import surface).
+
+import type { ComponentId } from './component';
+import { componentId, defineComponent } from './component';
+
+/**
+ * The id=0 essential `Entity` component. Its single `self` field carries the
+ * full packed entity handle for the row it sits on (written at spawn time).
+ *
+ * Naming convention (feat-20260611-ecs-storage-naming-ssot):
+ *
+ *   - Value-space `Entity` (this const) is the id=0 component token. It is
+ *     looked up by name (`'Entity'`) at component-registration time and used
+ *     as a value (`world.spawn`, `world.get(entity, Entity)`).
+ *   - Type-space `EntityHandle` (the branded number, exported from `../entity`)
+ *     is the row-identifier handle type. It is used in `: EntityHandle`
+ *     annotations.
+ *
+ * The two no longer share a name -- the prior intentional coexistence (a
+ * single `Entity` symbol carrying both meanings via TS namespace merging) was
+ * dropped because two-roles-one-name created repeated AI-user confusion when
+ * reading `: Entity` annotations (is this the handle or the token?). The id=0
+ * component token's name (the literal string `'Entity'`) is preserved for
+ * runtime stability; only the type-space alias was renamed.
+ *
+ * @example Read an entity's own handle through a query:
+ *   const query = world.query({ read: [Transform] }).unwrap();
+ *   for (const row of query) {
+ *     const handle = row.entity;
+ *   }
+ *
+ * @example Use `world.get` as a general liveness probe:
+ *   const r = world.get(e, Entity);
+ *   if (!r.ok) { // r.error.code === 'stale-entity' for a despawned handle
+ *   }
+ */
+export const Entity = defineComponent('Entity', {
+  // Layer-2 default is never observed: `world.spawn` always overwrites `self`
+  // with the freshly encoded handle for the row. `null` is the type-correct
+  // "no handle yet" placeholder (`'entity'` decodes to `EntityHandle | null`).
+  self: { type: 'entity', default: null },
+});
+
+/**
+ * Marks an entity as disabled.
+ *
+ * Queries exclude this tag by default. Add `Disabled` to a query's `with`
+ * tuple when the query must inspect or re-enable disabled entities.
+ */
+export const Disabled = defineComponent('Disabled', {});
+
+/**
+ * SSOT for component ids that are essential to every archetype. Every archetype
+ * carries the columns named by these ids unconditionally (they cannot be added
+ * or removed via `addComponent` / `removeComponent`). Currently only `Entity`
+ * is essential -- the row-identity column that lets every entity read its own
+ * packed handle (`world.get(e, Entity).self === e`) through the same column
+ * path as any other component (feat-20260602 / charter P4).
+ *
+ * Frozen so consumers cannot mutate the SSOT. The barrel
+ * (`packages/ecs/src/index.ts`) re-exports this constant so the AI-facing
+ * `import { ESSENTIAL_COMPONENT_IDS } from '@forgeax/engine-ecs'` works.
+ *
+ * Physical location is `packages/ecs/src/entity.ts` -- the module that owns
+ * the `defineComponent('Entity', ...)` call, so reading the owner identity
+ * immediately after registration is well-defined. tweak-20260612-ecs-concept-
+ * compression lifted this file back from the historical `components/entity.ts`
+ * after `entity-handle.ts` freed up the `entity.ts` slot.
+ */
+export const ESSENTIAL_COMPONENT_IDS: ReadonlyArray<ComponentId> = Object.freeze([
+  componentId(Entity),
+]);
+
+/**
+ * Fold the essential component ids (currently `[componentId(Entity)]`) into a caller-
+ * supplied id list. Returns a NEW array; never mutates the input.
+ *
+ *   - If `ids` already contains every essential id, returns a deduped copy
+ *     (idempotent under repeated folding).
+ *   - Otherwise, returns `[...essential, ...ids]` with duplicates of the
+ *     essential ids removed.
+ *
+ * The empty input maps to `[componentId(Entity)]` -- the bare-archetype shape that a
+ * `world.spawn()` (no components) materialises.
+ *
+ * Single SSOT consumed by both `archetypeKey` (string-key fold) and
+ * `createArchetype` (column-build fold) so the two sites can never disagree
+ * on which ids are essential. Hot-path correctness is on `createArchetype`'s
+ * side: misalignment between key and columns silently drops fields.
+ *
+ * @example
+ *   foldEssentials([2, 5, 7])              // [componentId(Entity), 2, 5, 7]
+ *   foldEssentials([componentId(Entity), 2, 5]) // [componentId(Entity), 2, 5]
+ *   foldEssentials([componentId(Entity), componentId(Entity)]) // [componentId(Entity)]
+ *   foldEssentials([])                     // [componentId(Entity)]
+ */
+export function foldEssentials(ids: ReadonlyArray<ComponentId>): ComponentId[] {
+  const seen = new Set<ComponentId>();
+  const out: ComponentId[] = [];
+  for (const essential of ESSENTIAL_COMPONENT_IDS) {
+    if (!seen.has(essential)) {
+      seen.add(essential);
+      out.push(essential);
+    }
+  }
+  for (const id of ids) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}

package/src/errors/query-and-component-errors.ts

@@ -0,0 +1,200 @@
+/**
+ * Returned via `Result.err` from `world.removeComponent` when the caller tries
+ * to remove an essential (undeletable) component
+ * (feat-20260602-archetype-stores-full-packed-entity M1 / w3, plan-strategy
+ * D-3). The only essential component today is the id=0 `Entity` component: every
+ * archetype carries it unconditionally as the row's own packed handle, so
+ * removing it is structurally meaningless. The code name is deliberately
+ * generic (`remove-essential-component`, not entity-specific) so a future second
+ * essential component reuses it without a rename.
+ *
+ * `.code = 'remove-essential-component'`
+ * `.detail = { componentName }`
+ * `.hint` — names the essential component + states it cannot be removed.
+ */
+export class RemoveEssentialComponentError extends Error {
+  override readonly name = 'RemoveEssentialComponentError';
+  readonly code = 'remove-essential-component' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: { readonly componentName: string };
+
+  constructor(componentName: string) {
+    const hint = `Component "${componentName}" is essential (every entity carries it unconditionally) and cannot be removed. Despawn the entity instead if you want to retire it.`;
+    const expected = 'non-essential component';
+    super(
+      `removeComponent: essential component cannot be removed.\n` +
+        `  code: remove-essential-component\n` +
+        `  component: ${componentName}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { componentName };
+  }
+}
+
+/**
+ * Returned via the `Result` err branch when `instantiate` encounters a
+ * SceneAsset entity whose `components` map references a component name that was
+ * never passed to `defineComponent`.
+ *
+ * `.code = 'component-not-defined'`
+ * `.detail.name` — the offending component name.
+ *
+ * Promoting this to a class (rather than a bare object literal) keeps the
+ * scene-instantiate failure surface inside the `EcsError` class union, so the
+ * documented two-level narrow `cause instanceof EcsError` actually matches it
+ * (docs/feedbacks/2026-06-03 §6.2 Tier 4.2). `expected` / `hint` accept
+ * per-call overrides because the parent-passthrough (ChildOf) site needs a
+ * distinct message from the generic entity-component site.
+ */
+export class ComponentNotDefinedError extends Error {
+  override readonly name = 'ComponentNotDefinedError';
+  readonly code = 'component-not-defined' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: { readonly name: string };
+
+  constructor(componentName: string, opts?: { expected?: string; hint?: string }) {
+    const expected = opts?.expected ?? `component '${componentName}' defined before instantiate`;
+    const hint =
+      opts?.hint ??
+      `define the component via defineComponent('${componentName}', ...) before instantiating this SceneAsset`;
+    super(
+      `instantiate: component not defined.\n` +
+        `  code: component-not-defined\n` +
+        `  component: ${componentName}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { name: componentName };
+  }
+}
+
+/**
+ * Returned via `Result.err` from `world.spawn` / `world.addComponent` /
+ * `world.instantiateScene` / `Commands.spawn` when the caller-supplied
+ * data payload carries a key that is not declared in the target component's
+ * schema. The pre-fix behaviour silently dropped unknown keys inside
+ * `fillComponentDefaults` (which walked schema keys, never raw keys), so a
+ * typo like `MeshRenderer { material: h }` (singular legacy field name; the
+ * current schema has `materials: array<...>`) produced an empty-defaults row
+ * + an invisible / mid-grey entity downstream. Surfacing the typo at the
+ * spawn boundary collapses a class of "renders wrong, looks like a graphics
+ * bug" reports into a single explicit error.
+ *
+ * `.code = 'spawn-data-unknown-field'`
+ * `.detail = { component, field, knownFields }`
+ * `.hint` — names the offending field and lists the schema's known fields.
+ */
+export class SpawnDataUnknownFieldError extends Error {
+  override readonly name = 'SpawnDataUnknownFieldError';
+  readonly code = 'spawn-data-unknown-field' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly component: string;
+    readonly field: string;
+    readonly knownFields: readonly string[];
+  };
+
+  constructor(componentName: string, fieldName: string, knownFields: readonly string[]) {
+    const sortedKnown = [...knownFields].sort();
+    const expected = `field name in {${sortedKnown.join(', ')}}`;
+    const hint =
+      `'${fieldName}' is not a schema field of '${componentName}'. ` +
+      `Known fields: ${sortedKnown.join(', ')}. ` +
+      `Check for a typo or a stale single-vs-plural rename (e.g. 'material' vs 'materials').`;
+    super(
+      `${componentName}: spawn data carries unknown field.\n` +
+        `  code: spawn-data-unknown-field\n` +
+        `  component: ${componentName}\n` +
+        `  field: ${fieldName}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { component: componentName, field: fieldName, knownFields: sortedKnown };
+  }
+}
+export type QuerySpanUnavailableReason = 'optional-data' | 'row-change-filter' | 'sparse-component';
+
+export class QueryDescriptorConflictError extends Error {
+  override readonly name = 'QueryDescriptorConflictError';
+  readonly code = 'query-descriptor-conflict' as const;
+  readonly expected = 'each component occupies one descriptor role';
+  readonly hint: string;
+  readonly detail: { readonly componentName: string; readonly roles: readonly string[] };
+
+  constructor(componentName: string, roles: readonly string[]) {
+    const hint = `Remove ${componentName} from all but one of: ${roles.join(', ')}.`;
+    super(`Query descriptor roles conflict for ${componentName}.\n  hint: ${hint}`);
+    this.hint = hint;
+    this.detail = { componentName, roles };
+  }
+}
+
+export class QueryDataRequiresFieldsError extends Error {
+  override readonly name = 'QueryDataRequiresFieldsError';
+  readonly code = 'query-data-requires-fields' as const;
+  readonly expected = 'a component with at least one data field';
+  readonly hint: string;
+  readonly detail: { readonly componentName: string };
+
+  constructor(componentName: string) {
+    const hint = `Move tag ${componentName} to with or without.`;
+    super(`Query data access requires fields on ${componentName}.\n  hint: ${hint}`);
+    this.hint = hint;
+    this.detail = { componentName };
+  }
+}
+
+export class QuerySpanUnavailableError extends Error {
+  override readonly name = 'QuerySpanUnavailableError';
+  readonly code = 'query-span-unavailable' as const;
+  readonly expected = 'a descriptor whose rows form contiguous table ranges';
+  readonly hint = 'Use row iteration or split the query.';
+  readonly detail: { readonly reason: QuerySpanUnavailableReason };
+
+  constructor(reason: QuerySpanUnavailableReason) {
+    super(`Query spans are unavailable: ${reason}.\n  hint: Use row iteration or split the query.`);
+    this.detail = { reason };
+  }
+}
+
+export class QueryIterationInvalidatedError extends Error {
+  override readonly name = 'QueryIterationInvalidatedError';
+  readonly code = 'query-iteration-invalidated' as const;
+  readonly expected: string;
+  readonly hint = 'Use deferred Commands for structural mutation, then restart iteration.';
+  readonly detail: {
+    readonly expectedStructureEpoch: number;
+    readonly actualStructureEpoch: number;
+  };
+
+  constructor(expectedStructureEpoch: number, actualStructureEpoch: number) {
+    const expected = `structure epoch ${expectedStructureEpoch}`;
+    super(
+      `Query iteration was invalidated by structure epoch ${actualStructureEpoch}.\n  hint: ${'Use deferred Commands for structural mutation, then restart iteration.'}`,
+    );
+    this.expected = expected;
+    this.detail = { expectedStructureEpoch, actualStructureEpoch };
+  }
+}
+
+export class QueryIterationActiveError extends Error {
+  override readonly name = 'QueryIterationActiveError';
+  readonly code = 'query-iteration-active' as const;
+  readonly expected = 'one active iterator per Query';
+  readonly hint = 'Complete the active iterator or create an independent Query.';
+  readonly detail = {};
+
+  constructor() {
+    super('Query already has an active iterator.\n  hint: Complete it before iterating again.');
+  }
+}

package/src/errors/relationship-errors.ts

@@ -0,0 +1,198 @@
+// ────────────────────────────────────────────────────────────────────────────
+// feat-20260531-ecs-relationship-abstraction-bidirectional-sync M2 — closed-
+// union evolution +4 (plan-strategy D-5). Adds 4 `relationship-*` kebab codes
+// (27 -> 31, add-only minor per AGENTS.md Error model evolution contract):
+//
+//   - relationship-self-cycle                       (cycle / ancestor walk hit)
+//   - relationship-mirror-component-not-registered  (defineComponent gate a)
+//   - relationship-mirror-field-type-mismatch       (defineComponent gate b)
+//   - relationship-detach-mismatch                  (removeChild parent arg mismatch)
+//
+// `relationship-exclusive-violation` is intentionally NOT a member: exclusive
+// re-add is an automatic reparent (a success path, D-1 style), not an error.
+// Every detail object is a discriminated payload narrowed via EcsErrorDetail.
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returned via `Result.err` from `world.addChild` / `world.reparent` (M3) when
+ * a hierarchy write would form a cycle — either the child is its own parent
+ * (self-loop) or the proposed parent is already a descendant of the child
+ * (ancestor-walk hit). The `.detail` carries both the offending child entity
+ * and the ancestor entity that closed the cycle so AI users can locate the
+ * loop without re-walking the graph.
+ *
+ * `.code = 'relationship-self-cycle'`
+ * `.detail = { component, entity, ancestor }`
+ * `.hint` — names the child + ancestor that would close the cycle.
+ */
+export class RelationshipSelfCycleError extends Error {
+  override readonly name = 'RelationshipSelfCycleError';
+  readonly code = 'relationship-self-cycle' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly component: string;
+    readonly entity: number;
+    readonly ancestor: number;
+  };
+
+  constructor(component: string, entity: number, ancestor: number) {
+    const hint = `Linking entity ${entity} via "${component}" would close a cycle through ancestor ${ancestor}. Reparent to an entity that is not a descendant of ${entity}.`;
+    const expected = 'acyclic parent chain';
+    super(
+      `relationship: cycle detected.\n` +
+        `  code: relationship-self-cycle\n` +
+        `  component: ${component}\n` +
+        `  entity: ${entity}\n` +
+        `  ancestor: ${ancestor}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { component, entity, ancestor };
+  }
+}
+
+/**
+ * Thrown by `defineComponent` (feat-20260602 M2) when a component declares a
+ * `relationship.mirror` naming a component that has not yet been defined
+ * (AC-09). AI users defineComponent the mirror before the holder (mirror-then-
+ * holder order).
+ *
+ * The `.code` literal `relationship-mirror-component-not-registered` is kept
+ * unchanged across the M2 migration (deliberate terminology trade-off:
+ * external `.code` stability over wording precision); only the `.hint` text
+ * drops the register/registered phrasing in favour of defineComponent ordering
+ * guidance.
+ *
+ * `.code = 'relationship-mirror-component-not-registered'`
+ * `.detail = { component, mirror }`
+ * `.hint` — names the holder + the undefined mirror component.
+ */
+export class RelationshipMirrorComponentNotRegisteredError extends Error {
+  override readonly name = 'RelationshipMirrorComponentNotRegisteredError';
+  readonly code = 'relationship-mirror-component-not-registered' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: { readonly component: string; readonly mirror: string };
+
+  constructor(component: string, mirror: string) {
+    const hint = `Component "${component}" declares relationship.mirror = "${mirror}", but "${mirror}" has not been defined yet. defineComponent the mirror component before the holder (define them in mirror-then-holder order).`;
+    const expected = `mirror component "${mirror}" registered`;
+    super(
+      `relationship: mirror component not registered.\n` +
+        `  code: relationship-mirror-component-not-registered\n` +
+        `  component: ${component}\n` +
+        `  mirror: ${mirror}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { component, mirror };
+  }
+}
+
+/**
+ * Thrown by `defineComponent` (feat-20260602 M2) when the
+ * `relationship.field` on the mirror component is missing or its schema type
+ * is not the only legal back-reference storage shape `array<entity>`
+ * (AC-11 b). AI users declare the mirror field as `'array<entity>'`.
+ *
+ * `.code = 'relationship-mirror-field-type-mismatch'`
+ * `.detail = { component, mirror, field, actualType }`
+ * `.hint` — names the holder + mirror field + the type observed.
+ */
+export class RelationshipMirrorFieldTypeMismatchError extends Error {
+  override readonly name = 'RelationshipMirrorFieldTypeMismatchError';
+  readonly code = 'relationship-mirror-field-type-mismatch' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly component: string;
+    readonly mirror: string;
+    readonly field: string;
+    readonly actualType: string;
+  };
+
+  constructor(component: string, mirror: string, field: string, actualType: string) {
+    const hint = `Component "${component}" mirror "${mirror}".${field} has type "${actualType}"; the reverse-list field must be declared as 'array<entity>'.`;
+    const expected = "mirror field type === 'array<entity>'";
+    super(
+      `relationship: mirror field type mismatch.\n` +
+        `  code: relationship-mirror-field-type-mismatch\n` +
+        `  component: ${component}\n` +
+        `  mirror: ${mirror}\n` +
+        `  field: ${field}\n` +
+        `  actualType: ${actualType}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { component, mirror, field, actualType };
+  }
+}
+
+/**
+ * Returned via `Result.err` from `world.removeChild` (M3) when the `parent`
+ * argument does not match the child's current relationship parent (the child
+ * lacks the relationship component, or it points at a different parent). The
+ * `.detail` carries the expected (argument) parent + the actual current parent
+ * so AI users can reconcile their model.
+ *
+ * `.code = 'relationship-detach-mismatch'`
+ * `.detail = { component, child, expectedParent, actualParent }`
+ *   `actualParent === ENTITY_NULL_RAW` (0) signals the child has no relationship.
+ * `.hint` — names the child + the parent mismatch.
+ */
+export class RelationshipDetachMismatchError extends Error {
+  override readonly name = 'RelationshipDetachMismatchError';
+  readonly code = 'relationship-detach-mismatch' as const;
+  readonly hint: string;
+  readonly expected: string;
+  readonly detail: {
+    readonly component: string;
+    readonly child: number;
+    readonly expectedParent: number;
+    readonly actualParent: number;
+  };
+
+  constructor(component: string, child: number, expectedParent: number, actualParent: number) {
+    const hint = `removeChild(${expectedParent}, ${child}) via "${component}": child's current parent is ${actualParent}, not ${expectedParent}. Detach from the actual parent or re-read the current relationship.`;
+    const expected = `child's "${component}" parent === ${expectedParent}`;
+    super(
+      `relationship: detach parent mismatch.\n` +
+        `  code: relationship-detach-mismatch\n` +
+        `  component: ${component}\n` +
+        `  child: ${child}\n` +
+        `  expectedParent: ${expectedParent}\n` +
+        `  actualParent: ${actualParent}\n` +
+        `  expected: ${expected}\n` +
+        `  hint: ${hint}`,
+    );
+    this.hint = hint;
+    this.expected = expected;
+    this.detail = { component, child, expectedParent, actualParent };
+  }
+}
+
+/** Returned when callers attempt to mutate an engine-maintained target list. */
+export class RelationshipTargetReadonlyError extends Error {
+  override readonly name = 'RelationshipTargetReadonlyError';
+  readonly code = 'component-field-invalid-value' as const;
+  readonly expected = 'relationship source mutation';
+  readonly hint: string;
+  readonly detail: {
+    readonly component: string;
+    readonly operation: string;
+  };
+
+  constructor(component: string, operation: string) {
+    const hint = `Component "${component}" is an engine-maintained relationship target. Mutate its source component instead of ${operation}.`;
+    super(`[RelationshipTargetReadonlyError component-field-invalid-value] ${hint}`);
+    this.hint = hint;
+    this.detail = { component, operation };
+  }
+}