@accelerationguy/accel 1.0.0

package/modules/radar/src/domains/02-data.md

@@ -0,0 +1,224 @@
+---
+id: domain-02
+number: "02"
+name: Data & State Integrity
+owner_agents: [data-engineer]
+---
+
+## Overview
+
+Covers data models, schema evolution, migrations, referential integrity, consistency guarantees, and state transition safety. Most catastrophic failures are data bugs, not code bugs — corrupt state, irreversible migrations, silent data loss, and inconsistent derived data can cause damage that outlasts any code fix.
+
+Scope: schema design and evolution, migration strategy, referential integrity enforcement, state machine correctness, data validation at system boundaries, backup and recovery strategies, and data lifecycle management. Does NOT cover data security or privacy (domains 04, 05), performance of data access patterns (domain 08), or business logic correctness that happens to involve data (domain 03).
+
+## Audit Questions
+
+- Are data models explicitly defined (ORM models, schema files, type definitions), or is the schema implicit in code?
+- Is there a versioned migration strategy, and are migrations reversible?
+- Are referential integrity constraints enforced at the database level, application level, or both?
+- Are state machines explicit with defined transitions, or are state changes scattered across the codebase?
+- Is input data validated at system boundaries before entering the data layer?
+- What is the backup and recovery strategy, and has it been tested?
+- Are there orphaned records or data consistency issues that accumulate over time?
+- How is schema evolution handled for API contracts (versioning, backward compatibility)?
+- Is there a data lifecycle policy (retention, archival, deletion)?
+- Are derived/computed data stores (caches, materialized views, denormalized tables) kept consistent with source data?
+- What happens to in-flight data during deployments or schema migrations?
+
+## Failure Patterns
+
+### Schema Drift
+
+- **Description:** The actual database schema has diverged from what the application code expects, causing runtime errors, data corruption, or silent data loss.
+- **Indicators:**
+  - Migration files that don't match the current database state
+  - ORM model definitions inconsistent with actual table schemas
+  - Queries that reference columns or tables that may not exist in all environments
+  - Manual schema changes applied directly to production without migration files
+- **Severity Tendency:** critical
+
+### Missing Migrations
+
+- **Description:** Schema changes are applied manually or through ad-hoc scripts rather than through a versioned, repeatable migration system.
+- **Indicators:**
+  - No migration directory or migration tool configured
+  - SQL scripts named with dates or "fix_" prefixes applied manually
+  - Different environments have different schema states
+  - Schema changes require coordination calls or runbooks
+- **Severity Tendency:** high
+
+### Inconsistent State Machines
+
+- **Description:** Entity state transitions are managed through scattered conditional logic rather than an explicit state machine, allowing invalid transitions and orphaned states.
+- **Indicators:**
+  - Status fields with string values set in multiple locations across the codebase
+  - No validation of state transitions (e.g., "completed" directly from "draft" skipping "in_progress")
+  - Dead states — status values that exist in the database but no code path produces them
+  - Business logic that checks status with long if/else chains instead of state machine patterns
+- **Severity Tendency:** high
+
+### Data Validation Gaps
+
+- **Description:** User input or external data enters the system without proper validation, allowing malformed, out-of-range, or structurally invalid data to persist in storage.
+- **Indicators:**
+  - No validation middleware or schema validation library in the request pipeline
+  - Database columns without constraints (nullable when shouldn't be, no length limits, no check constraints)
+  - Tests that only use well-formed data — no edge case or boundary testing
+  - Error reports showing unexpected data types or formats in database records
+- **Severity Tendency:** high
+
+### Orphaned Records
+
+- **Description:** Related records become disconnected due to missing cascade deletes, soft-delete inconsistencies, or partial transaction failures, leaving data that references nonexistent parents.
+- **Indicators:**
+  - Foreign keys without ON DELETE behavior defined
+  - Soft-delete implementation that doesn't propagate to related records
+  - Cleanup scripts or cron jobs that exist to "fix" orphaned data
+  - Queries with LEFT JOINs where INNER JOINs would be semantically correct (defensive coding around orphans)
+- **Severity Tendency:** medium
+
+### Implicit Schema
+
+- **Description:** The data model has no explicit definition — the schema exists only as an emergent property of the code that reads and writes data, common in NoSQL or dynamic-language systems.
+- **Indicators:**
+  - Document databases (MongoDB, DynamoDB) used without schema validation
+  - Dynamic object properties added at various points in the codebase
+  - No TypeScript interfaces, JSON Schema, or Pydantic models for data structures
+  - Different code paths write different fields to the same collection/table
+- **Severity Tendency:** high
+
+### Race Conditions in State Transitions
+
+- **Description:** Concurrent operations can cause state corruption because state reads and writes are not atomic, leading to lost updates, duplicate processing, or invalid state combinations.
+- **Indicators:**
+  - Read-then-write patterns without locking or optimistic concurrency control
+  - No unique constraints or idempotency keys on operations that should be atomic
+  - Race condition bugs in production history (double charges, duplicate records)
+  - State updates using UPDATE without WHERE clause checking current state
+- **Severity Tendency:** critical
+
+## Best Practice Patterns
+
+### Versioned Migrations
+
+- **Replaces Failure Pattern:** Missing Migrations
+- **Abstract Pattern:** Every schema change is captured as a versioned, ordered, idempotent migration file that can be applied forward and (where possible) rolled back. The migration history is the authoritative record of schema evolution.
+- **Framework Mappings:**
+  - Rails: ActiveRecord migrations with `db:migrate` and `db:rollback` — timestamped, reversible, tracked in `schema_migrations` table
+  - Django: `makemigrations` + `migrate` — auto-generated from model changes, dependency-tracked
+  - Laravel: Artisan migrations with `up()` and `down()` methods, batch-tracked
+- **Language Patterns:**
+  - Node.js: Knex migrations or Prisma Migrate with explicit up/down SQL
+  - Go: golang-migrate or Atlas with versioned SQL files and checksum verification
+
+### Schema-Code Synchronization
+
+- **Replaces Failure Pattern:** Schema Drift
+- **Abstract Pattern:** The database schema and application code are kept in sync through automated checks that detect divergence. Schema validation runs in CI to ensure the code's expectations match the actual database structure.
+- **Framework Mappings:**
+  - Prisma: `prisma db pull` + `prisma migrate diff` to detect drift between schema file and live database
+  - Django: `makemigrations --check` in CI fails if model definitions don't match the current migration state
+  - Flyway: `flyway validate` checks that applied migrations match the expected checksums and sequence
+- **Language Patterns:**
+  - Any: CI pipeline step that compares declared schema against actual database and fails on mismatch
+  - TypeScript/Python: ORM schema introspection tools that generate drift reports as part of deployment checks
+
+### Explicit State Machines
+
+- **Replaces Failure Pattern:** Inconsistent State Machines
+- **Abstract Pattern:** State transitions are modeled as a finite state machine with explicitly defined states, allowed transitions, guard conditions, and side effects. Invalid transitions are rejected, not silently ignored.
+- **Framework Mappings:**
+  - Ruby: `aasm` gem — declarative state machine DSL with events, guards, and callbacks
+  - Python: `transitions` library — lightweight FSM with diagram generation
+  - Laravel: `spatie/laravel-model-states` — type-safe state transitions with configurable transition classes
+- **Language Patterns:**
+  - TypeScript: Discriminated unions for states with exhaustive switch statements enforcing transition handling
+  - Java/Kotlin: Enum-based state machines with transition methods that return `Optional<NextState>`
+
+### Input Validation at Boundaries
+
+- **Replaces Failure Pattern:** Data Validation Gaps
+- **Abstract Pattern:** All data entering the system is validated at the boundary — API endpoints, message consumers, file parsers — using schema validation that rejects invalid data before it reaches business logic or persistence.
+- **Framework Mappings:**
+  - Express: `zod` or `joi` validation middleware applied at route level
+  - Spring Boot: `@Valid` annotation with Bean Validation (JSR 380) on request DTOs
+  - FastAPI: Pydantic models as request types — automatic validation and documentation
+- **Language Patterns:**
+  - TypeScript: Zod schemas that parse (not just type-check) incoming data: `const user = UserSchema.parse(req.body)`
+  - Python: Pydantic models or `marshmallow` schemas at every external data entry point
+
+### Referential Integrity Enforcement
+
+- **Replaces Failure Pattern:** Orphaned Records
+- **Abstract Pattern:** Relationships between records are enforced at the database level through foreign keys, cascade rules, and constraints — not solely through application logic. The database is the last line of defense for data consistency.
+- **Framework Mappings:**
+  - PostgreSQL: Foreign keys with explicit ON DELETE (CASCADE, SET NULL, RESTRICT) based on domain semantics
+  - Rails: `dependent: :destroy` at the model level plus database-level foreign key constraints
+  - Django: `on_delete` parameter (CASCADE, PROTECT, SET_NULL) on ForeignKey fields
+- **Language Patterns:**
+  - SQL: `ALTER TABLE ADD CONSTRAINT ... FOREIGN KEY ... ON DELETE CASCADE` for parent-owned children
+  - Any ORM: Configure both ORM-level and database-level constraints — belt and suspenders approach
+
+### Schema-First Data Modeling
+
+- **Replaces Failure Pattern:** Implicit Schema
+- **Abstract Pattern:** Data schemas are defined explicitly and centrally before code is written against them. The schema definition is the source of truth — code is generated from or validated against the schema, not the other way around.
+- **Framework Mappings:**
+  - Prisma: Schema file as single source of truth generating client, types, and migrations
+  - Protocol Buffers / gRPC: .proto files defining data structures with code generation for all languages
+  - JSON Schema: Central schema definition with runtime validation in document databases
+- **Language Patterns:**
+  - TypeScript: Zod schemas that generate TypeScript types: `type User = z.infer<typeof UserSchema>`
+  - Python: Pydantic models serving as both validation and documentation for data structures
+
+### Optimistic Concurrency Control
+
+- **Replaces Failure Pattern:** Race Conditions in State Transitions
+- **Abstract Pattern:** State modifications include a version check — each update verifies that the record hasn't changed since it was read. Conflicts are detected and surfaced rather than silently overwritten.
+- **Framework Mappings:**
+  - JPA/Hibernate: `@Version` annotation on a version column — automatic optimistic locking
+  - Rails: `lock_version` column with built-in ActiveRecord optimistic locking
+  - DynamoDB: Conditional writes using `ConditionExpression` to enforce atomic state transitions
+- **Language Patterns:**
+  - SQL: `UPDATE ... SET status = 'shipped', version = version + 1 WHERE id = ? AND version = ?` — zero affected rows means conflict
+  - Any: Idempotency keys on write operations to safely retry without duplication
+
+## Red Flags
+
+- No migration directory or migration tool in the project
+- Database columns with `TEXT` type where structured data is stored (JSON as unvalidated strings)
+- Status fields with string type and no enum constraint
+- Multiple code locations writing to the same table with different field assumptions
+- Manual SQL scripts in a `fixes/` or `patches/` directory
+- Foreign keys missing between obviously related tables
+- No `created_at` / `updated_at` timestamps on tables that track entities
+- Soft-delete (`deleted_at`) without corresponding query scoping
+- NoSQL collections with no schema validation configured
+- Data transformation logic scattered across controllers, services, and background jobs
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| sonarqube | Data flow analysis, detecting potential null dereferences and unvalidated data usage | contextual |
+| semgrep | Pattern detection for SQL injection, unparameterized queries, missing validation, raw query construction | supporting |
+| checkov | Infrastructure-as-code database configuration — encryption, backup, access controls | supporting |
+
+## Standards & Frameworks
+
+- Database normalization (1NF through BCNF) — structured approach to eliminating data redundancy and anomalies
+- ACID properties — Atomicity, Consistency, Isolation, Durability as transaction correctness guarantees
+- CAP theorem — Consistency, Availability, Partition tolerance trade-offs for distributed data systems
+- Event Sourcing — Storing state as an append-only sequence of events for full auditability and replay
+- CQRS (Command Query Responsibility Segregation) — Separating read and write models for data access optimization
+- Schema evolution patterns (Avro, Protobuf) — Forward and backward compatible schema changes
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| Migration count vs schema age | Ratio of migrations to system age (months) | ≥1 migration per month of active development |
+| Orphan record percentage | Percentage of child records referencing nonexistent parents | 0% |
+| Foreign key coverage | Percentage of relationships enforced by database-level foreign keys | >90% |
+| Schema validation coverage | Percentage of external data entry points with schema validation | >95% |
+| State machine explicitness | Percentage of stateful entities with formally defined state machines | >80% for entities with ≥3 states |

package/modules/radar/src/domains/03-correctness.md

@@ -0,0 +1,230 @@
+---
+id: domain-03
+number: "03"
+name: Correctness & Logic
+owner_agents: [senior-app-engineer]
+---
+
+## Overview
+
+This domain covers logic correctness, error propagation, edge case handling, concurrency safety, input validation, invariant enforcement, and idempotency. Most production incidents stem from mundane logic bugs rather than exotic failures. This domain focuses on whether the code does what it claims to do under all conditions, including edge cases, concurrent execution, and failure scenarios. Does NOT cover security vulnerabilities (domain 04), testing strategies (domain 06), or architectural patterns (domain 01).
+
+## Audit Questions
+
+- Are errors caught and propagated with sufficient context, or are they silently swallowed?
+- Does the code handle edge cases like empty collections, boundary values, and null inputs?
+- Are race conditions possible in concurrent access to shared state?
+- Are critical assumptions documented and validated at runtime?
+- Is input validation performed before business logic execution?
+- Are invariants explicitly enforced at state transition boundaries?
+- Can retry operations be safely executed multiple times without side effects?
+- Does error handling follow a consistent pattern across the codebase?
+- Are null/undefined values handled defensively throughout data flows?
+- Are off-by-one errors prevented in loops, pagination, and range operations?
+- Do concurrent operations maintain data consistency guarantees?
+- Are temporal assumptions (ordering, timing) explicitly validated?
+
+## Failure Patterns
+
+### Swallowed Errors
+- **Description:** Exceptions or error conditions are caught but not logged, propagated, or handled, causing silent failures that are difficult to diagnose in production.
+- **Indicators:**
+  - Empty catch blocks or catch blocks with only comments
+  - Error handlers that return default values without logging
+  - Promise rejections without .catch() handlers
+  - Error objects created but never thrown or returned
+  - try-catch wrapping entire functions without discrimination
+- **Severity Tendency:** high
+
+### Missing Edge Case Handling
+- **Description:** Code assumes happy-path conditions and fails on boundary values, empty inputs, or unusual but valid data states.
+- **Indicators:**
+  - No validation for empty arrays before accessing elements
+  - Division operations without zero checks
+  - String operations without length validation
+  - Loops that assume non-empty collections
+  - Missing null/undefined checks before property access
+  - Pagination logic that fails on single-page results
+- **Severity Tendency:** medium
+
+### Race Conditions
+- **Description:** Concurrent operations on shared state produce inconsistent results due to timing-dependent execution order.
+- **Indicators:**
+  - Check-then-act patterns without synchronization
+  - Shared mutable state accessed from multiple threads/async contexts
+  - Database reads followed by writes without transactions
+  - Cache invalidation logic that races with updates
+  - Counter increments without atomic operations
+  - File operations without locking mechanisms
+- **Severity Tendency:** critical
+
+### Implicit Assumptions
+- **Description:** Code relies on undocumented assumptions about data shape, execution environment, or temporal conditions that may not hold.
+- **Indicators:**
+  - Missing assertions for preconditions
+  - Array access without bounds checking
+  - Type coercion without validation
+  - Assumptions about API response structure without schema validation
+  - Hard-coded constants derived from production data
+  - Dependencies on execution order without enforcement
+- **Severity Tendency:** high
+
+### Missing Input Validation
+- **Description:** External inputs are processed without validation, allowing invalid data to corrupt business logic or system state.
+- **Indicators:**
+  - API handlers that directly use request parameters
+  - Database queries constructed from unvalidated input
+  - File paths constructed from user input without sanitization
+  - Numeric inputs used in calculations without range checks
+  - Enum values not validated against allowed set
+  - Date/time inputs without format validation
+- **Severity Tendency:** high
+
+### Non-Idempotent Retries
+- **Description:** Retry logic can produce duplicate side effects because operations are not designed to be safely re-executed.
+- **Indicators:**
+  - Operations that create resources without uniqueness checks
+  - Retry logic that increments counters multiple times
+  - Payment processing without idempotency keys
+  - Email sending in retry paths without deduplication
+  - Database inserts in retry handlers without conflict resolution
+  - Event publishing without delivery guarantees
+- **Severity Tendency:** critical
+
+### Inconsistent Error Propagation
+- **Description:** Error handling patterns vary across the codebase, making it difficult to predict failure behavior and implement reliable error recovery.
+- **Indicators:**
+  - Mix of error codes, exceptions, and sentinel values
+  - Some functions return errors, others throw exceptions
+  - Inconsistent use of Result/Either types
+  - Error messages lack context or stack traces
+  - Different error formats from different modules
+  - No standardized error hierarchy or taxonomy
+- **Severity Tendency:** medium
+
+## Best Practice Patterns
+
+### Explicit Error Propagation
+- **Replaces Failure Pattern:** Swallowed Errors
+- **Abstract Pattern:** Every error should be logged with context and either handled locally with recovery logic or propagated to a caller capable of making handling decisions. Error handling should be explicit and traceable.
+- **Framework Mappings:**
+  - Express.js: Centralized error middleware with `next(error)` propagation
+  - Spring Boot: `@ControllerAdvice` with exception hierarchies
+  - FastAPI: Exception handlers with status code mapping
+- **Language Patterns:**
+  - Go: Explicit error returns with `if err != nil` checks and `fmt.Errorf` wrapping
+  - Rust: Result<T, E> types with `?` operator for propagation
+  - TypeScript: Either/Result types or explicit Promise rejection handling
+
+### Defensive Edge Case Guards
+- **Replaces Failure Pattern:** Missing Edge Case Handling
+- **Abstract Pattern:** Validate boundary conditions, empty states, and null cases before executing business logic. Use guard clauses to fail fast with clear error messages.
+- **Framework Mappings:**
+  - Django: Model field validators with `clean()` methods
+  - Rails: ActiveModel validations with custom validators
+  - NestJS: ValidationPipe with class-validator decorators
+- **Language Patterns:**
+  - Python: Guard clauses with early returns and `assert` for invariants
+  - Java: Optional<T> for nullable values with `orElseThrow()`
+  - JavaScript: Nullish coalescing and optional chaining with validation
+
+### Synchronized State Access
+- **Replaces Failure Pattern:** Race Conditions
+- **Abstract Pattern:** Use locks, atomic operations, or immutable data structures to ensure state consistency under concurrent access. Prefer isolation mechanisms provided by databases or message queues.
+- **Framework Mappings:**
+  - PostgreSQL: Serializable transactions with SELECT FOR UPDATE
+  - Redis: MULTI/EXEC transactions or Lua scripts for atomicity
+  - MongoDB: Document-level atomic operations with transactions
+- **Language Patterns:**
+  - Java: `synchronized` blocks or `java.util.concurrent` locks
+  - Go: Mutexes (`sync.Mutex`) or channels for coordination
+  - Rust: Arc<Mutex<T>> or lock-free atomic types
+
+### Documented Preconditions
+- **Replaces Failure Pattern:** Implicit Assumptions
+- **Abstract Pattern:** Document assumptions as executable assertions or type constraints. Validate preconditions at function boundaries and invariants at state transitions.
+- **Framework Mappings:**
+  - DbC libraries: Contract-based programming with precondition/postcondition decorators
+  - GraphQL: Schema validation enforcing structure assumptions
+  - OpenAPI: Request/response schemas with strict validation
+- **Language Patterns:**
+  - TypeScript: Branded types and discriminated unions for compile-time guarantees
+  - Python: Type hints with runtime validation via Pydantic
+  - C++: Concepts and static assertions for template constraints
+
+### Validated Input Boundaries
+- **Replaces Failure Pattern:** Missing Input Validation
+- **Abstract Pattern:** Validate all external inputs at system boundaries using schema validation or type systems before allowing data to flow into business logic.
+- **Framework Mappings:**
+  - Zod/Yup: Schema validation for JavaScript/TypeScript APIs
+  - JSON Schema: Standardized validation across languages
+  - Bean Validation: JSR-380 annotations for Java
+- **Language Patterns:**
+  - Rust: Type system ensures validation at compile time with newtype patterns
+  - Elixir: Ecto changesets for data validation and casting
+  - Scala: Refined types for compile-time constraint enforcement
+
+### Idempotent Operations
+- **Replaces Failure Pattern:** Non-Idempotent Retries
+- **Abstract Pattern:** Design operations to produce the same outcome regardless of how many times they are executed. Use idempotency keys, conditional writes, or natural idempotence.
+- **Framework Mappings:**
+  - Stripe API: Idempotency-Key headers for payment operations
+  - AWS S3: ETags for conditional writes
+  - HTTP: PUT and DELETE methods with idempotent semantics
+- **Language Patterns:**
+  - SQL: INSERT ... ON CONFLICT DO NOTHING for safe retries
+  - REST: Idempotency middleware checking request fingerprints
+  - Event Sourcing: Append-only logs with deduplication on read
+
+### Standardized Error Handling
+- **Replaces Failure Pattern:** Inconsistent Error Propagation
+- **Abstract Pattern:** Establish a single error handling strategy across the codebase with consistent error types, context propagation, and recovery patterns.
+- **Framework Mappings:**
+  - gRPC: Status codes with structured error details
+  - Problem Details (RFC 7807): Standardized HTTP error responses
+  - GraphQL: Errors array with extensions for context
+- **Language Patterns:**
+  - Go: Error wrapping with `fmt.Errorf("%w", err)` and `errors.Is()`
+  - Java: Exception hierarchies with checked/unchecked distinction
+  - Kotlin: Sealed classes for exhaustive error handling
+
+## Red Flags
+
+- Empty catch blocks or generic exception handlers without logging
+- Array/list access with hardcoded indices like `items[0]`
+- Division operations without denominator checks
+- Check-then-act patterns: `if (exists) { use() }`
+- Missing null checks before method calls or property access
+- Retry logic that doesn't use idempotency keys or uniqueness constraints
+- Error handling that varies between similar functions
+- String parsing without format validation
+- Numeric operations without overflow protection
+- Assumptions about API response structure without validation
+- Concurrent access to shared state without synchronization primitives
+- Database operations outside transactions when consistency matters
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| SonarQube | Null pointer risks, complexity metrics, error handling gaps | primary |
+| Semgrep | Logic patterns, validation missing, concurrency issues | primary |
+| git-history | Logic change patterns, bug fix frequency in modules | contextual |
+
+## Standards & Frameworks
+
+- Defensive Programming Principles: Validate inputs, handle errors explicitly, fail fast
+- Design by Contract (DbC): Preconditions, postconditions, invariants as first-class concerns
+- CWE-703 (Improper Check or Handling of Exceptional Conditions): Industry classification of error handling failures
+- ACID Properties: Atomicity, Consistency, Isolation, Durability for data correctness
+- CAP Theorem Awareness: Understanding consistency trade-offs in distributed systems
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| Bug Density (bugs per KLOC) | Logic defects found in production or testing per thousand lines | <0.5 for mature code, <2.0 for new features |
+| Error Handling Coverage | Percentage of functions with explicit error handling paths | >90% |
+| Cyclomatic Complexity (Hot Paths) | Decision point density in critical business logic | <10 per function in performance-critical or high-risk paths |
+| Null Safety Violations | Potential null pointer dereferences detected by static analysis | 0 in critical paths, <5 per 10K LOC overall |
+| Race Condition Density | Concurrent access issues per 1K LOC of concurrent code | <0.1 |