Merge pull request #99 from csprance/relationship-v2

## GECS v7.1.0 — Structural Relationship Queries

**Relationship queries are now as fast as component queries.** No API changes required — your existing `with_relationship()` calls just got dramatically faster.

### What Changed

`with_relationship()` previously worked as a post-filter: after selecting entities by component, it iterated every matched entity and linearly scanned their relationships array. This was O(N×M×K) where N = entities, M = relationships per entity, K = filters.

In v7.1.0, each `(Relation, Target)` pair is baked into the archetype signature. Relationship queries now resolve through the same O(1) archetype bucket lookup that component queries use — no per-entity scanning.

### Performance (Godot 4.6, from benchmarks)

**Exact relationship queries — constant time regardless of entity count:**

| Scale | Relationship Query | Component Query (baseline) |
|------:|-------------------:|---------------------------:|
| 100 | 0.089 ms | 0.060 ms |
| 1,000 | 0.092 ms | 0.061 ms |
| 10,000 | 0.091 ms | 0.137 ms |

Exact `with_relationship([Relationship.new(C_Type.new(), target)])` queries are **flat at ~0.09ms** whether you have 100 or 10,000 entities. That's within noise of a `with_all()` component query.

**Wildcard relationship queries** (`Relationship.new(C_Type.new(), null)`) scale with the number of distinct archetypes matched, not total entities:

| Scale | Wildcard Query |
|------:|---------------:|
| 100 | 0.214 ms |
| 1,000 | 1.941 ms |
| 10,000 | 21.274 ms |

*(This benchmark is worst-case: every entity has a unique target, creating one archetype per entity. Real-world usage with shared targets will be much faster.)*

### What You Need to Do

**Nothing.** The `with_relationship()` API is unchanged. Your existing code benefits automatically.

```gdscript
# This is the same API — it's just fast now
var children = world.query.with_relationship([
    Relationship.new(C_ChildOf.new(), parent_entity)
]).execute()
```

