@evolith/core-domain 1.0.1 → 1.0.3

package/rulesets/adr/adr-0002-hexagonal-architecture.rules.json

@@ -1,103 +0,0 @@
-{
-  "$schema": "../schema/ruleset-standard.schema.json",
-  "$id": "https://evolith.dev/rulesets/adr/adr-0002-hexagonal-architecture.rules.json",
-  "title": "ADR-0002 — Hexagonal Architecture (Ports & Adapters) Rules",
-  "description": "Machine-readable rules encoding ADR-0002 Clean Hexagonal Architecture. Mandatory structural pattern for all Evolith applications.",
-  "version": "1.0.0",
-  "adrId": "ADR-0002",
-  "adrTitle": "Clean Hexagonal Architecture with NestJS",
-  "status": "Approved",
-  "date": "2026-05-08",
-  "effectiveDate": "2026-05-08",
-  "rules": [
-    {
-      "id": "HXA-01",
-      "severity": "MUST",
-      "category": "layer-structure",
-      "title": "Core (Domain) has zero framework dependencies",
-      "description": "The Core/Domain layer MUST contain only pure TypeScript classes. Zero imports from NestJS, TypeORM, Express, or any external SDK. Contains entities, value objects, and port interfaces only.",
-      "rationale": "ADR-0002 §Decision: Core is pure TypeScript. Framework coupling prevents domain extraction and pure testing.",
-      "validationQuery": "Static analysis: Core layer files import no framework packages (nestjs, typeorm, express, mongoose).",
-      "blocking": true,
-      "layer": "Core"
-    },
-    {
-      "id": "HXA-02",
-      "severity": "MUST",
-      "category": "layer-structure",
-      "title": "Application layer imports Core only",
-      "description": "Application layer (Use Cases) may import Core classes and NestJS DI decorators only. No infrastructure imports (database adapters, external SDKs).",
-      "rationale": "ADR-0002 §Decision: Application orchestrates Core logic. Infrastructure belongs in adapters.",
-      "validationQuery": "Application layer files import only Core layer and @nestjs/common decorators.",
-      "blocking": true,
-      "layer": "Application"
-    },
-    {
-      "id": "HXA-03",
-      "severity": "MUST",
-      "category": "layer-structure",
-      "title": "Infrastructure (Adapters) implements Core ports",
-      "description": "Infrastructure layer contains concrete implementations of Core port interfaces (TypeOrmUserRepository, BcryptPasswordHasher). All framework and SDK imports live exclusively here.",
-      "rationale": "ADR-0002 §Decision: Infrastructure is the adapter layer. It implements the ports defined by Core.",
-      "validationQuery": "Infrastructure files implement interfaces defined in Core layer. No domain logic lives here.",
-      "blocking": true,
-      "layer": "Infrastructure"
-    },
-    {
-      "id": "HXA-04",
-      "severity": "MUST",
-      "category": "dependency-direction",
-      "title": "Dependency direction: Infrastructure → Application → Core",
-      "description": "Dependency direction is strictly enforced: Infrastructure depends on Application, Application depends on Core. Never the reverse.",
-      "rationale": "ADR-0002 §Decision: Dependency inversion is the core principle of hexagonal architecture.",
-      "validationQuery": "eslint-plugin-boundaries or equivalent static analysis enforces no backward imports.",
-      "blocking": true,
-      "layer": "All"
-    },
-    {
-      "id": "HXA-05",
-      "severity": "MUST NOT",
-      "category": "aop-isolation",
-      "title": "AOP concerns prohibited in Core/Application layers",
-      "description": "Cross-cutting concerns (Logging, Auditing, OTel, Caching, Transactions) MUST NOT hard-couple third-party decorators or SDKs inside Core or Application layers. Prohibited: @SentryCapture, @OpentelemetrySpan, @Cacheable on UseCase methods.",
-      "rationale": "ADR-0002 §4: AOP isolation rule. Framework decorators in domain pollute the domain with infrastructure concerns.",
-      "validationQuery": "Core/Application classes have no imports from Sentry, OpenTelemetry SDK, caching libraries, or transaction managers.",
-      "blocking": true,
-      "layer": "Core, Application"
-    },
-    {
-      "id": "HXA-06",
-      "severity": "MUST",
-      "category": "aop-isolation",
-      "title": "AOP implemented exclusively in Infrastructure layer",
-      "description": "Cross-cutting concerns MUST be encapsulated exclusively inside NestJS Interceptors, Middleware, or Decorator Wrappers residing in the Infrastructure/Adapter layer, wrapping pure UseCase execution from the outside.",
-      "rationale": "ADR-0002 §4: AOP in adapters preserves domain purity while enabling observability.",
-      "validationQuery": "AOP implementations (interceptors, middleware, decorators) exist only in Infrastructure layer.",
-      "blocking": false,
-      "layer": "Infrastructure"
-    },
-    {
-      "id": "HXA-07",
-      "severity": "MUST",
-      "category": "testing",
-      "title": "Core domain tests run without framework bootstrap",
-      "description": "Pure domain tests (entities, value objects, port interfaces) MUST run in milliseconds with no database or framework setup. Tests must not execute IO or container startups.",
-      "rationale": "ADR-0002 §Consequences: Pure domain tests are fast and framework-independent.",
-      "validationQuery": "Domain unit tests execute without TestBed or testcontainer initialization. Average execution time < 50ms per test file.",
-      "blocking": false,
-      "layer": "Core"
-    }
-  ],
-  "references": [
-    "reference/architecture/adrs/nodejs/0002-clean-architecture-nestjs.md",
-    "reference/architecture/adrs/nodejs/0003-strict-typescript-standards.md"
-  ],
-  "exitCriteria": {
-    "description": "All HXA rules are validated in CI via eslint-plugin-boundaries and import analysis.",
-    "validationTools": [
-      "eslint-plugin-boundaries",
-      "dependency-cruiser",
-      "custom AST rules"
-    ]
-  }
-}

