My Archetype Invariants Exploration & Reference Implementation

[SoyokazeRoom201]

• Update(4/7/2026): Article structure refinement and clarification

• Refer to Archetype Invariants #1481

• All my PRs are drafts for experimentation and exposing problems

• The previous title was "Proposal", which might cause confusion for the community. This is not a proposal for a specific API. This is a study of the problem space, with experimental implementations to validate the approach.

• I am continuing to explore whether there are any simple, opt-in solutions to avoid over-engineering...

---

1. Insight

Archetype is immutable after creation, which is directly consistent with tables in SQL. I referred to the theoretical concepts of databases and found that "JSON Schema" and "Web Ontology Language" directly address constraint issues in "open-world" data models.

---

2. Abstract Architecture

Core primitives

#[derive(Component)]
#[constraint(forbid(CompB))]
struct CompA;
 
#[derive(Component)]
#[constraint(forbid(CompA))]
struct CompB;

#[derive(Component)]
struct Position;

#[derive(Component)];
struct Velocity;

#[derive(Component)]
#[constraint(and(require(Position), require(Velocity)))]
struct HomingMissle;
 
#[derive(Component)]
#[constraint(require(HomingMissile))]
struct Projectile;

Controlled Side Effects

// Mutual exclusion with automatic replacement, current open pr
world.register_mutually_exclusive_components::<(CompA, CompB)>();
 
// Cascade removal
app.register_cascade_remove::<Projectile, HomingMissile>();

Each controlled API auto-registers the corresponding constraints. The system can statically verify that the side effects don't violate any constraints.

bevy-cli is a better alternative that can significantly reduce the compilation/registeration pressure and bevy_ecs codebase expansion

Validation & Final fallback

The validation point is in get_id_or_insert - the sole entry point for Archetype creation. There is no bypassing path. The Archetype cannot be changed after creation.

• If validation fails, the Archetype is never created.
• No hook, observer, or system can ever observe an illegal Archetype. Because the illgal archetype is not exist.

---

3. Constraint Primitives

Three primitives are sufficient to express any structural constraint:

Primitive	Semantics
require(T)	Component T must be present
not(expr)	Negation
and(exprs...)	All must hold

OPTIONAL:

Extension	Semantics	Note
or(exprs...)	At least one must hold	Optional. Without it everything is simpler. With it, more expressive but NP in theory. Query overlap detection could achieve false nagtive, otherwise the performance is unacceptable
only(A, B, C)	Universal quantifier - whitelist	Equivalent to forbidding all components not in the set. Cannot be expressed with finite forbids because new components can be registered at any time in registeration phase.

forbid can be naturally represented by primitives

• forbid(T) = not(require(T))

Coverage of Issue #1481 Requirements

Feature	Declaration	Primitives
Forbidden	A cannot coexist with B	A: forbid(B)
Always With	A requires B	A: require(B)
Only With (∀)	A can only coexist with B and C	A: only(B, C)
Inseparable	A and B must always appear together	A: require(B), B: require(A)
Disjoint	At most one of A, B, C	Each: forbid all others
Conditional	A needs B or C	A: or(require(B), require(C)) (requires Or)
Exclusive Pair	A needs exactly one of B or C	A: and(or(require(B), require(C)), not(and(require(B), require(C)))) (requires Or)
Required Group	Exactly one of {A,B,C} must exist	Each: forbid others + or(require(A), require(B), require(C)) (requires Or)

---

4. Implementation

Disjunctive Normal Form (DNF)

The current QueryFilter is exactly the same as this implementation.

Each constraint expression compiles to DNF - a disjunction (OR) of conjunctive clauses. Each clause is a pair of FixedBitSets:

struct DnfClause {
    required: FixedBitSet,  // Components that must be present
    forbidden: FixedBitSet, // Components that must NOT be present
}

Validation is short-circuit OR over clauses, each clause is two bitwise operations:

fn validate(dnf: &[DnfClause], archetype: &FixedBitSet) -> bool {
    dnf.iter().any(|clause| {
        archetype.contains_all(&clause.required)
            && !archetype.intersects(&clause.forbidden)
    })
}

Logic is as same as is_ruled_out in query/state.rs

Without the Or primitive(CNF), each component's constraint compiles to a single clause. Validation becomes one contains_all + one intersects per component - O(N/64) bitwise operations. No SAT solving involved.

