From 39a52bbb080abf9bf22d85b95dbd0ab8bf0192e4 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 22 May 2026 15:24:54 -0400 Subject: [PATCH 1/5] Add SourceOS interaction event schema --- schemas/SourceOSInteractionEvent.json | 507 ++++++++++++++++++++++++++ 1 file changed, 507 insertions(+) create mode 100644 schemas/SourceOSInteractionEvent.json diff --git a/schemas/SourceOSInteractionEvent.json b/schemas/SourceOSInteractionEvent.json new file mode 100644 index 0000000..ed77382 --- /dev/null +++ b/schemas/SourceOSInteractionEvent.json @@ -0,0 +1,507 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SourceOSInteractionEvent.json", + "title": "SourceOSInteractionEvent", + "description": "Shared noetic interaction event envelope for governed chat, terminal, Matrix, and web surfaces that submit tasks, stream results, display governance traces, and hand off evidence across SourceOS.", + "type": "object", + "additionalProperties": false, + "required": [ + "interactionEventId", + "type", + "specVersion", + "eventClass", + "occurredAt", + "surface", + "mode", + "session", + "actor", + "payloadMode", + "governanceTrace" + ], + "properties": { + "interactionEventId": { + "type": "string", + "pattern": "^urn:srcos:interaction-event:", + "description": "Stable URN identifier for this interaction event. Pattern: urn:srcos:interaction-event:" + }, + "type": { + "const": "SourceOSInteractionEvent", + "description": "Discriminator constant. Always SourceOSInteractionEvent." + }, + "specVersion": { + "type": "string", + "description": "SourceOS spec version for this event shape." + }, + "eventClass": { + "type": "string", + "enum": [ + "interaction.session_started", + "interaction.message_posted", + "interaction.task_submitted", + "interaction.task_stream_delta", + "interaction.task_completed", + "interaction.task_failed", + "interaction.governance_trace", + "interaction.steering_intent", + "interaction.memory_scope_bound", + "interaction.context_pack_bound", + "interaction.policy_decision", + "interaction.approval_requested", + "interaction.approval_recorded", + "interaction.redacted" + ], + "description": "Class of noetic interaction event emitted by a surface or authority plane." + }, + "occurredAt": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 date-time when this interaction event occurred." + }, + "surface": { + "type": "object", + "additionalProperties": false, + "description": "Surface or authority plane that emitted the event.", + "required": [ + "surfaceKind", + "sourcePlane" + ], + "properties": { + "surfaceKind": { + "type": "string", + "enum": [ + "noetica", + "agent-term", + "matrix", + "prophet-workspace", + "superconscious", + "agentplane", + "api", + "other" + ], + "description": "Surface family or authority-plane family that produced this event." + }, + "sourcePlane": { + "type": "string", + "description": "Concrete emitting plane or repository identifier such as SocioProphet/Noetica or SourceOS-Linux/agent-term." + }, + "clientRef": { + "type": [ + "string", + "null" + ], + "description": "Optional client, device, workspace, or UI instance reference." + } + } + }, + "mode": { + "type": "string", + "enum": [ + "standalone", + "sourceos", + "dry-run", + "replay" + ], + "description": "Execution/routing mode used by the surface." + }, + "session": { + "type": "object", + "additionalProperties": false, + "description": "Stable conversation and workroom scope binding for the interaction.", + "required": [ + "sessionId" + ], + "properties": { + "sessionId": { + "type": "string", + "description": "Surface-local or SourceOS-global session identifier." + }, + "conversationRef": { + "type": [ + "string", + "null" + ], + "description": "Conversation, chat, or transcript reference." + }, + "roomRef": { + "type": [ + "string", + "null" + ], + "description": "Matrix room, channel, or workroom room reference." + }, + "threadRef": { + "type": [ + "string", + "null" + ], + "description": "Thread root or work-order reference." + }, + "workroomRef": { + "type": [ + "string", + "null" + ], + "description": "Prophet Workspace or Professional Workroom reference." + }, + "topicRef": { + "type": [ + "string", + "null" + ], + "description": "Slash Topics or New Hope topic/membrane scope reference." + }, + "opsHistoryEventRef": { + "type": [ + "string", + "null" + ], + "pattern": "^urn:srcos:ops-history-event:|^$", + "description": "Optional OpsHistory event reference when this interaction is durably recorded." + } + } + }, + "actor": { + "type": "object", + "additionalProperties": false, + "description": "Human, agent, bot, service, or system actor responsible for emitting or initiating the event.", + "required": [ + "actorRef", + "actorKind" + ], + "properties": { + "actorRef": { + "type": "string", + "description": "Actor authority reference. Human subjects may use subject URNs; non-human actors must resolve through Agent Registry when enabled." + }, + "actorKind": { + "type": "string", + "enum": [ + "human", + "agent", + "service", + "bot", + "system" + ], + "description": "Actor class." + }, + "agentRegistryRef": { + "type": [ + "string", + "null" + ], + "description": "Agent Registry identity/session/grant reference for non-human actors." + }, + "onBehalfOfRef": { + "type": [ + "string", + "null" + ], + "description": "Optional subject, workroom, or service reference on whose behalf the actor operated." + } + } + }, + "participants": { + "type": "array", + "description": "Participants visible in the interaction. This is descriptive only and does not grant authority.", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "role", + "participantRef" + ], + "properties": { + "role": { + "type": "string", + "enum": [ + "user", + "assistant", + "operator", + "agent", + "provider", + "tool", + "observer" + ], + "description": "Participant role in the interaction." + }, + "participantRef": { + "type": "string", + "description": "Stable participant reference." + }, + "agentRegistryRef": { + "type": [ + "string", + "null" + ], + "description": "Optional Agent Registry reference for agent-like participants." + } + } + }, + "default": [] + }, + "task": { + "type": [ + "object", + "null" + ], + "additionalProperties": false, + "description": "Optional task/request/result projection for model calls, Superconscious submissions, or AgentPlane-mediated runs.", + "properties": { + "taskRef": { + "type": [ + "string", + "null" + ], + "description": "Task, run, or request reference." + }, + "status": { + "type": "string", + "enum": [ + "submitted", + "streaming", + "success", + "failure", + "blocked", + "unavailable", + "not_configured" + ], + "description": "Task status as visible to the surface." + }, + "modelHint": { + "type": [ + "string", + "null" + ], + "description": "Model requested by the surface, before authoritative routing." + }, + "modelRouted": { + "type": [ + "string", + "null" + ], + "description": "Model selected by the authoritative model router or standalone provider path." + }, + "provider": { + "type": [ + "string", + "null" + ], + "description": "Provider or authority plane serving the task." + }, + "latencyMs": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "description": "Observed latency in milliseconds, when available." + } + } + }, + "steeringIntent": { + "type": [ + "object", + "null" + ], + "additionalProperties": false, + "description": "Optional steering intent. Blackbox prompting must not be represented as mechanistic SAE steering.", + "properties": { + "steeringKind": { + "type": "string", + "enum": [ + "none", + "neuronpedia_feature", + "local_sae", + "sourceos_local", + "other" + ], + "description": "Steering mechanism class." + }, + "featureRef": { + "type": [ + "string", + "null" + ], + "description": "Feature, layer, or steering primitive reference." + }, + "strength": { + "type": [ + "number", + "null" + ], + "description": "Requested steering strength, if applicable." + }, + "status": { + "type": "string", + "enum": [ + "requested", + "applied", + "noop", + "not_configured", + "blocked" + ], + "description": "Steering execution status." + } + } + }, + "governanceTrace": { + "type": "object", + "additionalProperties": false, + "description": "User-visible governance trail carried across web, terminal, Matrix, and authority-plane surfaces.", + "required": [ + "policyAdmitted", + "memoryWritten" + ], + "properties": { + "policyAdmitted": { + "type": "boolean", + "description": "Whether policy admitted the visible operation." + }, + "policyRef": { + "type": [ + "string", + "null" + ], + "description": "Primary policy reference or denial reference." + }, + "policyDecisionRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Policy Fabric decision references authorizing routing, context release, memory, side effects, export, or redaction.", + "default": [] + }, + "grantRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Tool/capability grant references requested or resolved through Agent Registry.", + "default": [] + }, + "memoryScopeRef": { + "type": [ + "string", + "null" + ], + "description": "Memory Mesh scope reference, if any." + }, + "memoryWritten": { + "type": "boolean", + "description": "Whether durable memory writeback occurred." + }, + "contextPackRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Context-pack references exchanged with Memory Mesh or AgentPlane.", + "default": [] + }, + "requestHash": { + "type": [ + "string", + "null" + ], + "description": "Hash of request envelope or prompt-relevant bounded payload." + }, + "evidenceHash": { + "type": [ + "string", + "null" + ], + "description": "Hash of result/evidence envelope." + }, + "providerRouteEvidenceRef": { + "type": [ + "string", + "null" + ], + "description": "Provider-route evidence reference for standalone or routed model calls." + }, + "agentPlaneRunRef": { + "type": [ + "string", + "null" + ], + "description": "AgentPlane run reference, if execution authority was involved." + }, + "evidenceRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Evidence artifact references.", + "default": [] + }, + "replayRef": { + "type": [ + "string", + "null" + ], + "description": "Replay artifact or replay-plan reference." + } + } + }, + "payloadMode": { + "type": "string", + "enum": [ + "metadata-only", + "summary", + "ref-only", + "inline-bounded", + "redacted" + ], + "description": "Payload disclosure posture. Raw sensitive payloads are denied by default." + }, + "payload": { + "type": [ + "object", + "null" + ], + "additionalProperties": true, + "description": "Optional bounded payload. Must not contain raw secrets, credentials, unrestricted browser history, unrestricted shell output, or private chain-of-thought." + }, + "sourceEventRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Upstream source event references from OpsHistory, Matrix, Noetica, AgentTerm, Superconscious, AgentPlane, or provider paths.", + "default": [] + }, + "redactionRefs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Redaction tombstone references that affect this interaction.", + "default": [] + }, + "integrity": { + "type": [ + "object", + "null" + ], + "additionalProperties": false, + "description": "Optional integrity envelope for this event.", + "properties": { + "eventHash": { + "type": [ + "string", + "null" + ], + "description": "Hash of canonicalized event content." + }, + "signature": { + "type": [ + "string", + "null" + ], + "description": "Cryptographic signature over canonicalized event content, when present." + } + } + } + } +} From a31c68df2b931d95289ff509db5b89b82dc9db92 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 22 May 2026 16:01:36 -0400 Subject: [PATCH 2/5] Add SourceOS interaction example --- examples/sourceos-interaction-event.json | 97 ++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 examples/sourceos-interaction-event.json diff --git a/examples/sourceos-interaction-event.json b/examples/sourceos-interaction-event.json new file mode 100644 index 0000000..661b728 --- /dev/null +++ b/examples/sourceos-interaction-event.json @@ -0,0 +1,97 @@ +{ + "interactionEventId": "urn:srcos:interaction-event:noetica-standalone-complete-0001", + "type": "SourceOSInteractionEvent", + "specVersion": "2.0.0", + "eventClass": "interaction.task_completed", + "occurredAt": "2026-05-22T16:20:00Z", + "surface": { + "surfaceKind": "noetica", + "sourcePlane": "SocioProphet/Noetica", + "clientRef": "web:noetica:local-demo" + }, + "mode": "standalone", + "session": { + "sessionId": "noetica-session-local", + "conversationRef": "urn:srcos:conversation:noetica-local-demo", + "roomRef": null, + "threadRef": "urn:srcos:thread:noetica-local-demo", + "workroomRef": "urn:srcos:workroom:professional-intelligence-demo", + "topicRef": "urn:srcos:topic:professional-intelligence", + "opsHistoryEventRef": "urn:srcos:ops-history-event:noetica-local-demo-0001" + }, + "actor": { + "actorRef": "urn:srcos:subject:user:operator", + "actorKind": "human", + "agentRegistryRef": null, + "onBehalfOfRef": "urn:srcos:workroom:professional-intelligence-demo" + }, + "participants": [ + { + "role": "user", + "participantRef": "urn:srcos:subject:user:operator", + "agentRegistryRef": null + }, + { + "role": "assistant", + "participantRef": "urn:srcos:agent:noetica", + "agentRegistryRef": "urn:srcos:agent-registry:noetica" + }, + { + "role": "provider", + "participantRef": "provider:openai", + "agentRegistryRef": null + } + ], + "task": { + "taskRef": "urn:srcos:task:noetica-standalone-0001", + "status": "success", + "modelHint": "gpt-4.1", + "modelRouted": "gpt-4.1", + "provider": "openai", + "latencyMs": 842 + }, + "steeringIntent": { + "steeringKind": "none", + "featureRef": null, + "strength": null, + "status": "noop" + }, + "governanceTrace": { + "policyAdmitted": true, + "policyRef": "noetica://standalone/local-policy", + "policyDecisionRefs": [ + "urn:srcos:decision:noetica-standalone-admit-0001" + ], + "grantRefs": [ + "call:openai" + ], + "memoryScopeRef": "noetica-session-local", + "memoryWritten": false, + "contextPackRefs": [], + "requestHash": "sha256:1111111111111111111111111111111111111111111111111111111111111111", + "evidenceHash": "sha256:2222222222222222222222222222222222222222222222222222222222222222", + "providerRouteEvidenceRef": "urn:srcos:evidence:provider-route:noetica-standalone-0001", + "agentPlaneRunRef": null, + "evidenceRefs": [ + "urn:srcos:evidence:noetica-standalone-0001" + ], + "replayRef": "urn:srcos:replay:noetica-standalone-0001" + }, + "payloadMode": "summary", + "payload": { + "summary": "Noetica completed a standalone provider call and emitted a governance trace consumable by AgentTerm.", + "egress": { + "contactedExternalProvider": true, + "sentPrompt": true, + "promptEgressDefault": "external-provider" + } + }, + "sourceEventRefs": [ + "urn:srcos:ops-history-event:noetica-local-demo-0001" + ], + "redactionRefs": [], + "integrity": { + "eventHash": "sha256:3333333333333333333333333333333333333333333333333333333333333333", + "signature": null + } +} From 36d009100bf65cdcedb000891c9fbace780344e1 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 22 May 2026 16:05:10 -0400 Subject: [PATCH 3/5] Document SourceOS interaction substrate --- .../sourceos-interaction-substrate.md | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/contract-additions/sourceos-interaction-substrate.md diff --git a/docs/contract-additions/sourceos-interaction-substrate.md b/docs/contract-additions/sourceos-interaction-substrate.md new file mode 100644 index 0000000..429981e --- /dev/null +++ b/docs/contract-additions/sourceos-interaction-substrate.md @@ -0,0 +1,103 @@ +# SourceOS Interaction Substrate v0.1 + +Status: Proposed +Date: 2026-05-22 + +## Purpose + +This contract defines the shared interaction substrate for Noetica, AgentTerm, Matrix rooms, Prophet Workspace workrooms, Superconscious task submission, AgentPlane evidence, Policy Fabric decisions, Agent Registry grants, Memory Mesh scope, Slash Topics, and replay surfaces. + +The architectural rule is simple: Noetica and AgentTerm are different surfaces over the same governed interaction substrate. + +Noetica owns the browser chat, model-selection, steering UX, and inline governance trail. AgentTerm owns the terminal-native / Matrix-first operator console, room/thread flow, approvals, event tailing, and trace rendering. Neither surface owns model routing, memory durability, tool grants, policy admission, or execution evidence. + +## Relationship to OpsHistory + +`OpsHistoryEvent` remains the local-first operational event ledger. `SourceOSInteractionEvent` is the noetic/chat/task projection that can be embedded in, referenced by, or derived from OpsHistory. + +The intended binding is: + +```text +Noetica message/send/result + -> SourceOSInteractionEvent + -> OpsHistoryEvent + -> AgentTerm tail/render/replay + -> Memory Mesh context-pack request or AgentPlane evidence ref, when policy admits +``` + +AgentTerm can emit the same event shape from Matrix, terminal commands, or operator approvals: + +```text +Matrix / terminal command + -> SourceOSInteractionEvent + -> Policy Fabric decision + -> Agent Registry grant resolution + -> Superconscious / AgentPlane task + -> Noetica or AgentTerm governance-trail rendering +``` + +## Normative boundaries + +1. A surface may render a governance trail, but Policy Fabric owns policy decisions. +2. A surface may request or display model routing, but model-router or the SourceOS route authority owns route decisions in `sourceos` mode. +3. A surface may request memory scope, but Memory Mesh owns recall and writeback. +4. A surface may list participants, but Agent Registry owns non-human identity, grants, sessions, revocation, and runtime authority. +5. A surface may display evidence, but AgentPlane owns execution evidence and replay artifacts. +6. A surface may declare steering intent, but blackbox prompting must not be represented as mechanistic SAE steering. +7. A surface may carry bounded summaries inline, but raw secrets, credentials, unrestricted browser history, unrestricted shell output, and private chain-of-thought are not valid payloads. +8. Redaction tombstones must propagate through OpsHistory and invalidate derived context packs, memory writebacks, exports, and replay surfaces. + +## Required producers + +- `SocioProphet/Noetica`: emit `SourceOSInteractionEvent` for standalone provider calls, SourceOS submissions, steering intent, governance trace updates, and task completion or failure. +- `SourceOS-Linux/agent-term`: emit the same event shape for terminal / Matrix / operator commands, approvals, room-thread bindings, task submissions, and trace rendering. +- `SocioProphet/superconscious`: accept or emit this event shape at the task boundary without becoming the memory, policy, or evidence authority. +- `SocioProphet/agentplane`: attach run, evidence, and replay refs rather than scraping raw surface state. +- `SocioProphet/memory-mesh`: receive bounded context-pack references, not unbounded transcripts. +- `SocioProphet/agent-registry`: resolve non-human participants and grants before enablement. +- `SocioProphet/policy-fabric`: decide side effects, context release, memory writeback, bridge/export, redaction, and replay admission. + +## Minimum event content + +A conforming event records: + +- event identity and class; +- emitting surface; +- execution mode; +- conversation/workroom/topic/thread scope; +- actor and participants; +- optional task status/model/provider projection; +- optional steering intent; +- governance trace; +- payload disclosure posture; +- source event refs; +- redaction refs; +- integrity envelope. + +## Surface obligations + +Noetica must show the governance trace inline beside model output. AgentTerm must render the same trace in terminal/Matrix/operator form. Both must preserve enough fields for replay and audit. + +Noetica-specific obligations: + +- standalone mode still emits route evidence, request hash, evidence hash, provider, latency, memory posture, and policy posture; +- sourceos mode emits the same shape even when live submission is unavailable or blocked; +- steering UI emits explicit `steeringIntent` status and does not conflate prompt engineering with mechanistic steering. + +AgentTerm-specific obligations: + +- terminal, Matrix, and slash-command actions become interaction events before dispatch; +- high-risk actions require Policy Fabric decisions and Agent Registry grants before execution; +- AgentTerm can render Noetica / Superconscious / AgentPlane traces without owning cognition, routing, memory, or execution authority. + +## Non-goals + +This contract does not replace `OpsHistoryEvent`. It does not define model-provider SDK behavior. It does not define Matrix transport semantics. It does not create a new memory store. It does not permit unrestricted transcript replication. It does not grant tool authority. + +## Acceptance criteria + +- `schemas/SourceOSInteractionEvent.json` validates. +- `examples/sourceos-interaction-event.json` validates. +- Noetica can emit the example shape from a standalone chat completion. +- AgentTerm can ingest and render the example governance trail without live Matrix or live provider credentials. +- All side-effecting follow-on behavior remains behind policy and grant gates. From 0c77c680184abd02b45ff5c3de6c2f5f7c68aa7c Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 22 May 2026 16:16:07 -0400 Subject: [PATCH 4/5] Add SourceOS interaction validator --- .../validate_sourceos_interaction_examples.py | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 tools/validate_sourceos_interaction_examples.py diff --git a/tools/validate_sourceos_interaction_examples.py b/tools/validate_sourceos_interaction_examples.py new file mode 100644 index 0000000..4fa7fc2 --- /dev/null +++ b/tools/validate_sourceos_interaction_examples.py @@ -0,0 +1,31 @@ +#!/usr/bin/env python3 +"""Validate SourceOS interaction substrate examples.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import jsonschema + + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA = ROOT / "schemas" / "SourceOSInteractionEvent.json" +EXAMPLE = ROOT / "examples" / "sourceos-interaction-event.json" + + +def load_json(path: Path) -> object: + with path.open("r", encoding="utf-8") as handle: + return json.load(handle) + + +def main() -> None: + schema = load_json(SCHEMA) + example = load_json(EXAMPLE) + + jsonschema.Draft202012Validator.check_schema(schema) + jsonschema.validate(example, schema) + + +if __name__ == "__main__": + main() From 2cdc0518d4702e61961afef19511584152858a7d Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Fri, 22 May 2026 16:19:12 -0400 Subject: [PATCH 5/5] Add SourceOS interaction validation workflow --- .../sourceos-interaction-substrate.yml | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 .github/workflows/sourceos-interaction-substrate.yml diff --git a/.github/workflows/sourceos-interaction-substrate.yml b/.github/workflows/sourceos-interaction-substrate.yml new file mode 100644 index 0000000..261b1d2 --- /dev/null +++ b/.github/workflows/sourceos-interaction-substrate.yml @@ -0,0 +1,40 @@ +name: SourceOS Interaction Substrate + +on: + pull_request: + branches: ["main"] + paths: + - "schemas/SourceOSInteractionEvent.json" + - "examples/sourceos-interaction-event.json" + - "docs/contract-additions/sourceos-interaction-substrate.md" + - "tools/validate_sourceos_interaction_examples.py" + - ".github/workflows/sourceos-interaction-substrate.yml" + push: + branches: ["main", "work/noetica-agentterm-interaction-substrate"] + paths: + - "schemas/SourceOSInteractionEvent.json" + - "examples/sourceos-interaction-event.json" + - "docs/contract-additions/sourceos-interaction-substrate.md" + - "tools/validate_sourceos_interaction_examples.py" + - ".github/workflows/sourceos-interaction-substrate.yml" + +permissions: + contents: read + +jobs: + validate-sourceos-interaction: + name: Validate interaction substrate example + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install validator dependencies + run: python -m pip install --upgrade pip jsonschema + + - name: Validate SourceOS interaction example + run: python tools/validate_sourceos_interaction_examples.py