package/rulesets/adr/adr-0005-cicd-quality-gates.rules.json

@@ -1,102 +0,0 @@
-{
-  "$schema": "../schema/ruleset-standard.schema.json",
-  "$id": "https://evolith.dev/rulesets/adr/adr-0005-cicd-quality-gates.rules.json",
-  "title": "ADR-0005 — CI/CD Security Quality Gates Rules",
-  "description": "Machine-readable rules encoding ADR-0005 CI/CD Security Quality Gates. Mandatory gates for every merge to protected branches.",
-  "version": "1.0.0",
-  "adrId": "ADR-0005",
-  "adrTitle": "CI/CD Security Quality Gates with CodeQL",
-  "status": "Approved",
-  "date": "2026-05-08",
-  "effectiveDate": "2026-05-08",
-  "rules": [
-    {
-      "id": "CICD-01",
-      "severity": "MUST",
-      "category": "security-scan",
-      "title": "CodeQL Static Analysis runs on every PR",
-      "description": "GitHub CodeQL must run on every pull request. Scans for OWASP Top 10 vulnerability patterns in TypeScript source code. PRs with High or Critical findings are BLOCKED from merging.",
-      "rationale": "ADR-0005 §Decision: Security enforced mechanically, not left to human review.",
-      "validationQuery": "CI pipeline includes CodeQL scan step. PRs with CRITICAL/HIGH findings cannot complete merge.",
-      "blocking": true,
-      "sla": {
-        "critical": "24 hours",
-        "high": "72 hours"
-      }
-    },
-    {
-      "id": "CICD-02",
-      "severity": "MUST",
-      "category": "dependency-scan",
-      "title": "Dependency vulnerability scan blocks merge",
-      "description": "npm audit --audit-level=high (or equivalent for other languages) runs in CI. Any dependency with a High or Critical CVE blocks the pipeline.",
-      "rationale": "ADR-0005 §Decision: Third-party dependencies can introduce known CVEs that go undetected without automated scanning.",
-      "validationQuery": "CI pipeline runs dependency audit. Pipeline fails on High/Critical CVE detection.",
-      "blocking": true
-    },
-    {
-      "id": "CICD-03",
-      "severity": "MUST",
-      "category": "secret-detection",
-      "title": "Secret detection enabled on repository",
-      "description": "GitHub's built-in secret scanning is enabled on the repository to detect accidentally committed API keys or credentials. Commits containing secrets are rejected.",
-      "rationale": "ADR-0005 §Decision: Secret detection prevents credential leakage at the source.",
-      "validationQuery": "Secret scanning is enabled in repository settings. Pre-commit hooks detect known secret patterns.",
-      "blocking": true
-    },
-    {
-      "id": "CICD-04",
-      "severity": "MUST",
-      "category": "pipeline-structure",
-      "title": "All quality gates execute before merge",
-      "description": "All quality gates (CodeQL, dependency scan, lint, tests, coverage) MUST complete successfully before a PR can merge. No merge with failing pipeline.",
-      "rationale": "ADR-0005 §Pipeline gates: Mechanical enforcement before merge.",
-      "validationQuery": "Protected branch requires all CI checks green. No override allowed without explicit waiver.",
-      "blocking": true
-    },
-    {
-      "id": "CICD-05",
-      "severity": "MUST",
-      "category": "documentation",
-      "title": "Security findings documented with justification",
-      "description": "False positive suppressions require documented justification comments in code. Suppressed findings must include a reason and an issue tracker reference.",
-      "rationale": "ADR-0005 §Consequences: False positives require manual suppression with documented justification.",
-      "validationQuery": "Suppressed findings have inline comments explaining justification and JIRA/Ticket reference.",
-      "blocking": false
-    },
-    {
-      "id": "CICD-06",
-      "severity": "MUST",
-      "category": "sla-compliance",
-      "title": "Critical findings resolved within 24 hours",
-      "description": "All Critical severity findings from CodeQL or dependency scans MUST be resolved within 24 hours of detection.",
-      "rationale": "ADR-0005 §SLA: Critical findings require immediate response.",
-      "validationQuery": "Issue tracker has Critical findings with age <= 24 hours or explicit SLA waiver.",
-      "blocking": false,
-      "enforcement": "Issue tracker integration or automated escalation"
-    },
-    {
-      "id": "CICD-07",
-      "severity": "MUST",
-      "category": "sla-compliance",
-      "title": "High findings resolved within 72 hours",
-      "description": "All High severity findings from CodeQL or dependency scans MUST be resolved within 72 hours of detection.",
-      "rationale": "ADR-0005 §SLA: High findings require timely response.",
-      "validationQuery": "Issue tracker has High findings with age <= 72 hours or explicit SLA waiver.",
-      "blocking": false
-    }
-  ],
-  "references": [
-    "reference/architecture/adrs/core/0005-ci-cd-quality-codeql.md",
-    "reference/architecture/adrs/core/0009-strict-dependency-pinning-vulnerability-management.md"
-  ],
-  "exitCriteria": {
-    "description": "All CI/CD gates pass. Protected branches enforce all checks. SLA compliance tracked.",
-    "validationTools": [
-      "GitHub Actions",
-      "CodeQL",
-      "npm audit",
-      "pre-commit hooks"
-    ]
-  }
-}