Verification Point(No any other points that can be bypassed)

Validation occurs only on the Archetype creation path (get_id_or_insert), with complexity O(components being inserted). Existing Archetypes are never re-checked because they are immutable. It is guaranteed by data structure.

Benchmarks

spawn_no_constraint         46.8 µs   (baseline)
spawn_with_simple_constraint   45.4 µs   (no measurable overhead)
spawn_with_complex_constraint  50.0 µs   (~7% overhead, complex constraint)

Note: Further benchmarking with more diverse scenarios is needed.

---

5. Integration with Query Overlap Detection

The principle is straightforward:

1. #[constraint(forbid(B))] on component A compiles to: A's forbidden BitSet contains B.
2. Scheduler checks Query<With<A>> vs Query<With<B>>.
3. Looks up constraint graph: A and B are mutually exclusive.
4. These two Queries can never match the same Archetype.
5. Conflict eliminated, parallel execution allowed.

experiment (from experimental code):

1. constraint.rs: Functions for determining whether any two components are mutually exclusive.
2. info.rs: Method for updating the mutual exclusion matrix.
3. query/state.rs: In from_states_uninitialized, inject all mutually exclusive components of with_id within AccessFilter::with into AccessFilter::without.

---

6. Controlled Side Effects + Constraints - UX API

#[derive(Component)]
#[constraint(forbid(CompB))]
struct CompA;
 
#[derive(Component)]
#[constraint(forbid(CompA))]
struct CompB;

world.register_mutually_exclusive_components::<(CompA, CompB)>();

Static safety verification

Because side effects are restricted to three forms - Add(X), Remove(X), Mutual Exclusion - the system can statically verify at registration time that no combination of side effects can violate any constraint:

// At registration time:
world.register_mutually_exclusive_components::<(CompA, CompB)>();
 
//   insert(CompA) -> effects: remove(CompB)
//   Check: any component still present that requires CompB
//   If yes -> reject registration
//   If no -> safe to register

// insert(CompB) -> effects: remove(CompA) is exactly same mirror behaviour

bevy-cli is a better alternative that can significantly reduce the compilation/registeration pressure and bevy_ecs codebase expansion

Better not to put side effects on component declaration

Something like [constraint(forbid(A, replace))]. This is because they can be combined. For example:

#[drive(Component)]
#[constraint(forbid(A, replace))]
struct B;

#[derive(Component)]
#[constraint(forbid(B, replace))]
struct A;

command.spawn((A, B)) // which one survive? can we rely on bundle order?

Meanwhile, side effects are context-dependent. The same mutual exclusion might need different strategies in different apps:

// replaces is silently
world.register_mutually_exclusive_components::<(CompA, CompB)>();

Constraints are universal truths about the data model. Side effects are policy decisions.

This is almost a consensus among all data models, and it is also the experience gained from lessons in the SQL language.

---

7. Relationship with Existing Features

Current PR #22818 (Mutually Exclusive Components)

It solves the immediate need for mutual exclusion. My study is complementary - it provides the theoretical foundation and architectural direction for a unified constraint system.

register_mutually_exclusive_components::<(A, B)>() is equivalent to:

• A: forbid(B), B: forbid(A) // Only constraints
• world.register_mutually_exclusive_components::<(CompA, CompB)>() // Only side effects

The current PR's problem is mixed invariant maintaince and auto-replace policy, therefore soundness bug exists

Current #[require(T)]

The existing #[require(T)] is a side effect. It does not enforce invariants(Is there any possible direct solution to the problem without proposed primitives?). Combining with #[constraint(require(T))] creates a complete guarantee:

#[derive(Component)]
#[require(Position)]                       // auto-insert
#[constraint(require(Position))]    // invariant - can never exist without Position
struct Health;

• #[require] makes it convenient (auto-inserts Position).
• #[constraint] makes it safe (blocks any Archetype where Health exists without Position).

---

8. Tradeoffs

Fallible API

To refuse illegal Archetype creation, get_id_or_insert must return Result(Is there any simple solution?), which propagates through downstream code. This is the largest engineering cost.

Proposed behavior for existing APIs:

• spawn(): If validation fails, entity lives in the empty Archetype (no components). User can try_insert or despawn.
• insert(): If validation fails silently, entity remains in existing Archetype.
• remove(): If validation fails silently, entity retains original components.
• despawn(): Always succeeds.

