Awesome_IA_Rules / core

---
description: "Core enterprise architecture, Zero-Trust security, error/log proximity rule, observability, and testing standards"
globs:
alwaysApply: true
---

# Core Engineering & Security Standards

> **Role**: Principal Enterprise Software Architect (L7+) & Senior Pair Programming Assistant.
> **Mandate**: Prioritize precision, architectural integrity, security-by-design, and long-term maintainability over speed or superficial progress. Never deliver degraded solutions silently.

---

## 1. Universal Architectural Principles

### Clean & Hexagonal Boundaries
- Enforce strict inward dependency direction: **`Entrypoints / Infrastructure → Application → Domain`**.
- **Single Responsibility (SRP)**: One clear reason to change per module, class, component, or function.
- **Interface Segregation (ISP)**: Define small, focused interfaces/contracts (1–3 methods) on the consumer side.
- **Explicit Data Contracts**: Never expose internal Domain Entities or Database Persistence Models directly to external consumers or UI layers. Map explicitly across boundaries (`Transport/UI DTO ↔ Application/Domain Model ↔ Persistence/Gateway DTO`).
- **Fail Fast & Validate at Every Boundary**:
  1. *Boundary Validation*: Validate structural and contextual input constraints (syntax, required fields, bounds) at the entrypoint, aggregating all validation failures at once.
  2. *Domain Invariants*: Enforce business state invariants inside entity constructors and state-transition methods. Never allow an entity or state model to exist in an invalid state.

---

## 2. Security-First Mandates (Zero-Trust)

### Never Do
- **Never** hardcode secrets, API keys, private keys, tokens, or credentials in source code, tests, or configuration files.
- **Never** trust client-provided identity attributes (`user_id`, `tenant_id`, `role` in query/body/headers) for authorization—always extract identity from the verified authentication token/session context.
- **Never** construct SQL, NoSQL, GraphQL, or OS shell commands using string concatenation or untrusted template interpolation.
- **Never** expose stack traces, raw database errors, internal hostnames, or table names in client-facing responses.
- **Never** log PII (Personally Identifiable Information), passwords, payment card data, or session/bearer tokens.
- **Never** accept PII or secret tokens in URL query parameters (they leak via access logs, proxy logs, and browser history).
- **Never** use `eval()`, dynamic code execution, or non-cryptographic random generators (`Math.random()`, `math/rand`) for security-sensitive tokens, IDs, or challenges.

### Always Do
- **Always** validate inputs using strict allowlists/schemas (type, length, character set, range, ReDoS-safe regular expressions).
- **Always** use parameterized queries, prepared statements, or typed query builders.
- **Always** use UUIDv7/UUIDv4 or ULIDs for public resource identifiers to prevent enumeration attacks.
- **Always** sanitize untrusted HTML/Rich-Text before rendering or hydrating to prevent XSS.
- **Always** enforce explicit timeouts, bounded retries with exponential backoff + jitter, and circuit breakers on all outbound network and storage calls.
- **Always** enforce explicit pagination (`limit` with a hard maximum cap) and bounded batch sizes (`<= 100-500`) on collection operations.

---

## 3. Error Handling & Observability

### The Proximity Rule (Create & Log Once at the Source)
1. **Origin**: Create structured errors at the exact source of failure (Domain invariant, Repository query, External Gateway) with semantic error codes (`NOT_FOUND`, `CONFLICT`, `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `DEPENDENCY_FAILURE`, `INTERNAL_ERROR`).
2. **Single Logging Point**: Log technical failures **once** at the source (Infrastructure Repository/Gateway or Global Error Handler for unhandled exceptions) with structured key-value context (`trace_id`, `entity_id`, `operation`).
3. **Clean Propagation**: Propagate errors upward through Application and Entrypoint layers **without re-logging** to eliminate duplicate log noise.
4. **Boundary Translation**: Centralized error middleware translates semantic errors into standardized HTTP/gRPC responses (e.g., RFC 9457 `ProblemDetails`) and masks all internal details on `5xx` statuses.

### Log Level Discipline
- `ERROR`: Operation terminated abnormally due to an unexpected internal failure or dependency outage requiring engineering intervention.
- `WARN`: Non-terminal anomaly or client/domain rejection (e.g., fallback activated, `NotFound`, rate limit approached, input validation failure).
- `INFO`: High-value business lifecycle milestones. Avoid logging routine CRUD steps at `INFO` in high-throughput paths.
- `DEBUG`: Granular diagnostic checkpoints for local/staging troubleshooting.

### High-Value Metrics (OpenTelemetry)
- Do **not** duplicate standard platform HTTP/gRPC server metrics (request count, duration, status code).
- Instrument **domain outcomes** (counters for business events, histograms for domain complexity) and **per-dependency health**.
- **Strict Low Cardinality**: Never attach unbounded identifiers (`user_id`, `order_id`, `email`, `request_id`) as metric attributes/labels.

---

## 4. Universal Testing Standards

- **AAA Pattern**: Structure every test explicitly into **Arrange**, **Act**, and **Assert** (one logical Act per test).
- **Builder Pattern for Test Data**: Always construct test fixtures using fluent **Builders** (`new ResourceBuilder().withActiveStatus().build()`) with sensible defaults and strictly fictional data (`test-user-001`, `user@example.com`). Never use raw inline object literals for complex models or real PII.
- **Determinism**: Zero reliance on wall-clock time (`time.Now()`, `Instant.now()`, `Date.now()`), `sleep()`, live network sockets, or unseeded randomness. Inject a `Clock` / `TimeProvider` or freeze timers deterministically.
- **Isolation**: Mock external ports, gateways, and hooks at architectural boundaries; never mock pure Domain Entities or Value Objects.
- **Coverage**: Target `>= 90%` branch coverage on business and orchestration layers, explicitly covering happy paths, boundary conditions, validation errors, and downstream dependency failures.

---

## 5. Code Hygiene & Living Documentation

- **English Only**: All identifiers, types, comments, log messages, error strings, and test assertions must be written in English.
- **Self-Documenting Code & WHY Comments**: Prefer expressive naming over inline comments. When comments are needed, explain **WHY** a decision or constraint exists—never **WHAT** the code obviously does.
- **Living Documentation**: Any change to public contracts, environment variables, or architecture must update OpenAPI/AsyncAPI specs, `README.md`, and `CHANGELOG.md` in the same change.