package/rulesets/adr/adr-0010-multi-tenancy.rules.json

@@ -1,129 +0,0 @@
-{
-  "$schema": "../schema/ruleset-standard.schema.json",
-  "$id": "https://evolith.dev/rulesets/adr/adr-0010-multi-tenancy.rules.json",
-  "title": "ADR-0010 — Multi-Tenancy Architecture Strategy Rules",
-  "description": "Machine-readable rules encoding ADR-0010 Multi-Tenancy Architecture. Conditional rules for products serving multiple tenants with dual-layer filtering.",
-  "version": "1.0.0",
-  "adrId": "ADR-0010",
-  "adrTitle": "Multi-Tenancy Architecture Strategy",
-  "status": "Approved",
-  "date": "2026-05-08",
-  "effectiveDate": "2026-05-08",
-  "conditional": true,
-  "condition": "REQUIRED when product serves multiple tenants. Single-tenant products may defer.",
-  "rules": [
-    {
-      "id": "MTN-01",
-      "severity": "MUST",
-      "category": "filtering-layer",
-      "title": "Application-layer tenant filtering is primary",
-      "description": "Application-layer filtering (WHERE tenant_id = X) is the PRIMARY enforcement mechanism for tenant data isolation. Every query that returns tenant-owned data MUST include tenant_id filter.",
-      "rationale": "ADR-0010: Application-layer filtering as primary mechanism. Always filter by tenant context.",
-      "validationQuery": "All repository queries include tenant_id in WHERE clause. No raw queries that bypass application context.",
-      "blocking": true,
-      "layer": "Application"
-    },
-    {
-      "id": "MTN-02",
-      "severity": "MUST",
-      "category": "filtering-layer",
-      "title": "Database-native tenant enforcement is secondary",
-      "description": "Database-native enforcement (RLS policies, separate schemas) is the SECONDARY failsafe mechanism. Database enforcement supplements but does not replace application-layer filtering.",
-      "rationale": "ADR-0010: Dual-layer strategy. Database is failsafe, not primary.",
-      "validationQuery": "Database has RLS or schema-per-tenant. Application-layer filtering still enforced even when DB enforcement exists.",
-      "blocking": true,
-      "layer": "Infrastructure"
-    },
-    {
-      "id": "MTN-03",
-      "severity": "MUST",
-      "category": "context-propagation",
-      "title": "Tenant context propagated through all layers",
-      "description": "Tenant context (tenant_id) MUST be propagated through all layers without exception. Domain logic operates with explicit tenant context. No implicit tenant assumption.",
-      "rationale": "ADR-0010: Tenant context must be explicit and immutable for the duration of the request.",
-      "validationQuery": "TenantId passed as explicit parameter or via scoped context (not static). Domain methods signature includes tenant context.",
-      "blocking": true
-    },
-    {
-      "id": "MTN-04",
-      "severity": "MUST NOT",
-      "category": "data-isolation",
-      "title": "Cross-tenant data access prohibited",
-      "description": "Cross-tenant data access is strictly prohibited. No query, report, or export operation may access data from multiple tenants without explicit multi-tenant authorization.",
-      "rationale": "ADR-0010: Data isolation is non-negotiable. Cross-tenant access requires explicit corporate authorization.",
-      "validationQuery": "Audit logs verify no cross-tenant queries. Access control lists block cross-tenant operations.",
-      "blocking": true
-    },
-    {
-      "id": "MTN-05",
-      "severity": "MUST",
-      "category": "schema-per-tenant",
-      "title": "Multi-tenant schema strategy defined upfront",
-      "description": "The multi-tenant schema strategy (shared schema with tenant_id, separate schema per tenant, or separate database per tenant) MUST be defined before Phase 2 Design and documented in evolith.yaml.",
-      "rationale": "ADR-0010: Schema strategy affects all bounded contexts. Must be decided early.",
-      "validationQuery": "evolith.yaml specifies boundedContexts[].persistence strategy (shared-schema | schema-per-tenant | db-per-tenant).",
-      "blocking": true
-    },
-    {
-      "id": "MTN-06",
-      "severity": "MUST",
-      "category": "audit-trail",
-      "title": "Tenant-scoped audit trail maintained",
-      "description": "All tenant operations MUST be logged with tenant context. Audit trail enables compliance and security investigation per tenant.",
-      "rationale": "ADR-0010: Audit trail must be tenant-scoped for compliance and security.",
-      "validationQuery": "All audit logs include tenant_id field. Logs are immutable and retained per compliance requirements.",
-      "blocking": false,
-      "layer": "Infrastructure"
-    },
-    {
-      "id": "MTN-07",
-      "severity": "MUST",
-      "category": "data-migration",
-      "title": "Tenant migration path defined for schema changes",
-      "description": "When schema changes affect tenant data (new tenant column, migration scripts), the migration MUST include tenant-aware rollback and validation. No schema migration that breaks tenant data integrity.",
-      "rationale": "ADR-0010: Schema migrations in multi-tenant context are high-risk. Tenant data integrity must be preserved.",
-      "validationQuery": "Migration scripts include tenant validation tests. Rollback tested with tenant data present.",
-      "blocking": true
-    },
-    {
-      "id": "MTN-08",
-      "severity": "MUST",
-      "category": "external-api",
-      "title": "External APIs validate tenant context on every request",
-      "description": "Every API endpoint that handles tenant data MUST validate tenant context from authentication token or header. Requests without valid tenant context are rejected with 403 Forbidden.",
-      "rationale": "ADR-0010: API endpoints must enforce tenant context at the boundary.",
-      "validationQuery": "API middleware validates tenant_id from JWT/token on every request. Invalid tenant context returns 403.",
-      "blocking": true,
-      "layer": "Api"
-    }
-  ],
-  "schemaStrategies": [
-    {
-      "strategy": "shared-schema",
-      "description": "All tenants share same database schema with tenant_id column",
-      "useWhen": "Low sensitivity, high tenant count"
-    },
-    {
-      "strategy": "schema-per-tenant",
-      "description": "Each tenant has own PostgreSQL schema",
-      "useWhen": "Moderate sensitivity, moderate tenant count"
-    },
-    {
-      "strategy": "db-per-tenant",
-      "description": "Each tenant has own database",
-      "useWhen": "High sensitivity, low tenant count, strong isolation required"
-    }
-  ],
-  "references": [
-    "reference/architecture/adrs/core/0010-multi-tenancy-architecture-strategy.md",
-    "reference/architecture/adrs/dotnet/0060-dotnet-multi-tenancy-dual-layer-strategy.md"
-  ],
-  "exitCriteria": {
-    "description": "All tenant-scoped queries include tenant_id filter. Database RLS enforced. Tenant context propagated through all layers.",
-    "validationTools": [
-      "SQL analysis",
-      "integration tests with tenant isolation",
-      "security scan"
-    ]
-  }
-}