This might not be the best solution, but it is the only way to avoid disrupting the existing API.

Runtime Registration of Constraints(Addressed by review)

My constraint validation layer does not support dynamic registration of new constraints on existing Components at runtime. Otherwise, this is a problem that cannot be easily solved. This requires more in-depth engineering diagnosis and decision-making, such as completely deleting all the illgal Archetypes. However, it cannot guarantee that UB will definitely not occur. Query Overlap Detection also requires that all modifications be able to be made at runtime.

In such context, runtime is indicating the system is in Update phase, after all Registeration phase

---

9. Edge Cases

Insert order

#[constraint(forbid(Alive))]
struct Dead;

#[constraint(forbid(Dead))]
struct Alive;

entity.insert(Dead).remove(Alive);  // May fail: intermediate {Alive, Dead} is illegal
entity.remove(Alive).insert(Dead);  // Works: {Dead} is legal

This is a real problem. Batch commands #5074 need to be solved. If combined with PR #22818 's auto replamcenet. Batch command resolving can be delayed. But it still cannot solve the fundamental issue.

Contradictory constraints

#[constraint(and(require(B), forbid(B)))]  // Always false
struct A;

The component can never exist in any Archetype. This is detected at DNF compilation (required ∩ forbidden ≠ ∅). Cross-component contradictions are detected via implication graph analysis.

bevy-cli is a better alternative that can significantly reduce the compilation/registeration pressure and bevy_ecs codebase expansion

This does not break invariants - it makes the component unusable.

---

10. Roadmap

Phase	Deliverable	Description
1	Core constraints	Primitives (without Or) + DNF/BitSet validation + debug_assert on Archetype creation
2	Fallible API	Convert debug_assert to Result<T, E> with proper error propagation
3	Query overlap detection	Use exclusions list to achieve query overlap detection & ambiguity checking
4	Batch commands	Transactional insert/remove to avoid intermediate-state issues I suggest we need it
5	Error handling	On<ComponentConstraintViolation>
6	Cascade Remove	register_cascade_remove
7	APIs that community needed	Additional APIs and sugar based on community needs

---

11. References

What	Link
Constraint primitives + DNF + validation	Draft PR #23658
Query overlap detection experiment	SoyokazeRoom201@bd56db0

---

If anyone has thoughts, questions, or concerns, welcome to the discussion. Thank you!

[SkiFire13]

My 2c:

app.register_cascade_remove::<Projectile, HomingMissile>(); // auto register constraints, auto insert...

world.register_mutually_exclusive_components::<(Alive, Dead)>(); // auto register constraints with auto replacement

As any dynamic APIs, we would have to consider what happens when an existing archetype suddently becomes invalid after adding one such new rule.

b) when do we enforce this (e.g. can we rely on this for soundness)
c) integration with query overlap detection
d) integration with scheduling and ambiguity checking

b) If only analysis is conducted without any restrictions(refuses), then options c) and d) cannot be achieved.

I would suggest you to try to make c) achievable, since historically that has been the main motivator for archetype invariants.

The guarantee of soundness is in the return of Result Err, which prevents any downstream code from continuing to write Components to the Table.

The return type is unfortunately not enough to ensure soundness (we are not in a language with dependent types). For example:

• a possible implementation could temporarily allow breaking invariants due to side-effects and then restoring them at the end (as you mention later on); by itself this should be fine, but an easy oversight would be exposing the invalid archetype through the use of component hooks/observers, or not being panic-safe and allowing the observation of the archetype when catching such panic. For this reason you have to carefully review the implementation too.

• if requirements can be introduced at runtime then they might make existing archetypes invalid, and it would be unsound for those to not be removed or fixed. Note that this happens outside the function that creates new archetypes! This means you cannot just reason about that function in isolation, you need to consider everything that could affect archetypes or archetype invariants in order to be sound.

Also, the idea of returning Result/Err seems inconsistent with the idea of automatically fixing the resulting archetype by skipping the insertion or overwriting the existing component. Which one are you pursuing?

In short, Components stores a mutex list and injects it directly during registeration phase. In terms of mutex list implementation, this is a roughly SAT solver, but it has a polynomial complexity.

I don't think you can achieve this in polynomial complexity without having false positives. You are effectively solving a SAT problem where you're pretty much trying to identify if P && Q && Inv is satisfyable. That's a SAT problem! In fact right now the formula is P && Q (since there are no archetype invariants) and solving it is already exponential (though to be fair it's exponential in the number of AnyOf and Or clauses, which are relatively rare).

