# shared-contract — skeleton-wide operational contract

## Registered identity

- Module ID: `shared-contract`
- Gradle path: `:shared-contract`
- Focused test: `./gradlew :shared-contract:test --console=plain`
- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
- Registry SSOT: `.harness/project/modules.yaml`.

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`).
- 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).

## 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).

## Test
```bash
cd src
./gradlew :shared-contract:test
```