STRICT TDD-DDD IMPLEMENTATION RULES

---
description: TDD-DDD Cursor Rules for Bevy v0.16 ECS/NATS/NixOS
globs: ["**/src/**/*.rs", "flake.nix", ".envrc", "**/tests/**/*.rs"]
alwaysApply: true
---

# STRICT TDD-DDD IMPLEMENTATION RULES

## Mandatory Testing Practices
1. **Test-First Development** - Never write production code without failing test first
2. **Domain Isolation** - All domain logic tests MUST NOT contain Bevy/NATS dependencies
3. **Headless Execution** - All tests must run in BEVY_HEADLESS=1 mode with Wayland disabled
4. **Test Coverage** - 95%+

We operate on Events and Event Handlers.
ALL Events should be ABLE to be handled, in other words a handler exists, but may not always get called. It should still have tests.

We issue Commands and Command Handlers.
ALL Commands should be ABLE to be handled, in other words a handler exists, but may not always get called. It should still have tests.

ALL TESTS REQUIRE A MERMAID GRAPH IN THE RUSTDOCS DETAILING WHAT IS BEING TESTED AND HOW

You DO NOT need to test actual rendering, but you DO need to test everything the rendering expects to be there IS.

## Bevy ECS Testing Directives
```
// REQUIRED test setup pattern
fn test_ecs_system() {
    let mut app = App::new();
    app.add_systems(Update, system_under_test)
       .insert_resource(TestNatsClient::new());

    app.update();
    let results = app.world.query::().iter(&app.world);
    assert_eq!(results.len(), 1);
}
```

## NATS Messaging Validation
```
// ECS-NATS bridge testing pattern
fn validate_nats_message_handling(
    mut commands: Commands,
    mut events: EventReader,
    mut outgoing: EventWriter
) {
    for msg in events.read() {
        let response = DomainService::process(&msg.payload);
        outgoing.send(NatsOutgoing::new(response));
        commands.spawn(TestMarker::processed());
    }
}
```

## NixOS Environment Configuration
```
# REQUIRED flake.nix structure
{
  inputs.bevy.url = "github:bevyengine/bevy/v0.16";

  outputs = { self, nixpkgs, bevy }:
    let pkgs = nixpkgs.legacyPackages.x86_64-linux;
    in {
      devShells.default = pkgs.mkShell {
        BEVY_HEADLESS = "1";
        buildInputs = with pkgs; [
          rustc cargo pkg-config
          vulkan-headers wayland
          nats-server natscli
        ];
      };
    };
}
```

## Prohibited Patterns
❌ Never use `#[cfg(test)]` without `#[test]`
❌ No direct Wayland dependencies - use NixOS graphics stack[3][16]
❌ Ban `unwrap()` in domain logic tests - must handle Option/Result[2][10]

## TDD Workflow Commands
```
# Start TDD session
direnv allow && nix develop
BEVY_HEADLESS=1 cargo watch -x test

# NATS integration tests
nats-server -js & cargo test --test nats_bridge

# Domain layer tests
cargo test --lib -- domain
```

## Verification Matrix
| Test Type     | Execution Time | Must Pass |
| ------------- | -------------- | --------- |
| Unit (Domain) | ,              |
    payload: JsonValue
}
```

## Performance Guardrails
1. Single test duration <100ms
2. Test memory usage <50MB
3. No async in domain layer tests[1][4]

## Code Generation Rules
1. New types MUST have `#[derive(Component)]` if used in ECS
2. All NATS messages MUST use `#[derive(Serialize, Deserialize)]`
3. Test modules MUST mirror src structure[2][10]

## Emergency Protocols
// Critical test failure pattern
fn handle_test_failure() {
    panic!("TEST FAILURE: Rollback transaction and inspect DB snapshot");
}
```