From fbb6869b68f96b8eef74544e971512f4170afc05 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Sat, 25 Apr 2026 11:18:45 -0400
Subject: [PATCH 1/2] docs(spec): add ADR for CompressionEvaluation placement

---
 .../0010-compression-evaluation-placement.md  | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/adr/0010-compression-evaluation-placement.md

diff --git a/docs/adr/0010-compression-evaluation-placement.md b/docs/adr/0010-compression-evaluation-placement.md
new file mode 100644
index 0000000..bb452b5
--- /dev/null
+++ b/docs/adr/0010-compression-evaluation-placement.md
@@ -0,0 +1,85 @@
+# ADR-0010 — CompressionEvaluation placement
+
+**Date:** 2026-04-25  
+**Status:** Proposed
+
+## Context
+
+Compression Commons has been seeded upstream in `SocioProphet/sourceos-workspace` as a planning/freeze artifact, but the live placement guidance now distinguishes four lanes:
+
+- `sourceos-workspace` for planning and sequencing
+- `sourceos-spec` for typed contract canon
+- `source-os` for Linux realization
+- `socios` for later opt-in commons handoff
+
+The next contract decision is where Compression Commons belongs as a machine-readable object and how much of it should be modeled as new schema versus composition over existing governance, execution, provenance, and reference types.
+
+The current `sourceos-spec` surface already contains adjacent objects:
+- `PolicyDecision`
+- `RunRecord`
+- `ProvenanceRecord`
+- `ExecutionDecision`
+- `SessionReceipt`
+- `TruthSurface`
+- `DeltaSurface`
+- `ContentRef`
+- `DataRef`
+
+## Decision
+
+Introduce Compression Commons into `sourceos-spec` as one new top-level metadata-plane contract:
+
+- `CompressionEvaluation`
+
+Place it under the existing Execution / Provenance family rather than creating a new family in the first cut.
+
+`CompressionEvaluation` should reuse existing neighboring objects rather than cloning them:
+- `PolicyDecision` for allow/deny/obligations
+- `RunRecord` for evaluator execution audit
+- `ProvenanceRecord` for lineage
+- `ContentRef` for digest-first artifact or baseline handles
+- `DataRef` for dataset/asset/stream/file references
+
+The first API surface should be a base metadata-plane action endpoint in `openapi.yaml`:
+
+- `POST /v2/compression-evaluations/evaluate`
+
+The first cut should not add:
+- a new `ArtifactRef` top-level schema
+- a new `CorpusSnapshotRef` top-level schema
+- a new `MetricVector` top-level schema
+- a new AsyncAPI channel
+- an agent-plane patch surface
+
+Semantic overlay updates are required if `CompressionEvaluation` becomes first-class.
+
+## Alternatives considered
+
+| Alternative | Reason not chosen |
+|-------------|------------------|
+| Put Compression Commons only in `sourceos-workspace` | Correct for planning/freeze, wrong for canonical machine-readable contracts |
+| Start in `sourceos-sdk` first | Premature; SDK should consume the canon, not define it |
+| Put Compression Commons in the agent-plane patch first | Too narrow; evaluation is broader than agent sessions |
+| Create a whole new Compression Commons schema family immediately | Too much schema sprawl before reuse is exhausted |
+| Keep `socioprophet-agent-standards` as the machine-readable contract home | Conflicts with the active typed-contract lane in `sourceos-spec` |
+
+## Consequences
+
+Positive:
+- keeps one contract canon for machine-readable evaluation objects
+- minimizes duplication by reusing governance/provenance/reference primitives
+- keeps SDK and Linux realization work downstream of the contract decision
+- preserves a clean split between planning, contracts, runtime, and commons handoff
+
+Negative:
+- requires explicit reconciliation of older docs that still point schema ownership at other repos
+- delays SDK-facing work until the contract shape is agreed
+- may require later extraction of additional top-level schemas if reuse proves insufficient
+
+## References
+
+- `SocioProphet/sourceos-workspace`
+- `SociOS-Linux/source-os`
+- `SocioProphet/socioprophet-agent-standards`
+- `SourceOS-Linux/sourceos-spec`
+- follow-on design note: `docs/contract-additions/compression-evaluation-v0-placement.md`

