diff --git a/docs/adr/0010-runtime-content-composition-over-new-umbrella-schema.md b/docs/adr/0010-runtime-content-composition-over-new-umbrella-schema.md new file mode 100644 index 0000000..ff17c27 --- /dev/null +++ b/docs/adr/0010-runtime-content-composition-over-new-umbrella-schema.md @@ -0,0 +1,61 @@ +# ADR-0010: runtime/content composition over a new umbrella schema + +Date: 2026-04-24 +Status: Proposed + +## Context + +Recent architecture work across the workspace introduced useful language around phase-relative orchestration, governed execution posture, content-addressed curation, and deployment envelopes. + +However, the SourceOS typed-contract layer already contains most of the primitives needed to express that model: + +- `WorkloadSpec` +- `DataSphere` +- `ExecutionSurface` +- `ExecutionDecision` +- `RunRecord` +- `ContentRef` +- control-plane tranche wrappers for isolation/release posture where required + +Creating a new umbrella schema that re-declares those fields would introduce a rival constitutional surface, increase duplication, and make it harder for downstream repos to know which type family is canonical. + +## Decision + +For runtime/content/orchestration alignment, this repository will prefer **composition from existing schema families** over creating a new top-level umbrella schema. + +The rule is: + +1. First express the concern using existing typed contracts and references. +2. If a true gap remains, add the smallest additive schema necessary. +3. Any additive schema must reference existing types rather than re-declaring their fields. +4. Vendor-specific names such as OpenShift, Giant Swarm, Docker, Podman, or Kubernetes should remain realization/adaptation concerns unless a generic contract cannot express the required semantics. + +### Composition guidance + +- Runnable unit identity and entrypoint → `WorkloadSpec` +- Execution boundary / trust posture → `DataSphere` and `ExecutionSurface` +- Allow/deny/ask/defer/rewrite control → `ExecutionDecision` +- Run/evidence linkage → `RunRecord` +- Content-addressed input/output references → `ContentRef` +- Release/isolation control-plane posture → control-plane tranche wrappers where appropriate + +## Consequences + +### Positive + +- Preserves a single canonical contract layer. +- Keeps downstream repos aligned on existing `schemas.srcos.ai/v2/...` identities. +- Avoids needless field duplication and version drift. +- Keeps orchestrator/vendor names out of the stable schema identity unless truly necessary. + +### Negative + +- Some higher-level concepts may be less immediately convenient to describe in one document. +- Composition may require better guidance notes or examples for downstream implementers. +- If a real gap exists, we still need disciplined additive work rather than pretending composition solves everything. + +## References + +- Issue: #51 +- Workspace placement anchor: SocioProphet/sociosphere#158 +- Workspace codification PR: SocioProphet/sociosphere#159 diff --git a/docs/adr/README.md b/docs/adr/README.md index 66f6fde..d2afdcb 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -24,3 +24,4 @@ This directory contains Architecture Decision Records for the SourceOS/SociOS ty - `ADR-0007-local-first-control-node-and-image-promotion-seam.md` - `ADR-0008-local-first-release-and-enrollment-contract-family.md` - `0009-truth-surfaces-b11-delta.md` +- `0010-runtime-content-composition-over-new-umbrella-schema.md`