package/rulesets/adr/adr-0018-testing-pyramid.rules.json

@@ -1,115 +0,0 @@
-{
-  "$schema": "../schema/ruleset-standard.schema.json",
-  "$id": "https://evolith.dev/rulesets/adr/adr-0018-testing-pyramid.rules.json",
-  "title": "ADR-0018 — Testing Pyramid and Quality Gates Rules",
-  "description": "Machine-readable rules encoding ADR-0018 Testing Pyramid. Enforces layered testing with distribution targets and blocking thresholds.",
-  "version": "1.0.0",
-  "adrId": "ADR-0018",
-  "adrTitle": "Testing Pyramid and Automated Quality Gates",
-  "status": "Approved",
-  "date": "2026-05-08",
-  "effectiveDate": "2026-05-08",
-  "rules": [
-    {
-      "id": "TPY-01",
-      "severity": "MUST",
-      "category": "test-layer-distribution",
-      "title": "Test distribution follows 70/20/10 pyramid",
-      "description": "Test suite distribution MUST target: 70% unit tests, 20% integration tests, 10% E2E tests. Deviation beyond 5% tolerance requires written explanation in PR.",
-      "rationale": "ADR-0018 §Decision: Rigid test requirements prevent gradual regression. Pyramid distribution enforces coverage quality.",
-      "validationQuery": "CI reports test count by type. Distribution checked against target ±5% tolerance.",
-      "blocking": false,
-      "target": {
-        "unit": 70,
-        "integration": 20,
-        "e2e": 10,
-        "tolerance": 5
-      }
-    },
-    {
-      "id": "TPY-02",
-      "severity": "MUST",
-      "category": "unit-testing",
-      "title": "Unit tests dominate total test volume",
-      "description": "Unit tests MUST dominate the total test volume. Unit tests isolate pure core and application classes. Tests must not execute IO or container startups.",
-      "rationale": "ADR-0018 §Decision: Unit layer dominates total test volume using standard Jest executions isolating pure core and application classes.",
-      "validationQuery": "Unit test execution time < 50ms average. No testcontainer, database, or HTTP call in unit tests.",
-      "blocking": true,
-      "layer": "Core, Application"
-    },
-    {
-      "id": "TPY-03",
-      "severity": "MUST",
-      "category": "integration-testing",
-      "title": "Integration tests use ephemeral containers",
-      "description": "Integration tests MUST test persistence and gateway adapters against active databases using testcontainer engines (e.g., live PostgreSQL/Redis in ephemeral containers). No shared state between test runs.",
-      "rationale": "ADR-0018 §Decision: Integration layer uses testcontainers for safe, isolated database testing.",
-      "validationQuery": "Integration tests use ephemeral containers. No mutable shared database state across test runs.",
-      "blocking": false,
-      "layer": "Infrastructure"
-    },
-    {
-      "id": "TPY-04",
-      "severity": "MUST",
-      "category": "e2e-testing",
-      "title": "E2E tests cover full HTTP routes",
-      "description": "E2E tests deploy isolated supertest routines orchestrating full HTTP routes (Controller Service Database) testing actual external boundary security and transport.",
-      "rationale": "ADR-0018 §Decision: E2E layer tests complete HTTP integration from controller to database.",
-      "validationQuery": "E2E tests execute real HTTP requests against deployed service. No mocked services.",
-      "blocking": false,
-      "layer": "Api"
-    },
-    {
-      "id": "TPY-05",
-      "severity": "MUST",
-      "category": "coverage-threshold",
-      "title": "Business logic coverage >= 80%",
-      "description": "CI pipeline rigorously denies processing merge commits that collapse general test coverage thresholds underneath 80% for business logic.",
-      "rationale": "ADR-0018 §Decision: Binary gates enforce coverage minimums before code enters target branch.",
-      "validationQuery": "Coverage report shows business logic coverage >= 80%. CI fails below threshold.",
-      "blocking": true,
-      "threshold": 80
-    },
-    {
-      "id": "TPY-06",
-      "severity": "MUST",
-      "category": "per-layer-thresholds",
-      "title": "Per-layer coverage thresholds enforced",
-      "description": "Coverage thresholds are enforced per layer: Domain >= 95%, Application >= 85%, Infrastructure >= 60%, BFF/Controllers >= 70%. Aggregate coverage is insufficient.",
-      "rationale": "Senior Architectural Assessment finding: 70% aggregate can be reached with happy paths only. Layer differentiation is required for hexagonal architectures with rich domains.",
-      "validationQuery": "Jest/Istanbul configured with coverageThresholds by path pattern. Each layer meets its threshold.",
-      "blocking": true,
-      "layerThresholds": {
-        "Domain": 95,
-        "Application": 85,
-        "Infrastructure": 60,
-        "Api": 70
-      }
-    },
-    {
-      "id": "TPY-07",
-      "severity": "MUST NOT",
-      "category": "test-isolation",
-      "title": "Unit tests do not execute IO",
-      "description": "Unit tests MUST NOT execute IO operations (file system, network, database). Pure domain tests run in milliseconds with no external dependencies.",
-      "rationale": "ADR-0018 §Decision: Unit tests isolate pure core and application classes. IO would defeat isolation.",
-      "validationQuery": "Unit tests complete without network calls, file system access, or database connections. Mock all external dependencies.",
-      "blocking": true,
-      "layer": "Core, Application"
-    }
-  ],
-  "references": [
-    "reference/architecture/adrs/core/0018-testing-pyramid-quality-gates.md",
-    "reference/architecture/adrs/core/0005-ci-cd-quality-codeql.md",
-    "reference/governance/sdlc/quality-gates.md"
-  ],
-  "exitCriteria": {
-    "description": "Pyramid distribution validated per release. Coverage thresholds enforced in CI. SLA compliance tracked.",
-    "validationTools": [
-      "Jest",
-      "Istanbul",
-      "testcontainers",
-      "supertest"
-    ]
-  }
-}

