You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/architecture/adrs/0054-shell-library-isolation.es.md
+26-26Lines changed: 26 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
**Estado:** Aceptado
4
4
**Fecha:** 2026-05-15
5
-
**Enmendado:** 2026-05-24 — grafo de dependencias corregido; alcance extendido para incluir `Ums.Shell.Aop` y `Ums.Shell.Bootstrapper`
5
+
**Enmendado:** 2026-05-24 — grafo de dependencias corregido; alcance extendido para incluir `BeyondNetCode.Shell.Aop` y `BeyondNetCode.Shell.Bootstrapper`
6
6
**Responsable de Decisión:** Arquitectura
7
7
**Relacionados:**
8
8
-[ADR-0060: Estrategia de Concerns Cross-Cutting AOP](./0060-aop-cross-cutting-concern-strategy.md)
@@ -14,24 +14,24 @@
14
14
15
15
UMS incluye librerías de infraestructura reutilizables bajo `src/libs/shell`. Estas librerías se originaron de fuentes externas o de referencia, pero UMS no debe exponer namespaces upstream ni convenciones de repositorio en código de aplicación.
16
16
17
-
El ADR-0029 anterior describía "Primitivas DDD nativas de C# (sin librería externa)". Esa redacción ya no es precisa: la posición correcta es que UMS **posee su superficie de dependencia de dominio** a través de las shell libraries `Ums.Shell.*`. Las capas de aplicación consumen la abstracción shell de UMS, no la identidad fuente upstream.
17
+
El ADR-0029 anterior describía "Primitivas DDD nativas de C# (sin librería externa)". Esa redacción ya no es precisa: la posición correcta es que UMS **posee su superficie de dependencia de dominio** a través de las shell libraries `BeyondNetCode.Shell.*`. Las capas de aplicación consumen la abstracción shell de UMS, no la identidad fuente upstream.
18
18
19
19
A partir de 2026-05-24, la capa shell incluye cuatro grupos de librerías:
> **Corrección del ADR original (2026-05-15):**`Ums.Domain.csproj` previamente listaba una `<ProjectReference>` directa a `Ums.Shell.Factory`. Esto era una referencia redundante — `Ums.Shell.Ddd` ya depende de `Ums.Shell.Factory`, haciéndola disponible transitivamente. La referencia directa fue removida el 2026-05-24. El código de Domain debe acceder a abstracciones de factory solo a través de la capa shell DDD, no importando directamente el namespace de Factory.
66
+
> **Corrección del ADR original (2026-05-15):**`Ums.Domain.csproj` previamente listaba una `<ProjectReference>` directa a `BeyondNetCode.Shell.Factory`. Esto era una referencia redundante — `BeyondNetCode.Shell.Ddd` ya depende de `BeyondNetCode.Shell.Factory`, haciéndola disponible transitivamente. La referencia directa fue removida el 2026-05-24. El código de Domain debe acceder a abstracciones de factory solo a través de la capa shell DDD, no importando directamente el namespace de Factory.
67
67
68
68
### Reglas por capa
69
69
70
70
| Capa | Puede referenciar | NO puede referenciar |
|`Ums.Application`|`Ums.Domain`, `BeyondNetCode.Shell.Aspects` (contrato de atributos) |`BeyondNetCode.Shell.DispatchProxy`, `BeyondNetCode.Shell.Aop.*.Installer`, `BeyondNetCode.Shell.Factory`, `BeyondNetCode.Shell.Bootstrapper.*`|
74
74
|`Ums.Infrastructure`| Todo lo anterior + AOP installer + Bootstrapper | — |
75
75
|`Ums.Presentation`| Todas las capas + Bootstrapper para startup | — |
76
76
@@ -82,15 +82,15 @@ Ums.Domain
82
82
83
83
- UMS tiene una superficie de dependencia interna estable para patrones tácticos de DDD, Factory, AOP, y Bootstrapper.
84
84
- El código de Domain es puro de todas las preocupaciones de infraestructura — sin imports de AOP, DI, o logging.
85
-
-`Ums.Application` referencia solo el **contrato de atributo** de AOP (`Ums.Shell.Aop.Aspects`) — los handlers declaran intención cross-cutting vía atributos sin acoplamiento a la infraestructura de proxy.
85
+
-`Ums.Application` referencia solo el **contrato de atributo** de AOP (`BeyondNetCode.Shell.Aspects`) — los handlers declaran intención cross-cutting vía atributos sin acoplamiento a la infraestructura de proxy.
86
86
- Cambios de fuente upstream pueden ser absorbidos dentro de `src/libs/shell` sin tocar las capas de aplicación.
87
87
- El patrón `IMelLogger` (interfaz marker en Application, adapter concreto en Infrastructure) demuestra cómo aplicar el mismo principio de aislamiento a adapters cross-cutting.
88
88
89
89
### Trade-offs
90
90
91
91
- La capa shell es una dependencia arquitectónica real y debe ser versionada y revisada correspondientemente.
92
92
- Alertas de seguridad y warnings de paquetes de dependencias shell (ej., CVE de `OpenTelemetry.Api` en Bootstrapper) afectan la salud del build de UMS.
93
-
-`Ums.Shell.Ddd` depende de `Ums.Shell.Factory` — este acoplamiento es intencional (la construcción DDD puede usar abstracciones de factory internamente) pero significa que agregar una dependencia de Factory a Domain es suficiente para arrastrar Factory a todas partes donde Domain es referenciado.
93
+
-`BeyondNetCode.Shell.Ddd` depende de `BeyondNetCode.Shell.Factory` — este acoplamiento es intencional (la construcción DDD puede usar abstracciones de factory internamente) pero significa que agregar una dependencia de Factory a Domain es suficiente para arrastrar Factory a todas partes donde Domain es referenciado.
94
94
95
95
---
96
96
@@ -103,15 +103,15 @@ Las siguientes verificaciones son obligatorias después de cualquier cambio en l
103
103
dotnet build src/apps/ums.api/Ums.sln
104
104
105
105
# 2. Ejecutar todos los test suites de shell libraries
106
-
dotnet test src/libs/shell/aop/src/Ums.Shell.Aop.Tests/Ums.Shell.Aop.Tests.csproj --verbosity minimal
107
-
dotnet test src/libs/shell/factory/src/Ums.Shell.Factory.Test/Ums.Shell.Factory.Test.csproj --verbosity minimal
106
+
dotnet test src/libs/shell/aop/src/BeyondNetCode.Shell.Aop.Tests/BeyondNetCode.Shell.Aop.Tests.csproj --verbosity minimal
107
+
dotnet test src/libs/shell/factory/src/BeyondNetCode.Shell.Factory.Test/BeyondNetCode.Shell.Factory.Test.csproj --verbosity minimal
108
108
109
109
# 3. Verificar pureza del Domain (sin refs AOP en Domain)
UMS includes reusable infrastructure libraries under `src/libs/shell`. These libraries originated from external or reference sources, but UMS must not expose upstream namespaces or repository conventions in application code.
16
16
17
-
The previous ADR-0029 described "C# Native DDD Primitives (no external library)". That wording is no longer precise: the correct position is that UMS **owns its domain dependency surface** through `Ums.Shell.*` shell libraries. Application layers consume the UMS shell abstraction, not the upstream source identity.
17
+
The previous ADR-0029 described "C# Native DDD Primitives (no external library)". That wording is no longer precise: the correct position is that UMS **owns its domain dependency surface** through `BeyondNetCode.Shell.*` shell libraries. Application layers consume the UMS shell abstraction, not the upstream source identity.
18
18
19
19
As of 2026-05-24, the shell layer includes four library groups:
└── BeyondNetCode.Shell.Logger.Serilog (transitive via installer)
54
54
55
55
Ums.Application
56
56
├── Ums.Domain
57
-
└── Ums.Shell.Aop.Aspects ← attribute contract only (no DI, no runtime proxy)
57
+
└── BeyondNetCode.Shell.Aspects ← attribute contract only (no DI, no runtime proxy)
58
58
59
59
Ums.Domain
60
-
├── Ums.Shell.Ddd
61
-
│ └── Ums.Shell.Factory (transitive via Ddd)
62
-
└── Ums.Shell.Ddd.ValueObjects
63
-
└── Ums.Shell.Ddd (transitive)
60
+
├── BeyondNetCode.Shell.Ddd
61
+
│ └── BeyondNetCode.Shell.Factory (transitive via Ddd)
62
+
└── BeyondNetCode.Shell.Ddd.ValueObjects
63
+
└── BeyondNetCode.Shell.Ddd (transitive)
64
64
```
65
65
66
-
> **Correction from original ADR (2026-05-15):**`Ums.Domain.csproj` previously listed a direct `<ProjectReference>` to `Ums.Shell.Factory`. This was a redundant reference — `Ums.Shell.Ddd` already depends on `Ums.Shell.Factory`, making it available transitively. The direct reference was removed on 2026-05-24. Domain code must access factory abstractions only through the DDD shell layer, not by directly importing the Factory namespace.
66
+
> **Correction from original ADR (2026-05-15):**`Ums.Domain.csproj` previously listed a direct `<ProjectReference>` to `BeyondNetCode.Shell.Factory`. This was a redundant reference — `BeyondNetCode.Shell.Ddd` already depends on `BeyondNetCode.Shell.Factory`, making it available transitively. The direct reference was removed on 2026-05-24. Domain code must access factory abstractions only through the DDD shell layer, not by directly importing the Factory namespace.
67
67
68
68
### Rules per layer
69
69
70
70
| Layer | May reference | May NOT reference |
71
71
|---|---|---|
72
-
|`Ums.Domain`|`Ums.Shell.Ddd`, `Ums.Shell.Ddd.ValueObjects`| Any `Ums.Shell.Aop.*`, `Ums.Shell.Factory` (direct), `Ums.Shell.Bootstrapper.*`|
|`Ums.Infrastructure`| All of the above + AOP installer + Bootstrapper | — |
75
75
|`Ums.Presentation`| All layers + Bootstrapper for startup | — |
76
76
@@ -82,15 +82,15 @@ Ums.Domain
82
82
83
83
- UMS has a stable internal dependency surface for tactical DDD, Factory, AOP, and Bootstrapper patterns.
84
84
- Domain code is pure of all infrastructure concerns — no AOP, no DI, no logging imports.
85
-
-`Ums.Application` references only the AOP **attribute contract** (`Ums.Shell.Aop.Aspects`) — handlers declare cross-cutting intent via attributes without coupling to the proxy infrastructure.
85
+
-`Ums.Application` references only the AOP **attribute contract** (`BeyondNetCode.Shell.Aspects`) — handlers declare cross-cutting intent via attributes without coupling to the proxy infrastructure.
86
86
- Upstream source changes can be absorbed inside `src/libs/shell` without touching application layers.
87
87
- The `IMelLogger` pattern (marker interface in Application, concrete adapter in Infrastructure) demonstrates how to apply the same isolation principle to cross-cutting adapters.
88
88
89
89
### Trade-offs
90
90
91
91
- The shell layer is a real architectural dependency and must be versioned and reviewed accordingly.
92
92
- Security and package warnings from shell dependencies (e.g., `OpenTelemetry.Api` CVE in Bootstrapper) affect the UMS build health.
93
-
-`Ums.Shell.Ddd` depends on `Ums.Shell.Factory` — this coupling is intentional (DDD construction can use factory abstractions internally) but means that adding a Factory dependency to Domain is sufficient to pull in Factory everywhere Domain is referenced.
93
+
-`BeyondNetCode.Shell.Ddd` depends on `BeyondNetCode.Shell.Factory` — this coupling is intentional (DDD construction can use factory abstractions internally) but means that adding a Factory dependency to Domain is sufficient to pull in Factory everywhere Domain is referenced.
94
94
95
95
---
96
96
@@ -103,15 +103,15 @@ The following checks are mandatory after any change to the shell library referen
103
103
dotnet build src/apps/ums.api/Ums.sln
104
104
105
105
# 2. Run all shell library test suites
106
-
dotnet test src/libs/shell/aop/src/Ums.Shell.Aop.Tests/Ums.Shell.Aop.Tests.csproj --verbosity minimal
107
-
dotnet test src/libs/shell/factory/src/Ums.Shell.Factory.Test/Ums.Shell.Factory.Test.csproj --verbosity minimal
106
+
dotnet test src/libs/shell/aop/src/BeyondNetCode.Shell.Aop.Tests/BeyondNetCode.Shell.Aop.Tests.csproj --verbosity minimal
107
+
dotnet test src/libs/shell/factory/src/BeyondNetCode.Shell.Factory.Test/BeyondNetCode.Shell.Factory.Test.csproj --verbosity minimal
0 commit comments