|
| 1 | +# ADR 0001 — Agentic Mesh Access and Workspace Contract Expansion |
| 2 | + |
| 3 | +**Date:** 2026-04-14 |
| 4 | +**Status:** `Proposed` |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +## Context |
| 9 | + |
| 10 | +`SourceOS-Linux/sourceos-spec` already defines the canonical machine-readable contract layer for SourceOS/SociOS with a two-plane model: a metadata plane and an agent plane. The current agent-plane family already includes session, execution-decision, execution-surface, skill, memory, receipt, telemetry, and review objects. |
| 11 | + |
| 12 | +That is necessary but no longer sufficient for the operating model now being aligned across SourceOS, agentplane, CloudShell/fog execution, Nocalhost-style remote development, and the broader SocioProphet standards stack. |
| 13 | + |
| 14 | +The missing contract families are the ones required to model: |
| 15 | + |
| 16 | +- local-first but globally reachable mesh routing |
| 17 | +- governed operator remote shell access |
| 18 | +- governed HTTP/service tunnel access |
| 19 | +- developer workspaces and sync relationships |
| 20 | +- approval, delegation, and break-glass posture |
| 21 | +- proof-bearing evidence bundles and replay/export surfaces |
| 22 | +- Git-backed desired-state and boot/recovery lifecycle artifacts |
| 23 | +- placement decisions across local workstation, private cluster, fog, and optional burst cloud |
| 24 | +- world-model claims, conflicts, and reconciliation outcomes emitted from operational activity |
| 25 | + |
| 26 | +If these objects are left in runtime repos or prose-only standards repos, the contract authority will fragment. If they are forced into transport repositories, protocol concerns and product-surface semantics will be conflated. If they are placed in legacy distro/UI repositories, SourceOS loses a clean machine-readable spine. |
| 27 | + |
| 28 | +--- |
| 29 | + |
| 30 | +## Decision |
| 31 | + |
| 32 | +`SourceOS-Linux/sourceos-spec` remains the canonical owner for the machine-readable contract layer of the SourceOS/SociOS agentic mesh operating model. |
| 33 | + |
| 34 | +The repository should add the following new first-class object families, in phased additive work: |
| 35 | + |
| 36 | +### Access / route / session family |
| 37 | + |
| 38 | +- `MeshRoute` |
| 39 | +- `RemoteSession` |
| 40 | +- `SessionRecording` |
| 41 | +- `TunnelLease` |
| 42 | +- `ApprovalRequest` |
| 43 | +- `DelegationGrant` |
| 44 | + |
| 45 | +### Workspace / developer execution family |
| 46 | + |
| 47 | +- `DevSpace` |
| 48 | +- `DevSync` |
| 49 | + |
| 50 | +### Evidence / lifecycle / placement family |
| 51 | + |
| 52 | +- `EvidenceBundle` |
| 53 | +- `ProofPack` |
| 54 | +- `ConfigSource` |
| 55 | +- `ReleaseSet` |
| 56 | +- `BootReleaseSet` |
| 57 | +- `PlacementDecision` |
| 58 | + |
| 59 | +### Knowledge reconciliation family |
| 60 | + |
| 61 | +- `WorldStateClaim` |
| 62 | +- `ConflictSet` |
| 63 | +- `ReconciliationDecision` |
| 64 | + |
| 65 | +These object families should be treated as additive extensions of the existing two-plane model rather than as a separate third specification. They should be published through the same core surfaces this repository already owns: |
| 66 | + |
| 67 | +- JSON Schemas in `schemas/` |
| 68 | +- OpenAPI base or agent-plane patch fragments, as appropriate |
| 69 | +- AsyncAPI base or agent-plane patch fragments, as appropriate |
| 70 | +- semantic context updates for first-class types |
| 71 | +- example payloads and cross-object URN references |
| 72 | + |
| 73 | +The repository boundary is explicit: |
| 74 | + |
| 75 | +- `SourceOS-Linux/sourceos-spec` owns machine-readable object definitions and API/event contracts. |
| 76 | +- `SocioProphet/socioprophet-agent-standards` owns normative profile, conformance, and behavioral standards. |
| 77 | +- `SocioProphet/prophet-platform-standards` owns deployment, GitOps, RBAC, observability, and platform implementation standards. |
| 78 | +- `SocioProphet/socioprophet-standards-storage` owns event/storage/measurement/compliance standards for these artifacts. |
| 79 | +- `SocioProphet/socioprophet-standards-knowledge` owns knowledge/provenance/reconciliation semantics above the base contract layer. |
| 80 | +- `SocioProphet/agentplane` owns runtime execution, placement, run, evidence-emission, and replay implementation. |
| 81 | +- `SocioProphet/sociosphere` owns workspace manifest/lock/orchestration concerns, not downstream feature semantics. |
| 82 | +- `SocioProphet/TriTRPC` owns transport and fixture semantics, not product-surface object ownership. |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +## Alternatives considered |
| 87 | + |
| 88 | +| Alternative | Reason not chosen | |
| 89 | +|-------------|------------------| |
| 90 | +| Put the new object families directly into runtime repositories such as `agentplane` or `cloudshell-fog` | Rejected because runtime repos would become de facto schema authorities, causing duplicated contracts and drift. | |
| 91 | +| Put the new object families only in standards/prose repositories | Rejected because the SourceOS operating model needs machine-readable contracts, not prose-only declarations. | |
| 92 | +| Treat the new access/workspace model as a transport concern owned by `TriTRPC` | Rejected because transport and routing frames are not the same thing as operator sessions, tunnel leases, workspaces, or proof bundles. | |
| 93 | +| Place the work in `SociOS-Linux` | Rejected because the current `SociOS-Linux` inventory is not the canonical SourceOS contract/spec spine. | |
| 94 | +| Create a separate contract repository just for mesh access and workspaces | Rejected because that would fragment the existing two-plane contract authority and force downstream repos to stitch multiple specification roots together. | |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Consequences |
| 99 | + |
| 100 | +### Positive |
| 101 | + |
| 102 | +- SourceOS keeps a single machine-readable contract authority. |
| 103 | +- Operator access, developer workspaces, release/boot artifacts, and knowledge reconciliation can all reference the same URN and API/event conventions. |
| 104 | +- Downstream runtime and standards repos can consume a stable contract family instead of redefining object shapes. |
| 105 | +- The local-first / fog / cloud placement story becomes part of the spec rather than an implementation accident. |
| 106 | + |
| 107 | +### Negative |
| 108 | + |
| 109 | +- The repository scope broadens and will require careful staging to avoid an oversized one-shot schema drop. |
| 110 | +- Several downstream repos will need follow-on updates once the first object families land. |
| 111 | +- The distinction between metadata-plane and agent-plane ownership must stay explicit so the contract layer does not become a dumping ground. |
| 112 | + |
| 113 | +### Required follow-on |
| 114 | + |
| 115 | +The next changes should be phased: |
| 116 | + |
| 117 | +1. add the access / route / session family |
| 118 | +2. add workspace objects and sync posture |
| 119 | +3. add evidence / release / boot / placement objects |
| 120 | +4. add reconciliation objects and semantic overlay links |
| 121 | +5. update downstream standards and runtime repos to consume the canonical objects |
| 122 | + |
| 123 | +--- |
| 124 | + |
| 125 | +## References |
| 126 | + |
| 127 | +- `SourceOS-Linux/sourceos-spec` |
| 128 | +- `SocioProphet/socioprophet-agent-standards` |
| 129 | +- `SocioProphet/prophet-platform-standards` |
| 130 | +- `SocioProphet/socioprophet-standards-storage` |
| 131 | +- `SocioProphet/socioprophet-standards-knowledge` |
| 132 | +- `SocioProphet/agentplane` |
| 133 | +- `SocioProphet/sociosphere` |
| 134 | +- `SocioProphet/TriTRPC` |
0 commit comments