diff --git a/docs/contract-additions/sourceos-interaction-catalog.md b/docs/contract-additions/sourceos-interaction-catalog.md new file mode 100644 index 0000000..0eae0ef --- /dev/null +++ b/docs/contract-additions/sourceos-interaction-catalog.md @@ -0,0 +1,76 @@ +# SourceOS Interaction Substrate Catalog + +Status: Informational +Schema: `schemas/SourceOSInteractionEvent.json` +Example: `examples/sourceos-interaction-event.json` +Normative contract: `docs/contract-additions/sourceos-interaction-substrate.md` + +## Purpose + +This catalog entry makes the SourceOS interaction substrate discoverable for implementers who start from the contract-additions directory rather than from the schema tree. + +`SourceOSInteractionEvent` is the shared noetic/chat/task projection used by Noetica, AgentTerm, Matrix-facing operator flows, Superconscious task boundaries, AgentPlane evidence surfaces, Memory Mesh context-pack handoffs, Agent Registry grant references, and Policy Fabric decisions. + +The key architectural rule is that Noetica and AgentTerm are separate surfaces over the same interaction contract: + +- Noetica emits browser chat, model route, steering intent, provider evidence, and inline governance-trail events. +- AgentTerm ingests and renders the same event shape as a terminal / Matrix / operator governance trace. +- OpsHistory remains the local-first operational event ledger. +- Policy Fabric, Agent Registry, Memory Mesh, AgentPlane, and model-routing authorities remain outside both UI surfaces. + +## Contract objects + +| Artifact | Role | +| --- | --- | +| `schemas/SourceOSInteractionEvent.json` | Machine-readable JSON Schema for the shared interaction envelope. | +| `examples/sourceos-interaction-event.json` | Valid Noetica standalone completion example consumable by AgentTerm. | +| `tools/validate_sourceos_interaction_examples.py` | Dedicated validator for the schema/example pair. | +| `.github/workflows/sourceos-interaction-substrate.yml` | CI workflow for the interaction-substrate slice. | +| `docs/contract-additions/sourceos-interaction-substrate.md` | Normative design and authority-boundary contract. | + +## Required downstream bindings + +| Repository | Binding obligation | +| --- | --- | +| `SocioProphet/Noetica` | Emit `SourceOSInteractionEvent` for standalone and SourceOS chat lifecycle events. | +| `SourceOS-Linux/agent-term` | Ingest and render `SourceOSInteractionEvent` governance traces. | +| `SocioProphet/superconscious` | Accept or emit this shape at the task boundary without taking ownership of memory, policy, or evidence authority. | +| `SocioProphet/agentplane` | Attach run, replay, and evidence references rather than scraping surface-local state. | +| `SocioProphet/memory-mesh` | Consume bounded context-pack references rather than unbounded transcripts. | +| `SocioProphet/agent-registry` | Resolve non-human participants, grants, sessions, and revocation references. | +| `SocioProphet/policy-fabric` | Decide side effects, context release, memory writeback, bridge/export, redaction, and replay admission. | + +## Payload posture + +Interaction payloads are bounded by default. The valid payload modes are `metadata-only`, `summary`, `ref-only`, `inline-bounded`, and `redacted`. + +Implementations must not place raw secrets, credentials, unrestricted browser history, unrestricted shell output, unrestricted transcripts, or private chain-of-thought in `payload`. + +## Operational flow + +```text +Noetica standalone or SourceOS chat lifecycle + -> SourceOSInteractionEvent + -> governance trace visible in Noetica + -> OpsHistory or artifact reference + -> AgentTerm render/record/replay surface +``` + +```text +AgentTerm Matrix or terminal command + -> SourceOSInteractionEvent + -> Policy Fabric decision + -> Agent Registry grant resolution + -> Superconscious / AgentPlane task + -> governance trace visible in AgentTerm or Noetica +``` + +## Completion status + +Initial implementation status at catalog creation: + +- SourceOS spec schema/example/validator/workflow: merged. +- AgentTerm fixture ingest/render path: merged. +- Noetica emitter path: merged. + +Future work should add generated types or schema-consumption automation when the downstream repositories are ready for a shared package or codegen path. diff --git a/examples/README.md b/examples/README.md index 931e3e7..9736dfe 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,7 +6,7 @@ This directory contains one conforming JSON example payload for each top-level s ## What the examples show -The examples are designed to tell coherent end-to-end stories. The original example set catalogs, governs, transforms, and releases a personal health dataset within an agent session. Newer SourceOS examples show a SourceOS Workstation artifact flowing from content intent through overlays, build request, release manifest, evidence bundle, catalog entry, and access profile. The control-plane examples add the local-first lifecycle proof path: a `ReleaseSet` assigned to an M2 demo device, a `BootReleaseSet` for the recovery/provisioning lane, an `EnrollmentToken` authorizing one-time recovery access, and a `Fingerprint` reporting the realized post-apply state. Compression Commons examples add an artifact-versus-baseline evaluation record that references existing governance, execution, provenance, and content-reference contracts. +The examples are designed to tell coherent end-to-end stories. The original example set catalogs, governs, transforms, and releases a personal health dataset within an agent session. Newer SourceOS examples show a SourceOS Workstation artifact flowing from content intent through overlays, build request, release manifest, evidence bundle, catalog entry, and access profile. The control-plane examples add the local-first lifecycle proof path: a `ReleaseSet` assigned to an M2 demo device, a `BootReleaseSet` for the recovery/provisioning lane, an `EnrollmentToken` authorizing one-time recovery access, and a `Fingerprint` reporting the realized post-apply state. Compression Commons examples add an artifact-versus-baseline evaluation record that references existing governance, execution, provenance, and content-reference contracts. SourceOS Interaction examples add the noetic/chat/task event projection shared by Noetica and AgentTerm. Desktop/workstation examples may include bounded Mac-on-Linux polish metadata. These are contract signals only: concrete implementation authority remains in `SociOS-Linux/source-os`, and the examples do not claim full macOS parity. @@ -40,6 +40,8 @@ agent_session.json ──► execution_decision.json ──► session_recei ▼ session_review.json +sourceos-interaction-event.json ──► Noetica / AgentTerm governance trace + content_spec.json ──► overlay_bundle.json ──► build_request.json ──► release_manifest.json │ │ │ ▼ @@ -58,6 +60,16 @@ compressionevaluation.json ──► policy_decision.json / run.json / provenanc --- +## SourceOS Interaction examples + +These examples illustrate the shared noetic/chat/task interaction substrate: + +| File | Schema type | Description | +|------|------------|-------------| +| `sourceos-interaction-event.json` | SourceOSInteractionEvent | Noetica standalone provider completion event with governance trace fields consumable by AgentTerm | + +--- + ## Truth Plane examples These examples illustrate the Truth Plane contract additions: @@ -192,6 +204,7 @@ These examples illustrate the shared object family used by SourceOS artifact bui | `session_review.json` | SessionReview | Post-session learning review | | `settlement_event.json` | Optional receipt-to-settlement mapping | | `skill_manifest.json` | SkillManifest | The obfuscation skill manifest | +| `sourceos-interaction-event.json` | SourceOSInteractionEvent | Noetica standalone provider completion event with governance trace fields consumable by AgentTerm | | `telemetry_event.json` | TelemetryEvent | An informational telemetry event from the agent session | | `topic.json` | Topic | FogVault topic definition | | `topic_envelope.json` | FogVault append-only entry envelope | diff --git a/schemas/README.md b/schemas/README.md index ef7064d..60d8319 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -4,6 +4,18 @@ This directory contains the JSON Schema (draft 2020-12) files that make up the S --- +## Recent additions — SourceOS Interaction Substrate + +The SourceOS interaction substrate adds the following top-level schema: + +| File | Type | URN prefix | +|------|------|-----------| +| `SourceOSInteractionEvent.json` | SourceOSInteractionEvent | `urn:srcos:interaction-event:` | + +This type supports governed noetic/chat/task lifecycle events shared by Noetica, AgentTerm, Matrix-facing operator flows, Superconscious task boundaries, AgentPlane evidence references, Memory Mesh context-pack handoffs, Agent Registry grant references, and Policy Fabric decisions. + +--- + ## Recent additions — Release and build lifecycle The release/build lifecycle slice adds the following top-level schemas: @@ -135,6 +147,7 @@ These types support: | `SessionReview.json` | SessionReview | `urn:srcos:session-review:` | | `SettlementEvent.json` | SettlementEvent | `urn:srcos:settlement:` | | `SkillManifest.json` | SkillManifest | `urn:srcos:skill:` | +| `SourceOSInteractionEvent.json` | SourceOSInteractionEvent | `urn:srcos:interaction-event:` | | `SubjectContext.json` | SubjectContext | _(sub-object, no id)_ | | `SubjectSelector.json` | SubjectSelector | _(sub-object inside Policy scope)_ | | `TagAssignment.json` | TagAssignment | _(sub-object inside Field/GlossaryTerm)_ | @@ -242,6 +255,7 @@ These types support: | `EventEnvelope` | The universal wrapper for all AsyncAPI channel messages | | `TruthSurface` | Signed truth summary emitted by a plane (system/user/agent/witness) | | `DeltaSurface` | Signed diff between two TruthSurfaces with gate results | +| `SourceOSInteractionEvent` | Shared noetic/chat/task lifecycle event envelope for Noetica, AgentTerm, governance traces, task submission, and evidence handoff | ### Agent Plane