Roadmap

I don't see a mention of support for query overlap detection in the roadmap.

---

Regarding the UX of the feature, I like the idea of a simple and consistent model for the requirements (require, only, not, and, or, which are 5 btw). However later on this idea is kinda broken with forbid, must_have, overwrite, etc etc. I think we'll need a simple model there too, or users will be very confused by this feature (especially if we go the route of silently overwriting components or dropping inserts, which is somehow forces due to Command being delayed).

[SoyokazeRoom201]

Hi,

Theory Complete is one thing, engineering implementation is another, and UX is an even more important matter eventually. When the three balance each other, the proposal becomes fragmented and disorganized. However, we cannot ignore the problems I think. I have tried my best to expose them all.

And with each step of the experiment, more problems will be revealed, and continuous updates will be necessary...

• As my proposal mentioned, the "Or" primitive can be non-existent. It is the main reason for the increase in complexity and requires consensus. (If the community consensus deems it unnecessary, that would be truly great)

As any dynamic APIs, we would have to consider what happens when an existing archetype suddently becomes invalid after adding one such new rule.

• My proposition is that the primitives provides the underlying expression capability, and by using a controlled API, it exposes the validation + side effects combination to the users to provide ergonomics. I think this is a good architectural layering. The use of the primitives can make invariant maintenance simpler. Better not think from the User-Level API shape!

• If the underlying structure conforms to the framework of set theory, the combination of constraints and side effects can be analyzed using mathematical tools! It enables us to safely expose any feasible dynamic APIs. The four contracts have a final fallback.

I would suggest you to try to make c) achievable, since historically that has been the main motivator for archetype invariants.

• c) is achievable. My experiment can be found in (SoyokazeRoom201@bd56db0) Well, I can publish it using the draft pr. However, this will generate more noise and mental burden. More diagnosis and tests are needed. If community doesn't care, I will create a new Draft PR.

To be specific:

1. crates\bevy_ecs\src\component\constraint.rs: provides an functions for determining whether any two components are mutually exclusive.
2. crates\bevy_ecs\src\component\info.rs: Provided a method for updating the mutual exclusion matrix.
3. crates\bevy_ecs\src\query\state.rs: In from_states_uninitialized, inject all the mutual exclusion matrices of with_id within AccessFilter::with into AccessFilter::without.

The return type is unfortunately not enough to ensure soundness

• I think this can be summarized as contracts:

1. There are no constrained components that will be dynamically registered during runtime.

   In my implemntation:

   Constraints can only be declared through the "derive" macro, and cannot be added at runtime. If runtime registration is to be supported in the future, the existing Archetype will need to be re-verified at that time. However, this will incur significant costs. Therefore, better do not implement this feature.

2. Archetype is immutable once created.

3. An illegal Archetype creation was blocked by Err and it does not exist.

4. There is no automatic repair mechanism AFTER violations in the framework, because the invalidated Archetype simply does not exist; there is only one automatic repair mechanism is to create a new legal Archetype. Eventually, the creation will still fail.

   In my implementation:

   1. The verification point is located within the get_id_or_insert function, before the Archetype is created.
   2. If the verification fails, the Archetype will not be created.
   3. An non-existent Archetype will not be observed by the hook/observer.
   4. There is no intermediate state window.

Which one are you pursuing?

• The proposal has become contradictory with the updates. My bad. My proposition refienment of this proposal is:

For the existing API:

1. spawn(): The attempt at silence failed. The user obtained the ghost Entity. (Living in an empty Archetype, you can try to insert new components or despawn at any time)
2. insert(): Insertion of entity failed silently. The entity remains in the existing archetype.
3. remove(): If the operation fails silently, the user's Entity will retain its original components.
4. despawn(): Always succeed.

New API:

2. General Error Handling Observer |On<ComponentValidationError>| {}.

I don't think you can achieve this in polynomial complexity without having false positives.

If a false positive means "judging as mutually exclusive but it is not actually mutually exclusive", and a false negative means "it is truly mutually exclusive but it was not detected", then my implementation has false negatives but no false positives.

But a comprehensive analysis would introduce even more unpredictable runtime costs. For simple and common mutual exclusion analyses, I think this is sufficient. You can review my code if you are insterested crates\bevy_ecs\src\component\constraint.rs: (SoyokazeRoom201@bd56db0)

