Spec: Mutation and Evidence Accountability v0.1

.github/workflows/mutation-evidence-accountability.yml

@@ -0,0 +1,40 @@
+name: Mutation Evidence Accountability
+
+on:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "schemas/MutationEvidence*.json"
+      - "examples/mutation-evidence*.json"
+      - "fixtures/anti-patterns/mutation-evidence*.json"
+      - "tools/validate_mutation_evidence_accountability.py"
+      - ".github/workflows/mutation-evidence-accountability.yml"
+  push:
+    branches: ["main", "sourceos-mutation-evidence-v0-1"]
+    paths:
+      - "schemas/MutationEvidence*.json"
+      - "examples/mutation-evidence*.json"
+      - "fixtures/anti-patterns/mutation-evidence*.json"
+      - "tools/validate_mutation_evidence_accountability.py"
+      - ".github/workflows/mutation-evidence-accountability.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  validate-mutation-evidence:
+    name: Validate mutation/evidence receipts
+    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 examples and anti-pattern fixtures
+        run: python tools/validate_mutation_evidence_accountability.py

docs/adr/0012-sourceos-mutation-evidence-accountability.md

@@ -0,0 +1,70 @@
+# ADR-0012: SourceOS Mutation and Evidence Accountability
+
+Status: Proposed
+Date: 2026-05-05
+
+## Context
+
+A multi-artifact forensic review of macOS resource, syslog, console, Wi-Fi, and memorystatus reports exposed a recurring operating-system design failure: modern systems may enforce policy and collect telemetry while still failing to explain causality to the human operator.
+
+The reviewed evidence showed repeated browser disk-write pressure, browser process-family memory pressure, sandbox/TCC denials, watchdog coverage gaps, launchd/XPC service churn, Spotlight/indexing worker churn, opaque log-routing, media/codec diagnostic chatter, and weak continuity across shutdown, boot, login, and logging-service restart boundaries.
+
+The security conclusion is intentionally conservative: the available logs do not prove compromise, but they are not sufficient to clear compromise either. Several sensors were degraded or semantically incomplete. SourceOS must treat opaque or degraded telemetry as an evidence-quality failure, not as negative evidence.
+
+## Decision
+
+SourceOS will adopt a receipt-native accountability model for mutation, evidence routing, service lifecycle, resource pressure, media work, temporary artifacts, policy denials, and compromise assessment.
+
+The canonical specification home is this repository, `SourceOS-Linux/sourceos-spec`, using the existing layout:
+
+- `docs/adr/` for architectural decisions.
+- `docs/contract-additions/` for normative contracts.
+- `schemas/` for JSON schemas.
+- `examples/` for valid examples.
+- `fixtures/` for invalid or degraded anti-pattern examples.
+- `tools/` for schema validation and CI checks.
+
+Implementation should fan out only after this contract is stable:
+
+- `SourceOS-Linux/sourceos-boot`: boot evidence topology attestation and cross-reboot session IDs.
+- `SourceOS-Linux/sourceos-devtools`: validators, CLI tooling, CI gates, and synthetic anti-pattern fixtures.
+- `SourceOS-Linux/sourceos-shell`: operator timeline, evidence panel, and `sourceosctl explain` flows.
+- `SourceOS-Linux/BearBrowser`: browser coalition/profile/storage/write receipts.
+- `SourceOS-Linux/TurtleTerm`: terminal/session/UI-observation receipts.
+- `SourceOS-Linux/sourceos-syncd`: sync-cycle receipts, full-sync risk receipts, and temporary artifact budgets.
+
+## Required event families
+
+- `sourceos.observability.event.v0.1`
+- `sourceos.write_accountability.v0.1`
+- `sourceos.routing_receipt.v0.1`
+- `sourceos.media_work.v0.1`
+- `sourceos.temporary_artifact.v0.1`
+- `sourceos.coalition_resource.v0.1`
+- `sourceos.policy_decision.v0.1`
+- `sourceos.compromise_assessment.v0.1`
+
+## Consequences
+
+Every relevant subsystem must preserve enough evidence to answer:
+
+1. What happened?
+2. Who or what caused it?
+3. Which durable or temporary object changed?
+4. Which policy allowed, denied, degraded, sampled, redacted, routed, or dropped the event?
+5. What resource budget was consumed?
+6. What evidence was missing or degraded?
+7. What downstream work or risk was created?
+8. What should the user or operator do next?
+
+## Non-goals
+
+This ADR does not attempt to prove compromise in the reviewed macOS artifacts. It uses them as design evidence. It also does not require raw sensitive paths or network identifiers in default logs. SourceOS should use privacy-preserving object IDs by default and support explicit forensic expansion only when authorized.
+
+## Acceptance criteria
+
+- A base observability event schema exists and validates examples.
+- Mutation/write accountability, evidence routing, media work, temporary artifact lifecycle, coalition resource, policy decision, and compromise assessment schemas exist.
+- Valid examples and invalid anti-pattern fixtures are provided.
+- A local validator checks valid examples pass and anti-pattern fixtures fail.
+- Documentation explicitly states that lack of positive evidence is not clearance when sensors are degraded or evidence quality is insufficient.