package/rulesets/adr/adr-0032-protocol-selection.rules.json

@@ -1,134 +0,0 @@
-{
-  "$schema": "../schema/ruleset-standard.schema.json",
-  "$id": "https://evolith.dev/rulesets/adr/adr-0032-protocol-selection.rules.json",
-  "title": "ADR-0032 — API Protocol Selection Matrix Rules",
-  "description": "Machine-readable rules encoding ADR-0032 Protocol Selection Matrix. Mandatory protocol selection for internal, external, and BFF communication.",
-  "version": "1.0.0",
-  "adrId": "ADR-0032",
-  "adrTitle": "API Protocol Selection Matrix (REST vs gRPC vs GraphQL)",
-  "status": "Approved",
-  "date": "2026-05-11",
-  "effectiveDate": "2026-05-11",
-  "rules": [
-    {
-      "id": "PROT-01",
-      "severity": "MUST",
-      "category": "internal-communication",
-      "title": "Internal service-to-service uses gRPC",
-      "description": "MANDATE: gRPC (Protocol Buffers over HTTP/2) for all internal service-to-service communication between bounded contexts. Scope: synchronous calls where both services are owned by the organization.",
-      "rationale": "ADR-0032 §Decision: High performance, binary serialization, and strict type-safety through unified .proto contracts.",
-      "validationQuery": "Internal service calls use gRPC. No REST calls between internal bounded contexts (telemetry confirms).",
-      "blocking": true,
-      "scenario": "Machine-to-Machine (Internal)"
-    },
-    {
-      "id": "PROT-02",
-      "severity": "MUST",
-      "category": "external-communication",
-      "title": "Public and external APIs use REST",
-      "description": "MANDATE: REST (JSON over HTTPS) for all public third-party and external integration. Scope: external customer integrations, legacy corporate gateway connections, and global developer public APIs.",
-      "rationale": "ADR-0032 §Decision: Industry universality, trivial consumption, easiest debugging/testing, broad interactive documentation.",
-      "validationQuery": "Public API endpoints use REST/JSON. OpenAPI spec available for all public APIs.",
-      "blocking": true,
-      "scenario": "Public Third-Party & External Integration"
-    },
-    {
-      "id": "PROT-03",
-      "severity": "MUST",
-      "category": "bff-communication",
-      "title": "BFF uses REST primary, GraphQL targeted",
-      "description": "Default to REST for standard flows (CRUD commands). Adopt GraphQL strictly at the NestJS BFF level ONLY when a screen requires complex data aggregation (fetching Entities, associated Taxonomies, Audits, and relations simultaneously).",
-      "rationale": "ADR-0032 §Decision: Prevents mobile/web over-fetching and multiple sequential roundtrips for rich read scenarios.",
-      "validationQuery": "BFF uses REST for standard CRUD. GraphQL used only for aggregate read scenarios with documented justification.",
-      "blocking": false,
-      "scenario": "Frontend Portals & Dynamic BFF Orchestration"
-    },
-    {
-      "id": "PROT-04",
-      "severity": "MUST NOT",
-      "category": "graphql-isolation",
-      "title": "GraphQL resolvers never in domain layer",
-      "description": "GraphQL runtime logic MUST exist only within Tier-2 BFF application nodes. Core domain API definitions never natively support GraphQL resolvers. This prevents view-specific constraints from leaking into domain business logic.",
-      "rationale": "ADR-0032 §Architecture Guidelines: GraphQL isolation. Core domain must remain protocol-agnostic.",
-      "validationQuery": "No GraphQL resolvers in Core or Application layers. GraphQL exists only in BFF/Api layer.",
-      "blocking": true,
-      "scenario": "Domain Layer"
-    },
-    {
-      "id": "PROT-05",
-      "severity": "MUST",
-      "category": "protobuf-centralization",
-      "title": "Proto files centralized in Contracts library",
-      "description": "All internal gRPC service schemas (.proto) are hosted and versioned in a unified Contracts library (libs/contracts or similar) to prevent drifted interface models.",
-      "rationale": "ADR-0032 §Architecture Guidelines: Protobuf centralization prevents interface drift between services.",
-      "validationQuery": ".proto files exist in shared Contracts library. No duplicate .proto definitions across services.",
-      "blocking": true
-    },
-    {
-      "id": "PROT-06",
-      "severity": "SHOULD",
-      "category": "streaming",
-      "title": "File uploads/streams prefer gRPC streaming",
-      "description": "File uploads and streaming scenarios SHOULD use gRPC streaming capabilities for native streaming or REST multipart as fallback.",
-      "rationale": "ADR-0032 §Selection Decision Tree: Native streaming capability or simple multipart.",
-      "validationQuery": "Streaming endpoints evaluated for gRPC first, REST multipart as fallback.",
-      "blocking": false
-    },
-    {
-      "id": "PROT-07",
-      "severity": "MUST",
-      "category": "contract-versioning",
-      "title": "Breaking changes require version bump",
-      "description": "Breaking changes to inter-service contracts (gRPC .proto or REST OpenAPI) require a new major version. Consumer-driven contract tests must pass before merge.",
-      "rationale": "ADR-0032 §Decision: Contract versioning ensures backward compatibility during service evolution.",
-      "validationQuery": "Contract tests enforce backward compatibility. Breaking changes blocked by CI.",
-      "blocking": true
-    }
-  ],
-  "protocolMatrix": [
-    {
-      "scenario": "Machine-to-Machine (Internal)",
-      "protocol": "gRPC",
-      "justification": "Low latency, binary compaction, strongly typed"
-    },
-    {
-      "scenario": "File Uploads/Streams",
-      "protocol": "gRPC / REST",
-      "justification": "Native streaming or simple multipart"
-    },
-    {
-      "scenario": "Public Open API / Developer Docs",
-      "protocol": "REST",
-      "justification": "Universal standard, easiest vendor adoption"
-    },
-    {
-      "scenario": "High-Density Aggregate Dashboards",
-      "protocol": "GraphQL",
-      "justification": "Resolves under-fetching / recursive lookups"
-    },
-    {
-      "scenario": "Low-Power Mobile Data Retrieval",
-      "protocol": "GraphQL",
-      "justification": "Client strictly defines data shape"
-    },
-    {
-      "scenario": "Standard CRUD",
-      "protocol": "REST",
-      "justification": "Predictable cacheability, native HTTP semantics"
-    }
-  ],
-  "references": [
-    "reference/architecture/adrs/core/0032-api-protocol-decision-matrix-rest-grpc-graphql.md",
-    "reference/architecture/adrs/nodejs/0027-dual-protocol-rest-grpc-api-gateway.md",
-    "reference/architecture/adrs/core/0030-two-tier-distributed-gateway-model.md"
-  ],
-  "exitCriteria": {
-    "description": "All inter-service communication uses correct protocol per matrix. Contracts centralized and versioned.",
-    "validationTools": [
-      "gRPC",
-      "OpenAPI",
-      "Pact",
-      "network traffic analysis"
-    ]
-  }
-}