Intent
Codify the lessons from recent runtime logs into SourceOS contracts so UI, runtime, policy, plugins, shell, browser, and terminal surfaces cannot drift into contradictory capability states.
Evidence-derived failure class
A modern app/runtime stack can report a feature as enabled while the backend rejects the same capability as unsupported. That is capability split-brain. SourceOS should treat a feature as enabled only after a cross-plane capability negotiation succeeds across config, UI, runtime, server, plugin, policy, schema, and transport.
Secondary failure classes:
- repeated idempotent startup work logged as noisy operational chatter
- orphan lifecycle events, such as a turn/session event arriving before the local session registry knows the conversation
- Git/repo probing against paths that are not valid working-tree contexts
- browser automation transport state existing below the UI without a user-visible, revocable session receipt
- large runtime manifests dumped into ordinary logs instead of compact receipt references plus evidence bundles
Proposed spec additions
1. CapabilityLedger
Add a CapabilityLedger contract that records effective capability state after negotiation. Proposed states:
declaredrequestednegotiatingavailableenableddegradedblocked_by_policyunsupported_by_runtimeunsupported_by_servermissing_pluginmissing_schemafailed
Minimum fields:
{
"id": "urn:srcos:capability-ledger:<local-id>",
"type": "CapabilityLedger",
"specVersion": "0.1.0",
"capabilityRef": "urn:srcos:capability:<name>@<version>",
"declaredBy": ["config", "ui"],
"negotiatedBy": ["runtime", "server", "plugin", "policy"],
"effectiveState": "unsupported_by_server",
"policyDecisionRef": "urn:srcos:decision:<id>",
"evidenceRefs": [],
"capturedAt": "<date-time>"
}2. BrowserAutomationReceipt
Add a receipt type for browser automation sessions owned by BearBrowser-compatible surfaces.
Minimum fields:
{
"id": "urn:srcos:receipt:browser-automation:<local-id>",
"type": "BrowserAutomationReceipt",
"specVersion": "0.1.0",
"sessionRef": "urn:srcos:session:<id>",
"ownerRef": "urn:srcos:agent-or-plugin:<id>",
"transport": "native_pipe|cdp|webdriver|extension|accessibility",
"permissionScope": ["read_dom", "click", "type"],
"origin": "local|remote|workspace",
"userVisible": true,
"revocable": true,
"policyDecisionRef": "urn:srcos:decision:<id>",
"evidenceRefs": [],
"capturedAt": "<date-time>"
}3. GitWorkspaceState
Add a terminal/workspace classification object before any Git command is executed by TurtleTerm / agent-term / Sociosphere watchers.
States:
not_a_reporepo_rootinside_worktreeinside_git_dirbare_repoworktree_no_remotedetached_headcorrupt_repopermission_deniedoperation_superseded
Expected negative states should be info, not warning or error, unless a requested user operation depends on Git.
4. OrphanEventReceipt / quarantine protocol
Add an event-handling rule: every agent/runtime lifecycle event must attach to a known session DAG node or enter an orphan-event queue.
Protocol:
event_received
-> if session exists: append to session DAG
-> if session missing: append to orphan_event_queue
-> reconcile by conversation_id / parent_id / workspace_id / task_id
-> if reconciled: attach and mark recovered
-> if not reconciled after TTL: quarantine with evidence receipt
5. RuntimeInstallReceipt refinement
Existing SourceOS receipt patterns already support evidence references. Runtime install logs should emit compact operational lines and write full manifests to receipt/evidence bundles, not ordinary logs.
Acceptance criteria
- Add JSON schemas and examples for the new objects.
- Extend validation so examples fail on missing
policyDecisionRef, missing effectiveState, or ambiguous session ownership.
- Keep implementation in owning repos; this spec is the shared contract.
- Link implementation work to
SourceOS-Linux/BearBrowser, SourceOS-Linux/agent-term, SourceOS-Linux/sourceos-shell, and SocioProphet/sociosphere.
Owning surfaces
SourceOS-Linux/sourceos-spec: contract and examplesSourceOS-Linux/BearBrowser: browser automation receipt + visible revocation UISourceOS-Linux/agent-term: Git workspace classifier + severity disciplineSourceOS-Linux/sourceos-shell: capability ledger UI/runtime boundarySocioProphet/sociosphere: cross-repo control graph + orphan-event quarantine posture
Notes
This aligns with existing SourceOS receipt schemas and Sociosphere estate-control rules. The intent is not to create a parallel governance plane; it extends the existing receipt/evidence fabric.
Intent
Codify the lessons from recent runtime logs into SourceOS contracts so UI, runtime, policy, plugins, shell, browser, and terminal surfaces cannot drift into contradictory capability states.
Evidence-derived failure class
A modern app/runtime stack can report a feature as enabled while the backend rejects the same capability as unsupported. That is capability split-brain. SourceOS should treat a feature as enabled only after a cross-plane capability negotiation succeeds across config, UI, runtime, server, plugin, policy, schema, and transport.
Secondary failure classes:
Proposed spec additions
1. CapabilityLedger
Add a
CapabilityLedgercontract that records effective capability state after negotiation. Proposed states:declaredrequestednegotiatingavailableenableddegradedblocked_by_policyunsupported_by_runtimeunsupported_by_servermissing_pluginmissing_schemafailedMinimum fields:
{ "id": "urn:srcos:capability-ledger:<local-id>", "type": "CapabilityLedger", "specVersion": "0.1.0", "capabilityRef": "urn:srcos:capability:<name>@<version>", "declaredBy": ["config", "ui"], "negotiatedBy": ["runtime", "server", "plugin", "policy"], "effectiveState": "unsupported_by_server", "policyDecisionRef": "urn:srcos:decision:<id>", "evidenceRefs": [], "capturedAt": "<date-time>" }2. BrowserAutomationReceipt
Add a receipt type for browser automation sessions owned by BearBrowser-compatible surfaces.
Minimum fields:
{ "id": "urn:srcos:receipt:browser-automation:<local-id>", "type": "BrowserAutomationReceipt", "specVersion": "0.1.0", "sessionRef": "urn:srcos:session:<id>", "ownerRef": "urn:srcos:agent-or-plugin:<id>", "transport": "native_pipe|cdp|webdriver|extension|accessibility", "permissionScope": ["read_dom", "click", "type"], "origin": "local|remote|workspace", "userVisible": true, "revocable": true, "policyDecisionRef": "urn:srcos:decision:<id>", "evidenceRefs": [], "capturedAt": "<date-time>" }3. GitWorkspaceState
Add a terminal/workspace classification object before any Git command is executed by TurtleTerm / agent-term / Sociosphere watchers.
States:
not_a_reporepo_rootinside_worktreeinside_git_dirbare_repoworktree_no_remotedetached_headcorrupt_repopermission_deniedoperation_supersededExpected negative states should be
info, notwarningorerror, unless a requested user operation depends on Git.4. OrphanEventReceipt / quarantine protocol
Add an event-handling rule: every agent/runtime lifecycle event must attach to a known session DAG node or enter an orphan-event queue.
Protocol:
5. RuntimeInstallReceipt refinement
Existing SourceOS receipt patterns already support evidence references. Runtime install logs should emit compact operational lines and write full manifests to receipt/evidence bundles, not ordinary logs.
Acceptance criteria
policyDecisionRef, missingeffectiveState, or ambiguous session ownership.SourceOS-Linux/BearBrowser,SourceOS-Linux/agent-term,SourceOS-Linux/sourceos-shell, andSocioProphet/sociosphere.Owning surfaces
SourceOS-Linux/sourceos-spec: contract and examplesSourceOS-Linux/BearBrowser: browser automation receipt + visible revocation UISourceOS-Linux/agent-term: Git workspace classifier + severity disciplineSourceOS-Linux/sourceos-shell: capability ledger UI/runtime boundarySocioProphet/sociosphere: cross-repo control graph + orphan-event quarantine postureNotes
This aligns with existing SourceOS receipt schemas and Sociosphere estate-control rules. The intent is not to create a parallel governance plane; it extends the existing receipt/evidence fabric.