docs/contract-additions/browser-write-accountability.md

@@ -0,0 +1,60 @@
+# SourceOS Browser Write Accountability v0.1
+
+## Purpose
+
+This contract specializes SourceOS Mutation and Evidence Accountability for browser write-pressure incidents.
+
+The Firefox evidence from the macOS investigation showed repeated SQLite-backed profile/storage writes, but a later Add-ons Manager screenshot showed no visible installed extensions. That correction matters: extension-driven write amplification must be downgraded unless an extension inventory actually supports it.
+
+## Decision
+
+Browser write-pressure receipts must distinguish user-installed extension storage from browser-core profile state, per-origin storage, service-worker/cache state, session restore, browser sync, downloads/cache, diagnostics, and profile repair or migration.
+
+A browser write-pressure incident must not blame extensions merely because the browser wrote heavily.
+
+## Required actor classes
+
+- `browser_profile_core`
+- `browser_history_places`
+- `browser_favicons`
+- `browser_cookies_permissions`
+- `browser_session_restore`
+- `browser_origin_storage`
+- `browser_service_worker_cache`
+- `browser_download_cache`
+- `browser_sync_state`
+- `browser_extension_storage`
+- `browser_hidden_system_addon`
+- `browser_diagnostics`
+- `browser_profile_repair_or_migration`
+- `unknown`
+
+## Extension inventory states
+
+- `none_visible`: no user-installed extensions visible in the ordinary extension manager view.
+- `installed`: visible user-installed extensions exist.
+- `hidden_possible`: system, policy, hidden, or native-messaging add-ons may exist but were not fully enumerated.
+- `unavailable`: the extension inventory could not be collected.
+- `not_collected`: no extension inventory evidence was captured.
+
+## Normative rule
+
+If `extension_inventory_state=none_visible`, then `browser_extension_storage` must not be used as the primary actor class unless additional hidden/system/policy add-on evidence is attached.
+
+## Evidence-quality rule
+
+A complete browser-write receipt requires at minimum:
+
+- Browser/version/profile identifier.
+- Actor class.
+- Extension inventory state.
+- Operation class.
+- Object class and path class.
+- Byte count or write-pressure budget.
+- Evidence-quality status and missing fields.
+
+A report with only process name, stack offsets, and syscall class is partial evidence.
+
+## Design consequence
+
+SourceOS/BearBrowser must expose browser storage accountability by profile component and origin. The user should see whether writes came from core profile state, site/origin storage, service workers, downloads/cache, sync state, extensions, diagnostics, or migration/repair logic.

docs/contract-additions/mutation-evidence-accountability.md