If there is no or primitive, it is polynomial time

3. Hide the underlying primitive representation and expose controlled APIs to the users. For any contradictions, I will update them in the Discussion.

I don't see a mention of support for query overlap detection in the roadmap.

• This requires community consensus. I believe the community will summarize a detailed and progressive roadmap. Of course, I will continue to update accordingly.

Review -> Answer -> Experiment -> Discover new problems. Ultimately, we will see the dawn. Thank you!

[SkiFire13]

My proposition is that the primitives provides the underlying expression capability, and by using a controlled API, it exposes the validation + side effects combination to the users to provide ergonomics. I think this is a good architectural layering. The use of the primitives can make invariant maintenance simpler. Better not think from the User-Level API shape!

If the underlying structure conforms to the framework of set theory, the combination of constraints and side effects can be analyzed using mathematical tools! It enables us to safely expose any feasible dynamic APIs. The four contracts have a final fallback.

Invariant maintenance does not depend on your primitives though, it depends on any piece of code that can modify the data that the invariant refers to. As such you have to be extra careful about the whole system around that data.

You seem to contradict yourself when you say that your implementation does not support runtime registration of invariants, since the PR you posted does seem to support them, and even has a soundness bug due to them.

Finally, I would argue that user-level APIs do matter, because the goal is to provide a usable system to end users. You always need to consider them, especially when the theoretical framework gives room for different APIs.

This requires community consensus. I believe the community will summarize a detailed and progressive roadmap. Of course, I will continue to update accordingly.

It is listed as the main usecase in the archetype invariants issue though. What usecase (and hence reason to introduce this feature) remains without that? Remember that archetype invariants where really proposed as a solution for that problem, not as a standalone feature.

[SoyokazeRoom201]

Invariant maintenance does not depend on your primitives though, it depends on any piece of code that can modify the data that the invariant refers to. As such you have to be extra careful about the whole system around that data.

1. In the code, my validation point is located in the get_id_or_insert function. This is the sole entry point for Archetype's creation process, and there is no bypassing path. The archetype cannot be changed after creation, so the invariants are maintained. This is reflected in my code.

You seem to contradict yourself when you say that your implementation does not support runtime registration of invariants, since the PR you posted does seem to support them, and even has #22818 (comment) due to them.

2. That PR is not my own implementation; it is the code from another solution that I have referenced. It is used to illustrate that "automatic repair" and "constraint validation" are SHOULD BE two orthogonal layers. My constraint validation layer does not support dynamic registration at runtime. I didn't mention it. My bad.

The "dynamic" here refers to the process of registering new constraints on an existing Component during runtime. I will address it in discussion article.

Finally, I would argue that user-level APIs do matter, because the goal is to provide a usable system to end users. You always need to consider them, especially when the theoretical framework gives room for different APIs.

3. This is the point where I was negligent. My position is:

   • Components declare WHAT is legal
   • App/World declares HOW to to apply constraints(any replacement, insertion, deletion): app.register_mutually_exclusive_components::<CompA, CompB>()
   • Engine guarantees soundness.

The theoretical framework tells us which combinations of constraints + side-effects are safe. The controlled API exposes only those safe combinations to users. "Don't think that the API shape" may caused misunderstanding for you. This is mainly because I failed to organize my viewpoints into a proper structure, I will refine it.

It is listed as the main usecase in the #1481 though. What usecase (and hence reason to introduce this feature) remains without that? Remember that archetype invariants where really proposed as a solution for that problem, not as a standalone feature.

4. I mentioned it earlier with code references, and I refined the roadmap:

• Core infrastructure with the basic API(already implemented, need further disccusion and and truncat, like remove Or primitives) with only debug assert.
• Converting cfg[debug] to Result<T, E>.
• Integration with query overlap detection & ambiguity checking(Experiment can be found in SoyokazeRoom201@bd56db0)

Maybe my think of the consensus on the community roadmap is how to gradually implement the code in a way that avoids regression and keeps the scope under control.

If there are still any contradictions, inconsistencies or need clarification, I will continue to refine and explore to provide a solution direction. Thank you!

[SkiFire13]

That PR is not my own implementation; it is the code from another solution that I have referenced.

Oh my bad. Then yeah that explaind a lot of why I was confused!