46 lines
2.2 KiB
Markdown
46 lines
2.2 KiB
Markdown
# shared-contract — skeleton-wide operational contract
|
|
|
|
## Registered identity
|
|
|
|
- Module ID: `shared-contract`
|
|
- Gradle path: `:shared-contract`
|
|
- Focused test (derived from Gradle path): `./gradlew :shared-contract:test --console=plain`
|
|
- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
|
|
- Registry SSOT: `src/config/architecture/modules.json`.
|
|
|
|
Package root: `dev.caskeleton.shared`.
|
|
|
|
Design decisions previously kept as code comments (error-code classification, response
|
|
envelope shape, metric cardinality bounds, tracing seam, domain-context propagation) live in
|
|
[README.md](README.md). This file stays the SSOT for module rules.
|
|
|
|
## Responsibility
|
|
- Response envelope (`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`).
|
|
- Error code contract (`error/ApiErrorCode` interface, `error/OperationalError` enum).
|
|
- Cross-cutting mapper sentinel (`error/MappingException`).
|
|
- Request value contract (`request/Patch`).
|
|
- Framework-neutral Redis operational snapshot (`health/RedisHealthSnapshotProvider`) used by
|
|
adapters and bootstrap health composition without leaking Actuator or native client types.
|
|
- Tracing contract types (`tracing/TraceParent`, `tracing/BaggageAllowlist`,
|
|
`tracing/SpanErrorRecorder`) — W3C `traceparent` value type, baggage allowlist,
|
|
and the span-error-recording seam (feature-distributed-tracing-contract; the OTel
|
|
tracer runtime is a fork-activated seam, so these stay Java-stdlib-only).
|
|
- Generic messaging envelope schema resources under `contracts/messaging/envelope/`.
|
|
They own transport-neutral envelope metadata only; feature payload schemas remain in their
|
|
feature-owner modules. Resource presence is not runtime discovery or registration.
|
|
|
|
## Allowed
|
|
- Java standard library ONLY. No Spring, no Jackson, no JPA imports.
|
|
|
|
## Forbidden
|
|
- business/domain concept (domain error codes belong in the consuming module).
|
|
- framework imports (HTTP status is expressed as transport-neutral `int`; the web module maps it).
|
|
- claiming Draft 2020-12 validator compatibility before the messaging adapter's Task 6 validator
|
|
qualification exists.
|
|
|
|
## Test
|
|
```bash
|
|
cd src
|
|
./gradlew :shared-contract:test
|
|
```
|