@@ -0,0 +1,97 @@
+# SourceOS Mutation and Evidence Accountability v0.1
+
+## Purpose
+
+This contract defines the minimum evidence model for mutation, resource pressure, policy denials, evidence routing, media/codec work, temporary artifacts, service lifecycle, and compromise assessment in SourceOS.
+
+The design motivation is a repeated failure pattern observed in opaque macOS logs: low-level mechanisms recorded fragments of truth, but no layer provided a complete causal explanation. SourceOS must make mutation and evidence accountable by default.
+
+## Normative principles
+
+1. **Receipts over loose logs.** Events that mutate state, consume resource budgets, change evidence routing, or degrade security coverage must emit structured receipts.
+2. **No degraded sensor may clear an incident.** Absence of evidence from a degraded sensor is not negative evidence.
+3. **Report by actor, object, operation, policy, cost, and cause.** Process name alone is not attribution.
+4. **Report by coalition and service class.** Browsers, office stacks, indexers, sync agents, and model services are multi-process families.
+5. **Every denial needs a classification.** A denial can be expected, expected-but-degraded, misconfigured, suspicious, impossible, or unknown.
+6. **Retry and activation storms must circuit-break.** Repeated failures must be summarized with counts, first/last timestamps, backoff state, and remediation.
+7. **Logs are governed artifacts.** Routed, sampled, dropped, redacted, compressed, or diverted log streams must themselves have routing receipts.
+8. **Temporary artifacts are typed.** Codec scratch files, previews, thumbnails, sync staging, caches, and owned media must not collapse into one path class.
+9. **Cross-reboot continuity is mandatory.** Boot sessions, shutdowns, restarts, login sessions, and logging topology changes require stable correlation IDs.
+10. **Evidence quality is explicit.** Each incident must expose what is known, unknown, degraded, redacted, or insufficient.
+
+## Required event families
+
+- `sourceos.observability.event.v0.1`
+- `sourceos.write_accountability.v0.1`
+- `sourceos.routing_receipt.v0.1`
+- `sourceos.media_work.v0.1`
+- `sourceos.temporary_artifact.v0.1`
+- `sourceos.coalition_resource.v0.1`
+- `sourceos.policy_decision.v0.1`
+- `sourceos.compromise_assessment.v0.1`
+
+## Minimum event envelope
+
+Every receipt must include:
+
+- `schema`
+- `event_id`
+- `timestamp`
+- `boot_id`
+- `session_id`
+- `actor`
+- `operation`
+- `policy`
+- `evidence_quality`
+- `causal_parents`
+
+## Required evidence-quality states
+
+- `complete`
+- `partial`
+- `degraded_sensor`
+- `opaque_symbolication`
+- `redacted`
+- `insufficient_for_clearance`
+
+## Required compromise-assessment states
+
+- `compromise_proven`
+- `compromise_suspected`
+- `no_positive_compromise_evidence`
+- `cannot_exclude_compromise`
+- `sensor_degraded`
+- `evidence_inadequate`
+
+## Required artifact classes
+
+- `owned_media`
+- `durable_document`
+- `derived_preview`
+- `codec_temp`
+- `attachment_cache`
+- `thumbnail_cache`
+- `sync_staging`
+- `failed_transcode_residue`
+- `message_database_reference`
+- `browser_profile_db`
+- `browser_cache`
+- `semantic_index`
+- `opaque_vendor_state`
+
+## Required operator queries
+
+A SourceOS operator view must be able to answer:
+
+- Explain writes.
+- Explain logs and evidence routing.
+- Explain memory and coalition pressure.
+- Explain sync/reindex/full-sync risks.
+- Explain policy denials.
+- Explain degraded security coverage.
+- Explain media/temp artifacts.
+- Explain why compromise can or cannot be excluded.
+
+## Initial repo placement
+
+This contract belongs in `SourceOS-Linux/sourceos-spec` under `docs/contract-additions/mutation-evidence-accountability.md`. Implementation should be fanned out only after the contract and schema fixtures are validated.