From 371b6726aa2d0788d62e546eb1b3bd76d13c88a3 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Sat, 25 Apr 2026 11:19:25 -0400
Subject: [PATCH 2/2] docs(spec): add CompressionEvaluation v0 placement note

---
 .../compression-evaluation-v0-placement.md    | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/contract-additions/compression-evaluation-v0-placement.md

diff --git a/docs/contract-additions/compression-evaluation-v0-placement.md b/docs/contract-additions/compression-evaluation-v0-placement.md
new file mode 100644
index 0000000..e964ccc
--- /dev/null
+++ b/docs/contract-additions/compression-evaluation-v0-placement.md
@@ -0,0 +1,114 @@
+# CompressionEvaluation v0 placement note
+
+## Purpose
+
+This note turns the Compression Commons design assessment into an exact `sourceos-spec` landing plan.
+
+It does not add schemas. It records what the first real schema/API PR should contain.
+
+## New top-level schema
+
+Add exactly one new top-level schema in the first cut:
+
+- `schemas/CompressionEvaluation.json`
+
+Place it under the existing Execution / Provenance family in `schemas/README.md`.
+
+## Reused existing contracts
+
+CompressionEvaluation should compose existing contracts rather than duplicate them.
+
+Reuse as references:
+- `PolicyDecision`
+- `RunRecord`
+- `ProvenanceRecord`
+- `ContentRef`
+- `DataRef`
+- optional later summary refs: `TruthSurface`, `DeltaSurface`
+
+Do not introduce in the first cut:
+- `ArtifactRef` top-level schema
+- `CorpusSnapshotRef` top-level schema
+- `MetricVector` top-level schema
+- `EvidenceBundle` top-level schema
+
+## Proposed schema outline
+
+Required fields:
+- `id`
+- `type`
+- `specVersion`
+- `artifact`
+- `baseline`
+- `estimatorSet`
+- `metrics`
+- `createdAt`
+
+Recommended optional fields:
+- `purpose`
+- `policyDecisionRef`
+- `runRecordRef`
+- `provenanceRef`
+- `truthSurfaceRef`
+- `deltaSurfaceRef`
+- `integrity`
+- `notes`
+
+Recommended URN prefix:
+- `urn:srcos:compression-eval:`
+
+## Proposed REST addition
+
+Add one metadata-plane action endpoint to `openapi.yaml`:
+
+- `POST /v2/compression-evaluations/evaluate`
+
+Reason:
+- the first need is evaluate-and-persist
+- this matches the existing `POST /v2/decisions/evaluate` pattern
+- it avoids premature noun-upsert semantics for externally supplied evaluations
+
+Request shape should include:
+- `artifact`
+- `baseline`
+- `purpose`
+- `estimatorSet`
+- optional `environment`
+
+Response shape should be:
+- persisted `CompressionEvaluation`
+
+## Not in v0
+
+Do not add in the first cut:
+- `openapi.agent-plane.patch.yaml` changes
+- `asyncapi.yaml` channel additions
+
+Agent-plane integration can consume CompressionEvaluation later when an agent is the evaluator.
+AsyncAPI can be added later if evaluation becomes asynchronous or requires downstream event consumers.
+
+## Semantic overlay impact
+
+Because `CompressionEvaluation` is intended as a first-class type, the first schema PR should also update:
+- `semantic/context.jsonld`
+- `semantic/hydra.jsonld`
+
+## First real PR file list
+
+- `schemas/CompressionEvaluation.json`
+- `examples/compressionevaluation.json`
+- `schemas/README.md`
+- `ARCHITECTURE.md`
+- `openapi.yaml`
+- `semantic/context.jsonld`
+- `semantic/hydra.jsonld`
+- `CHANGELOG.md`
+- one ADR
+
+## Rationale
+
+This is the smallest additive move that keeps:
+- `sourceos-workspace` as planning/freeze
+- `sourceos-spec` as machine-readable canon
+- `source-os` as Linux realization
+- future SDK work as downstream consumer rather than contract owner