fix: stale archetype edge cache causing entity query dropout

[Donach]

Entities were intermittently "dropping out" of system queries after being processed for only a few frames. Root cause: the archetype edge cache was returning stale archetype instances that were no longer in the world's canonical archetypes dictionary.

Changes:

• archetype.gd: Add version counter for mutation tracking
• system.gd: Check version before/after snapshot to detect mutations
• world.gd: Validate edge cache returns canonical archetype instance

Summary by CodeRabbit

• New Features

  • Added direct query builder property for external queries

• Bug Fixes

  • Enhanced data consistency during entity mutations with improved synchronization
  • Strengthened archetype cache reliability and correctness
  • Added safeguards to prevent data misalignment during concurrent operations

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR introduces mutation tracking and defensive snapshot mechanisms to prevent race conditions in the Entity Component System. It adds a version counter to Archetype, applies snapshots in System iteration loops, and hardens archetype cache correctness in World's entity movement logic.

Changes

Cohort / File(s)	Summary
Archetype Versioning addons/gecs/ecs/archetype.gd	Added public version: int counter incremented on entity addition/removal to track structural mutations.
System Race-Condition Safeguards addons/gecs/ecs/system.gd	Introduced snapshot-based protections: component columns are duplicated before iteration, and archetype version is checked before/after processing to detect mid-frame mutations; debug warnings emitted if version changes occur.
World Query Property & Cache Canonicalization addons/gecs/ecs/world.gd	Added public query property getter that returns a fresh QueryBuilder with wired signals. Enhanced archetype movement paths to canonicalize archetypes from edge cache against world's canonical instances and reconcile stale references.

Sequence Diagram(s)

sequenceDiagram
    participant System as System (Processing)
    participant Archetype as Archetype
    participant World as World (Cache)
    
    System->>Archetype: snapshot_version = archetype.version
    System->>System: duplicate component columns
    System->>System: iterate with snapshots
    
    alt Entity mutation occurs mid-frame
        Note over Archetype: version incremented
        System->>Archetype: check version after process
        System-->>System: version changed? emit warning, skip
    else No mutation
        System->>Archetype: version unchanged
        System->>System: continue processing normally
    end
    
    alt Archetype cache stale
        World->>World: new_archetype from edge cache
        World->>World: find canonical archetype
        World->>World: reconcile & update edges
        World->>Archetype: point to canonical
    else Cache valid
        World->>Archetype: direct canonical access
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~40 minutes

Possibly related PRs

• Remove unused QueryBuilder pooling #71: Modifies World.query to return a fresh QueryBuilder with preserved cache\_invalidated signal wiring, directly overlapping with this PR's query property implementation.
• GECS v6.0.0 Release - Archetypes #66: Introduces archetype versioning and snapshot-based mutation safeguards that form the foundation for this PR's race-condition protection strategy.

Suggested labels

codex

Poem

🐰 A version blooms on every arch,
Snapshots guard each system's march,
When mutations shake the cache,
Canonicals guide safe passage fast!
Ears up for race-condition smash!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: addressing stale archetype edge cache causing entity query dropout, which matches the core objective of validating canonical archetype instances.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[csprance]

This should be resolved in v7.0.0. Thanks for this I took your idea and went a slightly different direction with it, but I appreciate you pointing out this issue it was not noticed!

Great work!