Skip to content

docs: reserve polycentric observer-control schema family lane #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mdheller merged 1 commit into from
Apr 9, 2026
Merged

docs: reserve polycentric observer-control schema family lane #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions docs/adr/ADR-0006-polycentric-observer-schema-family.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# ADR-0006 — Polycentric Observer-Control Schema Family

- Status: Proposed
- Date: 2026-04-09

## Context

The organization is adopting a polycentric observer-control model upstream in `SocioProphet/socioprophet-standards-storage`.

That normative doctrine introduces a canonical split between:

- entities
- interactions
- scoped state records
- observations, claims, evidence, and inferences
- actions, effects, and policy decisions
- artifacts and views
- trust labels, attestations, and flow rules
- retention and revocation semantics
- compile targets for CI/CD and NixOS ops

`SourceOS-Linux/sourceos-spec` is already the canonical machine-readable contract layer for the SourceOS metadata governance platform and the SociOS agent plane. This repository is therefore the correct downstream home for the schema family that implements that doctrine.

## Decision

Reserve this repository as the authoritative machine-readable home for the polycentric observer-control schema family.

The expected schema additions are:

- `Entity`
- `Interaction`
- `StateRecord`
- `View`
- `Observation`
- `Evidence`
- `Claim`
- `Inference`
- `Action`
- `Effect`
- `Artifact`
- `PolicyDecision`
- `ResourceAccount`
- `TrustLabel`
- `Attestation`
- `FlowRule`
- `BoundaryCrossing`
- `RetentionPolicy`
- compile-target schemas for CI/CD and NixOS ops
- machine-readable surface profiles where they belong in this contract layer

## Consequences

- Upstream normative prose and ADRs stay in `SocioProphet/socioprophet-standards-storage`.
- This repository owns the machine-readable realization: JSON Schema, examples, and semantic overlays.
- Runtime and transport repositories consume these schemas by reference and should not become the canonical schema source of truth.

## Follow-on work

1. Add the schema family under `schemas/`.
2. Add conforming examples under `examples/`.
3. Add JSON-LD / semantic overlay material under `semantic/`.
4. Wire adoption into downstream runtime repos.
5. Add conformance checks beyond structural validation where needed.
Loading