Property-based relationship queries continue to work as post-filters (runtime values can't be archetype-keyed):

```gdscript
# Still works — property queries remain post-filter
var high_damage = world.query.with_relationship([
    Relationship.new({C_Damage: {"amount": {"_gte": 50}}}, target)
]).execute()
```

### Other Changes

- **Legacy `relationship_entity_index` removed** — the old Dictionary-based index is gone, replaced entirely by the archetype system. Slightly lower memory footprint.
- **Archetype explosion warning** — if you exceed 500 archetypes (possible with many unique relationship targets), a one-time debug warning fires so you can catch unintended combinatorial blowup early.
- **Batch relationship transitions** — `add_relationships([r1, r2, r3])` produces exactly one archetype transition instead of N, keeping bulk operations fast.
- **Freed-target cleanup** — when a target entity is removed from the world, all source relationships pointing to it are automatically cleaned up via the archetype index.

### Test Coverage

313 tests passing, zero regressions. 34 new tests added covering structural relationship storage, signature computation, archetype transitions, query integration, and property query preservation.

Author: csprance

.gitignore

@@ -3,6 +3,9 @@
 /android/
 repomix-output.txt
 
+# Windows reserved device names (prevent accidental creation)
+nul
+
 reports/
 .claude/settings.local.json
 

.planning/PROJECT.md

@@ -0,0 +1,78 @@
+# GECS Structural Relationships (v7.1.0)
+
+## What This Is
+
+GECS is a lightweight, performant Entity Component System (ECS) framework for Godot 4.x. This milestone adds FLECS-style structural relationship queries: each `(Relation, Target)` pair becomes part of the archetype signature so `with_relationship()` queries resolve via O(1) archetype bucket lookup instead of per-entity linear scanning.
+
+## Core Value
+
+Relationship queries must be as fast as component queries — both select pre-grouped archetype buckets, no per-entity iteration.
+
+## Requirements
+
+### Validated
+
+- ✓ Archetype-based entity storage with FNV-1a signature hashing — existing
+- ✓ QueryBuilder with `with_all`, `with_any`, `with_none`, `with_group` — existing
+- ✓ Relationship system: typed `(relation, target)` pairs stored on entities — existing
+- ✓ `with_relationship()` query filter (currently post-filter, slow) — existing
+- ✓ Wildcard null-target relationship matching — existing
+- ✓ Property-based relationship queries via `ComponentQueryMatcher` — existing
+- ✓ CommandBuffer for safe structural mutations during iteration — existing
+- ✓ Observer/reactive system for component lifecycle events — existing
+- ✓ Archetype add/remove edge graph for O(1) archetype transitions — existing
+- ✓ Query archetype cache (FNV-1a keyed, invalidated on structural changes) — existing
+- ✓ Network sync addon (`gecs_network`) — existing
+- ✓ Serialization via `GECSIO` — existing
+- ✓ Each unique `(Relation, Target)` pair included in archetype signature
+- ✓ `entity.add_relationship()` moves entity to new archetype (structural transition)
+- ✓ `entity.remove_relationship()` moves entity back (structural transition)
+- ✓ `with_relationship()` exact-pair queries resolve via archetype cache lookup
+- ✓ Wildcard relation queries use a relation-type index bucket
+- ✓ Archetype query cache key includes structural relationship pairs
+- ✓ Cache invalidation triggers on relationship add/remove
+- ✓ New tests cover the structural archetype query path for relationships
+
+### Active
+
+- [ ] Property-based relationship queries remain as post-filter applied after archetype selection
+- [ ] All existing relationship tests pass unchanged as a formally tracked phase-5 deliverable
+- [ ] Perf benchmarks demonstrate O(1) relationship query parity with component queries
+- [ ] Ships as v7.1.0 — no public API breaks on World, Entity, QueryBuilder
+
+### Out of Scope
+
+- Changing the `with_relationship()` call site API — internal implementation only
+- Making property-based relationship queries structural — runtime values can't be archetype-keyed
+- Breaking any public API surface on World, Entity, QueryBuilder, System, Observer
+- Network sync changes — not affected by this milestone
+
+## Context
+
+Current bottleneck: `QueryBuilder` applies `with_relationship()` as a post-filter — it iterates every entity in the structural result set and calls `entity.has_relationship()`, which linearly scans `entity.relationships: Array[Relationship]`. This is O(N×M×K) where N = matched entities, M = relationships per entity, K = relationship filters.
+
+FLECS solves this by treating `(ChildOf, parent_entity)` as a first-class component slot in the archetype signature. The archetype hash includes relationship pairs so the query just selects matching archetype buckets — same O(1) path as component queries.
+
+The existing `relationship_entity_index: Dictionary` in World (`relation.resource_path → Array[Entity]`) is built but not used for queries. It will be replaced or extended to support the new structural approach.
+
+Entity relationships support three target types: Entity instance (identity), Component instance (type-matched), or null (wildcard). The archetype key must handle all three.
+
+## Constraints
+
+- **Compatibility**: No breaking changes to the public API (World, Entity, QueryBuilder, System, Observer, Relationship constructors) — v7.1.0 semver
+- **Godot 4.x**: GDScript only, no C++ extensions
+- **Test coverage**: All changes must have corresponding gdUnit4 tests in `addons/gecs/tests/`
+- **Perf validation**: Perf benchmarks in `addons/gecs/tests/performance/` must show structural relationship queries matching component query performance
+
+## Key Decisions
+
+| Decision                                             | Rationale                                                                                                                                   | Outcome                                          |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Each (Relation, Target) pair = unique archetype slot | Full FLECS fidelity; enables per-target structural queries; entity with (Damage,e1) AND (Damage,e2) lives in archetype including both pairs | Validated in phases 1-4                          |
+| Property queries stay as post-filter                 | Runtime property values can't be hashed into archetype keys                                                                                 | Validated; remains a phase 5 compatibility focus |
+| Keep `with_relationship()` API unchanged             | No user code churn; just make it fast internally                                                                                            | Validated                                        |
+| Wildcard (null target) uses relation-type index      | Separate bucket from exact-pair bucket; covers the common "has any X relationship" pattern fast                                             | Validated                                        |
+
+---
+
+_Last updated: 2026-03-22 after Phase 04 verification_

.planning/REQUIREMENTS.md

@@ -0,0 +1,127 @@
+# Requirements: GECS v7.1.0 — Structural Relationships
+
+**Defined:** 2026-03-18
+**Core Value:** Relationship queries must be as fast as component queries — both select pre-grouped archetype buckets, no per-entity iteration.
+
+## v1 Requirements
+
+Requirements for v7.1.0 release. Each maps to roadmap phases.
+
+### Archetype Pairs
+
+- [ ] **ARCH-01**: Each unique `(Relation, Target)` pair is encoded as a slot key and stored in the archetype's `component_types` array alongside component resource paths
+- [ ] **ARCH-02**: Relationship slot keys use `rel://<relation_resource_path>::<target_key>` string format in `component_types` (uniform with existing component path infrastructure)
+- [ ] **ARCH-03**: Archetype does NOT create SoA columns for `rel://` prefixed slot keys (relationship data remains on `entity.relationships`)
+- [ ] **ARCH-04**: Archetype exposes a `relationship_types` array for efficient pair subset iteration
+- [ ] **ARCH-05**: Archetype `matches_relationship_query()` method performs structural pair matching
+
+### Signature & Index
+
+- [ ] **SIGX-01**: `World._calculate_entity_signature()` includes relationship slot keys in the entity's archetype signature hash
+- [ ] **SIGX-02**: `QueryCacheKey.build()` encodes relationship pairs as `(relation_id, target_id)` integer pairs (not flattened — preserves pair structure to prevent hash collisions)
+- [ ] **SIGX-03**: World maintains a `_relation_type_archetype_index: Dictionary` mapping `relation.resource_path → Array[Archetype]` for O(1) wildcard queries
+- [ ] **SIGX-04**: `_relation_type_archetype_index` is updated when archetypes are created and destroyed
+
+### Structural Transitions
+
+- [ ] **TRAN-01**: `entity.add_relationship()` triggers an archetype transition (entity moves to new archetype including the pair slot key)
+- [ ] **TRAN-02**: `entity.remove_relationship()` triggers an archetype transition (entity moves to archetype without the pair slot key)
+- [ ] **TRAN-03**: `entity.add_relationships()` batches to a single archetype transition (not N sequential transitions) to prevent cache thrash
+- [ ] **TRAN-04**: Cache invalidation fires on relationship add/remove (currently deliberately disabled — must be re-enabled for structural correctness)
+- [ ] **TRAN-05**: When a target entity is removed from the World, all source entities holding `(Relation, freed_target)` relationships are cleaned up (REMOVE policy — relationship is deleted when target is deleted, same as FLECS default)
+
+### Query Integration
+
+- [ ] **QURY-01**: `QueryBuilder.get_cache_key()` passes relationship pairs to `QueryCacheKey.build()` (currently always passes empty arrays — must be fixed)
+- [ ] **QURY-02**: `with_relationship()` with exact `(Relation, Target)` resolves via archetype cache lookup, not per-entity scan
+- [ ] **QURY-03**: `with_relationship()` with null target (wildcard) resolves via `_relation_type_archetype_index`, not per-entity scan
+- [ ] **QURY-04**: `without_relationship()` resolves structurally via archetype exclusion
+- [ ] **QURY-05**: `System._query_has_non_structural_filters()` does NOT flag exact type-match relationships as non-structural (only property-query relationships are non-structural)
+- [ ] **QURY-06**: Archetype subsumption: entity-instance target `e_pizza` matches a query using script-archetype target `GecsFood` (via wildcard + post-filter strategy)
+
+### Property Query Preservation
+
+- [ ] **PROP-01**: Property-based relationship queries (`Relationship.new({C_Damage: {'amount': {'_gte': 50}}}, target)`) remain as post-filters applied after archetype narrowing
+- [ ] **PROP-02**: `_query_has_non_structural_filters()` still returns true for property-query relationships
+- [ ] **PROP-03**: All 20+ existing relationship tests in `test_relationships.gd` pass unchanged
+
+### Perf Validation & Cleanup
+
+- [ ] **PERF-01**: Performance benchmarks demonstrate relationship query time parity with equivalent component queries at scales of 100, 1000, 10000 entities
+- [ ] **PERF-02**: `relationship_entity_index` (legacy partial index in World) is removed or deprecated in favor of `_relation_type_archetype_index`
+- [ ] **PERF-03**: Archetype count monitoring added to debug mode output (detect archetype explosion in development)
+
+## v2 Requirements
+
+Deferred to v7.2.0 or later.
+
+### Relationship Traits
+
+- **TRAIT-01**: Exclusive relationship trait — entity can only hold one target per relation type (enforced on `add_relationship()`)
+- **TRAIT-02**: Symmetric relationship trait — adding `(R, B)` to A auto-adds `(R, A)` to B
+
+### Observer Integration
+
+- **OBS-01**: Observer `on_relationship_added` callback fires when a relationship pair is structurally added
+- **OBS-02**: Observer `on_relationship_removed` callback fires when a relationship pair is structurally removed
+
+### Advanced Queries
+
+- **ADVQ-01**: `with_any_relationship()` filter — OR semantics across multiple relationship patterns
+- **ADVQ-02**: Dual-index registration for archetype subsumption (Option A) as a performance follow-up if wildcard+post-filter proves too slow
+
+## Out of Scope
+
+| Feature                                                                  | Reason                                                                          |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Property-based relationship queries becoming structural                  | Runtime values can't be archetype-keyed by definition                           |
+| Transitive relationship queries / graph traversal at query time          | Defeats O(1) archetype lookup; anti-feature for GDScript performance            |
+| Traversal / `up()` queries (FLECS pattern)                               | Same anti-feature rationale                                                     |
+| OnDelete cascade policy (delete parent cascades to children)             | v2+ complexity; v7.1.0 ships REMOVE policy only                                 |
+| Pair data access from archetype SoA columns                              | Relationship data stays on entity.relationships; archetype tracks identity only |
+| Breaking any public API on World, Entity, QueryBuilder, System, Observer | v7.1.0 semver — no public API breaks                                            |
+| Network sync changes                                                     | Not affected by this milestone                                                  |
+
+## Traceability
+
+Updated during roadmap creation.
+
+| Requirement | Phase   | Status    |
+| ----------- | ------- | --------- |
+| ARCH-01     | Phase 1 | Completed |
+| ARCH-02     | Phase 1 | Completed |
+| ARCH-03     | Phase 1 | Completed |
+| ARCH-04     | Phase 1 | Completed |
+| ARCH-05     | Phase 1 | Completed |
+| SIGX-01     | Phase 2 | Completed |
+| SIGX-02     | Phase 2 | Completed |
+| SIGX-03     | Phase 2 | Completed |
+| SIGX-04     | Phase 2 | Completed |
+| TRAN-01     | Phase 3 | Completed |
+| TRAN-02     | Phase 3 | Completed |
+| TRAN-03     | Phase 3 | Completed |
+| TRAN-04     | Phase 3 | Completed |
+| TRAN-05     | Phase 3 | Completed |
+| QURY-01     | Phase 4 | Completed |
+| QURY-02     | Phase 4 | Completed |
+| QURY-03     | Phase 4 | Completed |
+| QURY-04     | Phase 4 | Completed |
+| QURY-05     | Phase 4 | Completed |
+| QURY-06     | Phase 4 | Completed |
+| PROP-01     | Phase 5 | Pending   |
+| PROP-02     | Phase 5 | Pending   |
+| PROP-03     | Phase 5 | Pending   |
+| PERF-01     | Phase 6 | Pending   |
+| PERF-02     | Phase 6 | Pending   |
+| PERF-03     | Phase 6 | Pending   |
+
+**Coverage:**
+
+- v1 requirements: 26 total
+- Mapped to phases: 26
+- Unmapped: 0 ✓
+
+---
+
+_Requirements defined: 2026-03-18_
+_Last updated: 2026-03-22 after Phase 04 verification_