diff --git a/docs/contract-additions/runtime-causality-contracts-v0.md b/docs/contract-additions/runtime-causality-contracts-v0.md new file mode 100644 index 0000000..92de113 --- /dev/null +++ b/docs/contract-additions/runtime-causality-contracts-v0.md @@ -0,0 +1,79 @@ +# Runtime Causality Contracts v0 + +This additive contract slice introduces runtime-causality records derived from ordered diagnostic evidence. The goal is to collapse opaque operating-system log storms into typed, bounded, user-explainable evidence objects. + +The slice now covers both first-pass runtime signals and second-pass causality envelopes: retry loops, security verdict availability, layered network truth, browser launch transactions, runtime identity graphs, desktop-service broker state, maintenance epochs, registry integrity, boot/session phase gates, and diagnostic-storm summaries. + +## Added schemas + +| File | Type | URN prefix | Purpose | +|---|---|---|---| +| `schemas/RetryLoopFingerprint.json` | `RetryLoopFingerprint` | `urn:srcos:retry-loop:` | Summarize repeated runtime failures with count, cadence, retry class, terminal state, policy validity, and remediation. | +| `schemas/SecurityVerdictState.json` | `SecurityVerdictState` | `urn:srcos:security-verdict:` | Represent security decision availability, including degraded states such as no verdict provider, invalid provider, unavailable policy, or insufficient evidence. | +| `schemas/NetworkTruthState.json` | `NetworkTruthState` | `urn:srcos:network-truth:` | Preserve layered connectivity truth instead of reducing network state to online/offline. | +| `schemas/BrowserLaunchTransaction.json` | `BrowserLaunchTransaction` | `urn:srcos:browser-launch-transaction:` | Model browser launch as a preflight transaction before WebContent/GPU/Networking child processes are allowed to spawn. | +| `schemas/RuntimeIdentityGraph.json` | `RuntimeIdentityGraph` | `urn:srcos:runtime-identity-graph:` | Connect app, helper, broker, package, executable, audit-token, profile, and session identity observations. | +| `schemas/DesktopServiceBrokerState.json` | `DesktopServiceBrokerState` | `urn:srcos:desktop-service-broker-state:` | Represent broker availability for pasteboard, launcher, core-services, file-provider, notification, extension-registry, intents, network-settings, credential, and URL-opening surfaces. | +| `schemas/MaintenanceEpoch.json` | `MaintenanceEpoch` | `urn:srcos:maintenance-epoch:` | Bound cleanup, cache-delete, indexing, backup, plugin-scan, cloud-purge, experiment-refresh, and registry-sweep maintenance work. | +| `schemas/RuntimeRegistryIntegrityRecord.json` | `RuntimeRegistryIntegrityRecord` | `urn:srcos:runtime-registry-integrity:` | Describe package receipt, extension record, broker record, manifest, launch-record, profile, and namespace-descriptor integrity. | +| `schemas/BootSessionPhaseState.json` | `BootSessionPhaseState` | `urn:srcos:boot-session-phase:` | Gate services by sealed boot, pre-login, post-login locked, unlocked user session, degraded session, or recovery session. | +| `schemas/DiagnosticStormRecord.json` | `DiagnosticStormRecord` | `urn:srcos:diagnostic-storm:` | Summarize repeated diagnostic signatures with count, cadence, severity, representative samples, suppression policy, and terminal state. | + +## Added examples + +| File | Scenario | +|---|---| +| `examples/retry_loop_fingerprint.json` | Full Disk Access/TCC denial loop collapsed into one bounded fingerprint. | +| `examples/security_verdict_state.json` | Network-flow observation where the verdict provider is unavailable. | +| `examples/network_truth_state.json` | Wi-Fi radio active but no association, failed route, and degraded DNS/DHCP observers. | +| `examples/browser_launch_transaction.json` | Browser launch prevented before child-process spawn because broker and extension-registry preflight failed. | +| `examples/runtime_identity_graph.json` | BearBrowser app and WebContent child process identity resolved as a degraded runtime graph. | +| `examples/desktop_service_broker_state.json` | Pasteboard, CoreServices, and extension-registry brokers degraded for browser child-process launch. | +| `examples/maintenance_epoch.json` | deleted/triald registry and experiment sweep bounded as a degraded maintenance epoch. | +| `examples/runtime_registry_integrity_record.json` | LaunchServices extension-record and treatment namespace-descriptor failures captured as registry-integrity evidence. | +| `examples/boot_session_phase_state.json` | post-login locked session blocks analytics and registry-cleanup components until unlock. | +| `examples/diagnostic_storm_record.json` | triald missing-namespace descriptor storm summarized with count, cadence, and suppression policy. | + +## Design intent + +The records are designed to support SourceOS doctor flows, browser diagnostics, terminal diagnostics, mesh/network intelligence, and forensic evidence receipts. They intentionally avoid platform-specific names in schema fields while allowing platform-specific event evidence through `evidenceRefs`. + +## Observed failure classes covered + +- Permission-denied polling loops. +- Security monitors that see flows but cannot attach verdicts. +- Network path ambiguity where radio, route, DNS, DHCP, captive portal, and internet reachability disagree. +- Browser child-process launch failures caused by missing desktop brokers, invalid registries, or denied service lookups. +- Runtime identity ambiguity across app, child process, helper, audit-token, and package boundaries. +- Background maintenance storms caused by cleanup, registry, experiment, backup, cloud purge, or plugin-scan activity. +- Registry integrity failures involving missing extension records, package receipts, broker records, and namespace descriptors. +- Boot/session phase failures where locked state prevents keyring, analytics, registry, or user-store access. +- Diagnostic storms that need first-seen, last-seen, count, cadence, sample events, suppression policy, terminal state, and remediation. + +## Downstream consumers + +- SourceOS doctor and workstation health reports. +- BearBrowser launch preflight and child-process attestation. +- TurtleTerm terminal helper preflight and broker checks. +- MeshRush/Meshrush network-truth and peer-path evaluation. +- Prophet Platform evidence receipts and FogStack runtime readiness checks. +- Sociosphere estate-control observability where runtime state must be summarized without losing causality. + +## Implementation notes + +These schemas are additive. They do not replace `TelemetryEvent`, `PolicyDecision`, `ExecutionDecision`, or `RunRecord`; instead, they summarize and relate those lower-level observations into user-readable runtime-causality records. + +The minimum viable runtime flow is: + +1. Capture raw telemetry. +2. Normalize repeated signatures into `RetryLoopFingerprint` and `DiagnosticStormRecord`. +3. Attach contextual truth with `NetworkTruthState`, `SecurityVerdictState`, `BootSessionPhaseState`, and `RuntimeRegistryIntegrityRecord`. +4. Gate app launches through `RuntimeIdentityGraph`, `DesktopServiceBrokerState`, and `BrowserLaunchTransaction`. +5. Bound cleanup/indexing/config refresh through `MaintenanceEpoch`. + +## Follow-up work + +- Add central `schemas/README.md` catalog rows for these ten types. +- Add validation automation that maps schema titles to snake_case examples. +- Add an example storm-log parser that emits these records from ordered logs. +- Wire SourceOS shell, BearBrowser, TurtleTerm, and MeshRush consumers to these contracts. diff --git a/examples/boot_session_phase_state.json b/examples/boot_session_phase_state.json new file mode 100644 index 0000000..f74d553 --- /dev/null +++ b/examples/boot_session_phase_state.json @@ -0,0 +1,41 @@ +{ + "id": "urn:srcos:boot-session-phase:post_login_locked_001", + "type": "BootSessionPhaseState", + "specVersion": "2.0.0", + "observedAt": "2026-05-06T22:36:15Z", + "bootId": "boot-20260506-001", + "sessionId": "session-501-post-login-locked", + "phase": "post-login-locked", + "phaseVerdict": "not-ready", + "availableKeyrings": [], + "availablePortals": ["notification"], + "allowedComponents": [ + { + "componentRef": "urn:srcos:component:basic-network-observer", + "state": "allowed-degraded", + "reason": "May observe interface transitions but cannot access unlocked user analytics state." + } + ], + "blockedComponents": [ + { + "componentRef": "urn:srcos:component:wifianalyticsd", + "requiredPhase": "unlocked-user-session", + "state": "deferred", + "reason": "Device has not been unlocked since boot, so analytics client and detached signature stores are unavailable.", + "remediationHint": "Defer analytics sampling until the user session reaches unlocked-user-session." + }, + { + "componentRef": "urn:srcos:component:deleted-registry-sweep", + "requiredPhase": "unlocked-user-session", + "state": "deferred", + "reason": "Registry cleanup requires unlocked stores and should not run during locked post-login state.", + "remediationHint": "Queue cleanup until unlock or recovery session." + } + ], + "evidenceRefs": [ + "urn:srcos:telemetry:te_device_not_unlocked_since_boot", + "urn:srcos:telemetry:te_key_store_locked" + ], + "userVisibleSummary": "The session is post-login but still locked; components requiring unlocked state must be deferred.", + "remediationHint": "Transition to unlocked-user-session before running analytics, registry repair, or browser launch preflight requiring user stores." +} diff --git a/examples/browser_launch_transaction.json b/examples/browser_launch_transaction.json new file mode 100644 index 0000000..8ce58c1 --- /dev/null +++ b/examples/browser_launch_transaction.json @@ -0,0 +1,24 @@ +{ + "id": "urn:srcos:browser-launch-transaction:bearbrowser_001", + "type": "BrowserLaunchTransaction", + "specVersion": "2.0.0", + "componentRef": "urn:srcos:component:BearBrowser", + "phaseStatus": "preflight", + "capabilityPreflightPassed": false, + "identityGraphValid": true, + "desktopBrokerValid": false, + "profileStoreValid": true, + "extensionRegistryValid": false, + "networkTruthSnapshotCaptured": true, + "childProcessSpawnAllowed": false, + "childProcessAttested": false, + "pageLoadStarted": false, + "observedAt": "2026-05-06T22:37:03Z", + "evidenceRefs": [ + "urn:srcos:telemetry:te_child_process_failed", + "urn:srcos:telemetry:te_launchservices_denied", + "urn:srcos:telemetry:te_pasteboard_denied" + ], + "userVisibleImpact": "WebContent child processes cannot spawn due to missing broker and extension validation", + "remediationHint": "Verify desktop broker availability and extension registry integrity before retrying launch." +} diff --git a/examples/desktop_service_broker_state.json b/examples/desktop_service_broker_state.json new file mode 100644 index 0000000..c45dbaf --- /dev/null +++ b/examples/desktop_service_broker_state.json @@ -0,0 +1,38 @@ +{ + "id": "urn:srcos:desktop-service-broker-state:bearbrowser_001", + "type": "DesktopServiceBrokerState", + "specVersion": "2.0.0", + "observedAt": "2026-05-06T22:37:03Z", + "componentRef": "urn:srcos:component:BearBrowser", + "overallState": "degraded", + "brokers": [ + { + "brokerKind": "pasteboard", + "state": "policy-blocked", + "fallback": "disable clipboard integration for WebContent child processes", + "userVisibleImpact": "Copy and paste may be unavailable inside sandboxed web content.", + "remediationHint": "Route pasteboard access through the desktop broker and require user gesture gating." + }, + { + "brokerKind": "core-services", + "state": "policy-blocked", + "fallback": "prevent child-process LaunchServices/CoreServices lookup", + "userVisibleImpact": "Browser child process cannot directly register with host desktop services.", + "remediationHint": "Move host desktop service calls into a parent-process broker." + }, + { + "brokerKind": "extension-registry", + "state": "degraded", + "fallback": "quarantine extension discovery for this launch transaction", + "userVisibleImpact": "Extensions are disabled until registry integrity is verified.", + "remediationHint": "Rebuild or refresh the extension registry before enabling extension discovery." + } + ], + "evidenceRefs": [ + "urn:srcos:telemetry:te_pasteboard_denied", + "urn:srcos:telemetry:te_coreservices_denied", + "urn:srcos:telemetry:te_extension_query_cancelled" + ], + "userVisibleSummary": "Desktop service brokers are degraded for BearBrowser, so child-process desktop access must remain brokered or disabled.", + "remediationHint": "Verify pasteboard, CoreServices, and extension-registry brokers before spawning WebContent." +} diff --git a/examples/diagnostic_storm_record.json b/examples/diagnostic_storm_record.json new file mode 100644 index 0000000..39b1e77 --- /dev/null +++ b/examples/diagnostic_storm_record.json @@ -0,0 +1,30 @@ +{ + "id": "urn:srcos:diagnostic-storm:triald_missing_namespace_001", + "type": "DiagnosticStormRecord", + "specVersion": "2.0.0", + "signature": "experiment:triald_system:missing_namespace_descriptor", + "sourceComponent": "triald_system", + "normalizedFailureClass": "registry-integrity-failure", + "firstSeen": "2026-05-06T22:37:00Z", + "lastSeen": "2026-05-06T22:37:18Z", + "repeatCount": 492, + "medianIntervalMs": 4.5, + "maxEventsPerSecond": 136, + "severity": "error", + "sampleEvents": [ + { + "eventRef": "urn:srcos:telemetry:te_triald_namespace_missing_001", + "messageTemplate": "Requested namespace descriptor does not exist for treatment layer", + "observedAt": "2026-05-06T22:37:00Z" + } + ], + "suppressionPolicy": "summarize", + "terminalState": "still-active", + "linkedIncidentRef": "urn:srcos:incident:runtime_registry_degraded_001", + "evidenceRefs": [ + "urn:srcos:telemetry:te_triald_namespace_missing", + "urn:srcos:retry-loop:triald_namespace_descriptor_001" + ], + "userVisibleSummary": "Trial namespace descriptor lookup repeated hundreds of times in a maintenance sweep.", + "remediationHint": "Summarize repeated namespace misses and defer further lookups until the namespace cache or registry epoch changes." +} diff --git a/examples/maintenance_epoch.json b/examples/maintenance_epoch.json new file mode 100644 index 0000000..8266163 --- /dev/null +++ b/examples/maintenance_epoch.json @@ -0,0 +1,31 @@ +{ + "id": "urn:srcos:maintenance-epoch:deleted_triald_001", + "type": "MaintenanceEpoch", + "specVersion": "2.0.0", + "startedAt": "2026-05-06T22:37:00Z", + "endedAt": "2026-05-06T22:37:21Z", + "epochKind": "registry-sweep", + "state": "degraded", + "sourceComponent": "deleted/triald", + "allowedDuringInteractiveLaunch": false, + "bootPhaseRequirement": "unlocked-user-session", + "lockRequirements": [ + "runtime-registry", + "launch-services-index", + "experiment-namespace-cache" + ], + "emissionBudget": { + "maxEventsPerMinute": 60, + "onBudgetExceeded": "summarize" + }, + "observedStormRefs": [ + "urn:srcos:diagnostic-storm:triald_missing_namespace_001", + "urn:srcos:diagnostic-storm:deleted_lsbundle_missing_001" + ], + "evidenceRefs": [ + "urn:srcos:telemetry:te_triald_namespace_missing", + "urn:srcos:telemetry:te_deleted_lsbundle_missing" + ], + "userVisibleSummary": "Background registry and experiment-maintenance work emitted a high-volume storm during an interactive browser launch window.", + "remediationHint": "Defer registry sweeps during interactive launches and collapse repeated missing-namespace events into DiagnosticStormRecord summaries." +} diff --git a/examples/network_truth_state.json b/examples/network_truth_state.json new file mode 100644 index 0000000..7d131fd --- /dev/null +++ b/examples/network_truth_state.json @@ -0,0 +1,27 @@ +{ + "id": "urn:srcos:network-truth:wifi_epoch_001", + "type": "NetworkTruthState", + "specVersion": "2.0.0", + "observedAt": "2026-05-06T22:36:20Z", + "networkEpoch": "wifi-en0-20260506-223620", + "interfaceRef": "en0", + "deviceIdentityState": "nil", + "radioState": "on", + "associationState": "not-associated", + "authenticationState": "unknown", + "dhcpState": "observer-failed", + "dnsState": "observer-failed", + "routeState": "route-failed", + "captivePortalState": "credential-missing", + "internetReachability": "unreachable", + "localMeshReachability": "unknown", + "vpnOrPrivacyOverlayState": "unknown", + "trustedPeerPathState": "not-evaluated", + "evidenceRefs": [ + "urn:srcos:telemetry:te_dns_nil_device", + "urn:srcos:telemetry:te_no_route_host", + "urn:srcos:telemetry:te_wifi_active_no_network" + ], + "userVisibleSummary": "Wi-Fi radio is active, but no network is associated and route/DNS observers are degraded.", + "remediationHint": "Re-evaluate association, DHCP, DNS, and route state before remote sync or browser launch." +} diff --git a/examples/retry_loop_fingerprint.json b/examples/retry_loop_fingerprint.json new file mode 100644 index 0000000..2547670 --- /dev/null +++ b/examples/retry_loop_fingerprint.json @@ -0,0 +1,20 @@ +{ + "id": "urn:srcos:retry-loop:blockblock_tcc_001", + "type": "RetryLoopFingerprint", + "specVersion": "2.0.0", + "signature": "capability_denial:blockblock:fda_tcc", + "sourceComponent": "BlockBlock", + "firstSeen": "2026-05-06T22:35:44Z", + "lastSeen": "2026-05-06T22:37:54Z", + "count": 176, + "medianIntervalMs": 556, + "maxEventsPerSecond": 2, + "retryClass": "polling", + "terminalState": "still-looping", + "policyValidity": "denied-but-noisy", + "severity": "warn", + "sampleEventRefs": ["urn:srcos:telemetry:te_001"], + "suppressionPolicy": "deduplicate_and_summarize", + "userVisibleImpact": "Full Disk Access not granted, polling continues", + "remediationHint": "Request Full Disk Access from user preferences" +} diff --git a/examples/runtime_identity_graph.json b/examples/runtime_identity_graph.json new file mode 100644 index 0000000..dd96903 --- /dev/null +++ b/examples/runtime_identity_graph.json @@ -0,0 +1,51 @@ +{ + "id": "urn:srcos:runtime-identity-graph:bearbrowser_001", + "type": "RuntimeIdentityGraph", + "specVersion": "2.0.0", + "observedAt": "2026-05-06T22:37:03Z", + "rootComponentRef": "urn:srcos:component:BearBrowser", + "identityVerdict": "degraded", + "nodes": [ + { + "nodeId": "app.bearbrowser", + "nodeKind": "app", + "displayName": "BearBrowser", + "processId": 54990, + "bundleOrPackageId": "application.dev.sourceos.BearBrowser", + "verificationVerdict": "valid" + }, + { + "nodeId": "child.webcontent.54997", + "nodeKind": "browser-child", + "displayName": "WebContent", + "processId": 54997, + "bundleOrPackageId": "com.apple.WebKit.WebContent", + "verificationVerdict": "degraded" + }, + { + "nodeId": "audit.webcontent.54997", + "nodeKind": "audit-token", + "displayName": "WebContent audit token", + "auditIdentity": "audit-token-unresolved", + "verificationVerdict": "ambiguous" + } + ], + "edges": [ + { + "from": "app.bearbrowser", + "to": "child.webcontent.54997", + "relationship": "spawned" + }, + { + "from": "child.webcontent.54997", + "to": "audit.webcontent.54997", + "relationship": "observed-as" + } + ], + "evidenceRefs": [ + "urn:srcos:telemetry:te_invalid_product_id", + "urn:srcos:telemetry:te_audit_token_unresolved" + ], + "userVisibleImpact": "A browser child process launched, but its runtime identity could not be fully resolved.", + "remediationHint": "Verify child-process package identity, audit-token mapping, and broker registration before allowing page load." +} diff --git a/examples/runtime_registry_integrity_record.json b/examples/runtime_registry_integrity_record.json new file mode 100644 index 0000000..5b68aba --- /dev/null +++ b/examples/runtime_registry_integrity_record.json @@ -0,0 +1,32 @@ +{ + "id": "urn:srcos:runtime-registry-integrity:launchservices_001", + "type": "RuntimeRegistryIntegrityRecord", + "specVersion": "2.0.0", + "observedAt": "2026-05-06T22:37:00Z", + "componentRef": "urn:srcos:component:desktop-registry", + "bundleOrPackageIdentity": "com.apple.CloudPhotosConfiguration", + "verificationVerdict": "degraded", + "registryRecords": [ + { + "recordKind": "extension-record", + "recordRef": "com.apple.CloudPhotosConfiguration", + "state": "missing", + "errorCode": "LS_-10814", + "userVisibleImpact": "The runtime could not construct an extension record from the desktop registry.", + "remediationHint": "Refresh or rebuild the runtime extension registry before enabling extension discovery." + }, + { + "recordKind": "namespace-descriptor", + "recordRef": "trial-treatment-layer-0x4", + "state": "missing", + "userVisibleImpact": "Experiment or treatment metadata could not be resolved during maintenance.", + "remediationHint": "Suppress repeated namespace lookups and emit a DiagnosticStormRecord until the namespace cache changes." + } + ], + "evidenceRefs": [ + "urn:srcos:telemetry:te_lsbundle_record_missing", + "urn:srcos:telemetry:te_namespace_descriptor_missing" + ], + "userVisibleSummary": "Registry integrity is degraded because extension records and treatment namespace descriptors are missing.", + "remediationHint": "Run a bounded registry repair or defer registry-dependent launch work until integrity is restored." +} diff --git a/examples/security_verdict_state.json b/examples/security_verdict_state.json new file mode 100644 index 0000000..df34ab7 --- /dev/null +++ b/examples/security_verdict_state.json @@ -0,0 +1,14 @@ +{ + "id": "urn:srcos:security-verdict:lulu_flow_001", + "type": "SecurityVerdictState", + "specVersion": "2.0.0", + "subjectRef": "urn:srcos:component:lulu_extension", + "decision": "no-verdict", + "verdictProviderState": "no-verdict-provider", + "observedAt": "2026-05-06T22:36:00Z", + "policyRef": "urn:srcos:policy:network_flow_block", + "providerRef": "urn:srcos:verdict-provider:lulu", + "evidenceRefs": ["urn:srcos:telemetry:te_002"], + "userVisibleImpact": "Flows exist but no security verdict available", + "remediationHint": "Verify extension provisioning and provider availability" +} diff --git a/schemas/BootSessionPhaseState.json b/schemas/BootSessionPhaseState.json new file mode 100644 index 0000000..59e1374 --- /dev/null +++ b/schemas/BootSessionPhaseState.json @@ -0,0 +1,63 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/BootSessionPhaseState.json", + "title": "BootSessionPhaseState", + "description": "A boot/session phase record used to gate services that require user unlock, keyrings, portals, desktop brokers, or recovery-mode boundaries before execution.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "observedAt", + "bootId", + "sessionId", + "phase", + "phaseVerdict", + "allowedComponents", + "blockedComponents" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:boot-session-phase:" }, + "type": { "const": "BootSessionPhaseState" }, + "specVersion": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" }, + "bootId": { "type": "string", "minLength": 1 }, + "sessionId": { "type": "string", "minLength": 1 }, + "phase": { "enum": ["sealed-boot", "pre-login", "post-login-locked", "unlocked-user-session", "degraded-session", "recovery-session", "unknown"] }, + "phaseVerdict": { "enum": ["ready", "not-ready", "degraded", "recovery-only", "unknown"] }, + "availableKeyrings": { "type": "array", "items": { "type": "string" } }, + "availablePortals": { "type": "array", "items": { "type": "string" } }, + "allowedComponents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["componentRef", "state"], + "properties": { + "componentRef": { "type": "string" }, + "state": { "enum": ["allowed", "allowed-degraded", "unknown"] }, + "reason": { "type": "string" } + } + } + }, + "blockedComponents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["componentRef", "requiredPhase", "state"], + "properties": { + "componentRef": { "type": "string" }, + "requiredPhase": { "enum": ["sealed-boot", "pre-login", "post-login-locked", "unlocked-user-session", "degraded-session", "recovery-session", "unknown"] }, + "state": { "enum": ["blocked", "deferred", "quarantined", "unknown"] }, + "reason": { "type": "string" }, + "remediationHint": { "type": "string" } + } + } + }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/BrowserLaunchTransaction.json b/schemas/BrowserLaunchTransaction.json new file mode 100644 index 0000000..abeb557 --- /dev/null +++ b/schemas/BrowserLaunchTransaction.json @@ -0,0 +1,43 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/BrowserLaunchTransaction.json", + "title": "BrowserLaunchTransaction", + "description": "A preflighted launch transaction for browser or browser-like child processes, ensuring capability, identity, broker, profile, extension, and network truth preconditions are satisfied.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "componentRef", + "phaseStatus", + "capabilityPreflightPassed", + "identityGraphValid", + "desktopBrokerValid", + "profileStoreValid", + "extensionRegistryValid", + "networkTruthSnapshotCaptured", + "childProcessSpawnAllowed", + "observedAt" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:browser-launch-transaction:" }, + "type": { "const": "BrowserLaunchTransaction" }, + "specVersion": { "type": "string" }, + "componentRef": { "type": "string", "minLength": 1 }, + "phaseStatus": { "enum": ["preflight", "degraded", "failed", "completed"] }, + "capabilityPreflightPassed": { "type": "boolean" }, + "identityGraphValid": { "type": "boolean" }, + "desktopBrokerValid": { "type": "boolean" }, + "profileStoreValid": { "type": "boolean" }, + "extensionRegistryValid": { "type": "boolean" }, + "networkTruthSnapshotCaptured": { "type": "boolean" }, + "childProcessSpawnAllowed": { "type": "boolean" }, + "childProcessAttested": { "type": "boolean" }, + "pageLoadStarted": { "type": "boolean" }, + "observedAt": { "type": "string", "format": "date-time" }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleImpact": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/DesktopServiceBrokerState.json b/schemas/DesktopServiceBrokerState.json new file mode 100644 index 0000000..0232924 --- /dev/null +++ b/schemas/DesktopServiceBrokerState.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/DesktopServiceBrokerState.json", + "title": "DesktopServiceBrokerState", + "description": "A desktop-service broker availability record for pasteboard, launcher, file provider, notification, extension, credential, and network-settings surfaces consumed by sandboxed apps and child processes.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "observedAt", + "componentRef", + "overallState", + "brokers" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:desktop-service-broker-state:" }, + "type": { "const": "DesktopServiceBrokerState" }, + "specVersion": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" }, + "componentRef": { "type": "string", "minLength": 1 }, + "overallState": { "enum": ["ready", "degraded", "unavailable", "policy-blocked", "unknown"] }, + "brokers": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["brokerKind", "state"], + "properties": { + "brokerKind": { + "enum": [ + "pasteboard", + "launcher", + "core-services", + "file-provider", + "notification", + "extension-registry", + "intents", + "network-settings", + "credential-prompt", + "url-opener", + "accessibility", + "unknown" + ] + }, + "state": { "enum": ["ready", "degraded", "unavailable", "policy-blocked", "not-configured", "unknown"] }, + "policyRef": { "type": "string" }, + "fallback": { "type": "string" }, + "userVisibleImpact": { "type": "string" }, + "remediationHint": { "type": "string" } + } + } + }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/DiagnosticStormRecord.json b/schemas/DiagnosticStormRecord.json new file mode 100644 index 0000000..d60b07d --- /dev/null +++ b/schemas/DiagnosticStormRecord.json @@ -0,0 +1,56 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/DiagnosticStormRecord.json", + "title": "DiagnosticStormRecord", + "description": "A bounded diagnostic-storm summary that preserves repeated event signatures, timing, count, severity, representative samples, suppression state, terminal state, and linked incidents.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "signature", + "sourceComponent", + "normalizedFailureClass", + "firstSeen", + "lastSeen", + "repeatCount", + "severity", + "terminalState", + "suppressionPolicy" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:diagnostic-storm:" }, + "type": { "const": "DiagnosticStormRecord" }, + "specVersion": { "type": "string" }, + "signature": { "type": "string", "minLength": 1 }, + "sourceComponent": { "type": "string", "minLength": 1 }, + "normalizedFailureClass": { "enum": ["capability-denial", "network-observer-failure", "security-verdict-unavailable", "registry-integrity-failure", "maintenance-sweep-failure", "browser-launch-failure", "identity-resolution-failure", "boot-phase-gate-failure", "unknown"] }, + "firstSeen": { "type": "string", "format": "date-time" }, + "lastSeen": { "type": "string", "format": "date-time" }, + "repeatCount": { "type": "integer", "minimum": 1 }, + "medianIntervalMs": { "type": "number", "minimum": 0 }, + "maxEventsPerSecond": { "type": "integer", "minimum": 1 }, + "severity": { "enum": ["debug", "info", "warn", "error", "critical"] }, + "sampleEvents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["eventRef", "messageTemplate"], + "properties": { + "eventRef": { "type": "string" }, + "messageTemplate": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" } + } + } + }, + "suppressionPolicy": { "enum": ["none", "deduplicate", "summarize", "suppress", "quarantine", "escalate", "unknown"] }, + "terminalState": { "enum": ["resolved", "still-active", "suppressed", "quarantined", "escalated", "unknown"] }, + "linkedIncidentRef": { "type": "string" }, + "causalParentRef": { "type": "string" }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/MaintenanceEpoch.json b/schemas/MaintenanceEpoch.json new file mode 100644 index 0000000..ce10b8c --- /dev/null +++ b/schemas/MaintenanceEpoch.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/MaintenanceEpoch.json", + "title": "MaintenanceEpoch", + "description": "A bounded record for background maintenance sweeps such as cleanup, cache deletion, indexing, backup, plugin scans, cloud purge, and experiment/config refresh.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "startedAt", + "epochKind", + "state", + "sourceComponent", + "allowedDuringInteractiveLaunch", + "emissionBudget" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:maintenance-epoch:" }, + "type": { "const": "MaintenanceEpoch" }, + "specVersion": { "type": "string" }, + "startedAt": { "type": "string", "format": "date-time" }, + "endedAt": { "type": "string", "format": "date-time" }, + "epochKind": { "enum": ["cleanup", "cache-delete", "indexing", "backup", "plugin-scan", "cloud-purge", "experiment-refresh", "registry-sweep", "unknown"] }, + "state": { "enum": ["running", "completed", "failed", "degraded", "suppressed", "unknown"] }, + "sourceComponent": { "type": "string", "minLength": 1 }, + "allowedDuringInteractiveLaunch": { "type": "boolean" }, + "bootPhaseRequirement": { "enum": ["sealed-boot", "pre-login", "post-login-locked", "unlocked-user-session", "degraded-session", "recovery-session", "unknown"] }, + "lockRequirements": { "type": "array", "items": { "type": "string" } }, + "emissionBudget": { + "type": "object", + "additionalProperties": false, + "required": ["maxEventsPerMinute", "onBudgetExceeded"], + "properties": { + "maxEventsPerMinute": { "type": "integer", "minimum": 1 }, + "onBudgetExceeded": { "enum": ["summarize", "suppress", "quarantine", "escalate", "unknown"] } + } + }, + "observedStormRefs": { "type": "array", "items": { "type": "string" } }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/NetworkTruthState.json b/schemas/NetworkTruthState.json new file mode 100644 index 0000000..522b0bc --- /dev/null +++ b/schemas/NetworkTruthState.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/NetworkTruthState.json", + "title": "NetworkTruthState", + "description": "A layered network-state observation that separates radio, association, DHCP, DNS, route, captive portal, internet, mesh, overlay, and trusted-peer reachability instead of reducing connectivity to online/offline.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "observedAt", + "networkEpoch", + "radioState", + "associationState", + "dhcpState", + "dnsState", + "routeState", + "internetReachability", + "localMeshReachability" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:network-truth:" }, + "type": { "const": "NetworkTruthState" }, + "specVersion": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" }, + "networkEpoch": { "type": "string", "minLength": 1 }, + "interfaceRef": { "type": "string" }, + "deviceIdentityState": { "enum": ["present", "missing", "nil", "ambiguous", "unknown"] }, + "radioState": { "enum": ["off", "on", "resetting", "unavailable", "unknown"] }, + "associationState": { "enum": ["not-associated", "associating", "associated", "unstable", "unknown"] }, + "authenticationState": { "enum": ["not-authenticated", "authenticating", "authenticated", "failed", "unknown"] }, + "dhcpState": { "enum": ["not-started", "acquiring", "leased", "failed", "observer-failed", "unknown"] }, + "dnsState": { "enum": ["not-configured", "configured", "degraded", "failed", "observer-failed", "unknown"] }, + "routeState": { "enum": ["no-route", "route-present", "route-conflict", "route-failed", "unknown"] }, + "captivePortalState": { "enum": ["not-detected", "detected", "credential-missing", "authenticated", "unknown"] }, + "internetReachability": { "enum": ["reachable", "unreachable", "degraded", "unknown"] }, + "localMeshReachability": { "enum": ["reachable", "unreachable", "degraded", "not-configured", "unknown"] }, + "vpnOrPrivacyOverlayState": { "enum": ["off", "on", "degraded", "policy-blocked", "unknown"] }, + "trustedPeerPathState": { "enum": ["available", "unavailable", "degraded", "not-evaluated", "unknown"] }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/RetryLoopFingerprint.json b/schemas/RetryLoopFingerprint.json new file mode 100644 index 0000000..7b6cfe5 --- /dev/null +++ b/schemas/RetryLoopFingerprint.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/RetryLoopFingerprint.json", + "title": "RetryLoopFingerprint", + "description": "A bounded summary of a repeated runtime failure or retry loop, preserving count, cadence, burst density, policy validity, and terminal state.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "signature", + "sourceComponent", + "firstSeen", + "lastSeen", + "count", + "retryClass", + "terminalState", + "policyValidity" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:retry-loop:" + }, + "type": { + "const": "RetryLoopFingerprint" + }, + "specVersion": { + "type": "string" + }, + "signature": { + "type": "string", + "minLength": 1 + }, + "sourceComponent": { + "type": "string", + "minLength": 1 + }, + "firstSeen": { + "type": "string", + "format": "date-time" + }, + "lastSeen": { + "type": "string", + "format": "date-time" + }, + "count": { + "type": "integer", + "minimum": 1 + }, + "medianIntervalMs": { + "type": "number", + "minimum": 0 + }, + "maxEventsPerSecond": { + "type": "integer", + "minimum": 1 + }, + "retryClass": { + "enum": [ + "polling", + "burst", + "backoff", + "sweep", + "respawn", + "unknown" + ] + }, + "terminalState": { + "enum": [ + "resolved", + "still-looping", + "suppressed", + "quarantined", + "escalated", + "unknown" + ] + }, + "policyValidity": { + "enum": [ + "expected", + "unexpected", + "denied-correctly", + "denied-but-noisy", + "invalid-retry", + "unknown" + ] + }, + "severity": { + "enum": [ + "debug", + "info", + "warn", + "error", + "critical" + ] + }, + "sampleEventRefs": { + "type": "array", + "items": { + "type": "string" + } + }, + "causalParentRef": { + "type": "string" + }, + "suppressionPolicy": { + "type": "string" + }, + "userVisibleImpact": { + "type": "string" + }, + "remediationHint": { + "type": "string" + } + } +} diff --git a/schemas/RuntimeIdentityGraph.json b/schemas/RuntimeIdentityGraph.json new file mode 100644 index 0000000..f3df1c6 --- /dev/null +++ b/schemas/RuntimeIdentityGraph.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/RuntimeIdentityGraph.json", + "title": "RuntimeIdentityGraph", + "description": "A runtime identity graph connecting process, package, executable, helper, broker, profile, session, and audit-token identity observations.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "observedAt", + "rootComponentRef", + "identityVerdict", + "nodes" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:runtime-identity-graph:" }, + "type": { "const": "RuntimeIdentityGraph" }, + "specVersion": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" }, + "rootComponentRef": { "type": "string", "minLength": 1 }, + "identityVerdict": { "enum": ["valid", "degraded", "missing", "ambiguous", "invalid", "unknown"] }, + "nodes": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["nodeId", "nodeKind", "displayName"], + "properties": { + "nodeId": { "type": "string", "minLength": 1 }, + "nodeKind": { "enum": ["app", "daemon", "xpc-service", "browser-child", "terminal-helper", "broker", "extension", "package", "profile", "session", "audit-token", "executable"] }, + "displayName": { "type": "string", "minLength": 1 }, + "processId": { "type": "integer", "minimum": 0 }, + "bundleOrPackageId": { "type": "string" }, + "executableDigest": { "type": "string" }, + "auditIdentity": { "type": "string" }, + "verificationVerdict": { "enum": ["valid", "degraded", "missing", "ambiguous", "invalid", "unknown"] } + } + } + }, + "edges": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["from", "to", "relationship"], + "properties": { + "from": { "type": "string" }, + "to": { "type": "string" }, + "relationship": { "enum": ["spawned", "owns", "brokers", "uses-profile", "runs-as", "attests", "packages", "observed-as", "unknown"] } + } + } + }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleImpact": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/RuntimeRegistryIntegrityRecord.json b/schemas/RuntimeRegistryIntegrityRecord.json new file mode 100644 index 0000000..afad764 --- /dev/null +++ b/schemas/RuntimeRegistryIntegrityRecord.json @@ -0,0 +1,47 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/RuntimeRegistryIntegrityRecord.json", + "title": "RuntimeRegistryIntegrityRecord", + "description": "An integrity record for runtime registries such as package receipts, extension records, broker registrations, manifests, and desktop-service records.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "observedAt", + "componentRef", + "verificationVerdict", + "registryRecords" + ], + "properties": { + "id": { "type": "string", "pattern": "^urn:srcos:runtime-registry-integrity:" }, + "type": { "const": "RuntimeRegistryIntegrityRecord" }, + "specVersion": { "type": "string" }, + "observedAt": { "type": "string", "format": "date-time" }, + "componentRef": { "type": "string", "minLength": 1 }, + "bundleOrPackageIdentity": { "type": "string" }, + "manifestDigest": { "type": "string" }, + "verificationVerdict": { "enum": ["valid", "degraded", "missing", "invalid", "quarantined", "unknown"] }, + "registryRecords": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["recordKind", "state"], + "properties": { + "recordKind": { "enum": ["receipt", "extension-record", "extension-point", "broker-record", "package-manifest", "launch-record", "profile-record", "namespace-descriptor", "unknown"] }, + "recordRef": { "type": "string" }, + "state": { "enum": ["present", "missing", "invalid", "stale", "quarantined", "unknown"] }, + "errorCode": { "type": "string" }, + "userVisibleImpact": { "type": "string" }, + "remediationHint": { "type": "string" } + } + } + }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "userVisibleSummary": { "type": "string" }, + "remediationHint": { "type": "string" } + } +} diff --git a/schemas/SecurityVerdictState.json b/schemas/SecurityVerdictState.json new file mode 100644 index 0000000..93dae4b --- /dev/null +++ b/schemas/SecurityVerdictState.json @@ -0,0 +1,82 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/SecurityVerdictState.json", + "title": "SecurityVerdictState", + "description": "A typed state record for security or network-flow verdict availability, including degraded provider states such as no-verdict-provider or policy-unavailable.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "subjectRef", + "decision", + "observedAt", + "verdictProviderState" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:security-verdict:" + }, + "type": { + "const": "SecurityVerdictState" + }, + "specVersion": { + "type": "string" + }, + "subjectRef": { + "type": "string", + "minLength": 1 + }, + "objectRef": { + "type": "string" + }, + "flowRef": { + "type": "string" + }, + "observedAt": { + "type": "string", + "format": "date-time" + }, + "decision": { + "enum": [ + "allow", + "deny", + "ask", + "defer", + "no-verdict", + "unknown" + ] + }, + "verdictProviderState": { + "enum": [ + "ready", + "no-verdict-provider", + "provider-invalid", + "provider-not-ready", + "policy-unavailable", + "evidence-insufficient", + "unknown" + ] + }, + "policyRef": { + "type": "string" + }, + "providerRef": { + "type": "string" + }, + "evidenceRefs": { + "type": "array", + "items": { + "type": "string" + } + }, + "userVisibleImpact": { + "type": "string" + }, + "remediationHint": { + "type": "string" + } + } +}