Spec: Mutation and Evidence Accountability v0.1

[mdheller]

Summary

This draft PR adds the first SourceOS Mutation and Evidence Accountability specification slice.

It includes:

• ADR-0012: SourceOS Mutation and Evidence Accountability.
• A normative contract addition for mutation/evidence accountability.
• A browser-write-accountability contract with a no-visible-extension attribution guardrail.
• A stack integration map connecting the lessons to BearBrowser, TurtleTerm, SourceOS Shell, sourceos-syncd, sourceos-devtools, sourceos-boot, Exodus, FogStack/Prophet Platform, and ontogenesis.
• A base JSON Schema bundle covering observability events, write accountability, evidence routing, media work, temporary artifacts, coalition resource accounting, policy decisions, and compromise assessment.
• A second umbrella primitive schema: MutationReceipt, ExecutionContextReceipt, ServiceWorkReceipt, and EvidencePipelineReceipt, with specialized subtypes for browser writes, delegated I/O, sync cycles, folder sizing, archive extraction, diagnostic self-noise, UI/compositor work, path boundaries, evidence routing, and related receipt families.
• Valid examples for base receipts and umbrella primitives.
• Anti-pattern fixtures for missing routing counts, false clearance when a sensor is blind, extension-primary attribution without inventory support, delegated mutation without a full actor chain, diagnostic observer-effect clearance, and archive extraction without path-boundary/cleanup accounting.
• A validator that checks both schema bundles plus semantic guardrails.
• A dedicated GitHub Actions workflow: Mutation Evidence Accountability.

Motivation

This is based on the forensic design review of opaque OS logs. The core lesson is that an OS can enforce policy, collect telemetry, and still fail the operator if it cannot explain actor, object, operation, policy, resource cost, causality, delegated mutation, execution context, and evidence gaps.

The key security doctrine captured here is:

Absence of evidence from a degraded or incomplete sensor is not negative evidence.

The Firefox extension-inventory correction is also captured:

Browser write pressure must not be attributed to extension storage when the visible extension inventory is empty unless hidden/system/policy add-on evidence is attached.

The broader stack doctrine is:

SourceOS should explain mutation as a graph, not as isolated process logs. Mutation includes writes, clones, renames, unlinks, chmod/xattrs, WAL checkpoints, cache maintenance, archive extraction, diagnostic observer effects, delegated sync, UI/compositor work, and evidence routing.

Validation

GitHub Actions is passing on the latest head commit.

• Workflow: Mutation Evidence Accountability
• Run: docs: clarify repo topology and semantic role #3
• Conclusion: success
• Head SHA: 3b27da4bf00f7a614a4cdb942e131015f9b8be67

The validator now covers:

• base examples and anti-patterns;
• umbrella primitive examples and anti-patterns;
• no-visible-extension browser attribution guardrails;
• delegated I/O actor-chain completeness;
• diagnostic observer-effect clearance blocking;
• archive extraction path-boundary and cleanup accounting;
• blind/degraded/missing sensor compromise-clearance blocking.

Follow-up implementation targets

After this spec lands, implementation should fan out to:

• SourceOS-Linux/BearBrowser for browser coalition/profile/storage/origin receipts and no-extension attribution guardrails.
• SourceOS-Linux/TurtleTerm for terminal/session/archive/diagnostic mutation receipts.
• SourceOS-Linux/sourceos-shell for sourceosctl explain, evidence topology, and mutation graph UI.
• SourceOS-Linux/sourceos-syncd for delegated sync, full-sync-risk, scheduler, object-transfer, and temp-artifact receipts.
• SourceOS-Linux/sourceos-devtools for validators, CLI tooling, CI gates, and anti-pattern fixtures.
• SourceOS-Linux/sourceos-boot for boot evidence topology and cross-reboot session IDs.
• SocioProphet/prophet-platform for evidence-console and FogStack manifest integration.
• ontogenesis for ontology classes and SHACL gates.
• Exodus for migration artifact taxonomy and temp/cache exclusion logic.

Notes

This PR intentionally lands the contract first. It does not yet implement runtime instrumentation.

[mdheller]

Downstream implementation map created

The canonical spec slice in this PR now has downstream implementation issues across the stack:

• BearBrowser: Implement browser write accountability receipts BearBrowser#28
• TurtleTerm: Implement terminal mutation and archive extraction receipts TurtleTerm#12
• SourceOS Shell: Add sourceosctl explain and evidence topology views sourceos-shell#15
• sourceos-syncd: Implement delegated sync and full-sync-risk receipts sourceos-syncd#18
• sourceos-devtools: Wire mutation/evidence validator and fixture generators into devtools sourceos-devtools#25
• sourceos-boot: Emit boot evidence topology attestation sourceos-boot#24
• Prophet Platform / FogStack evidence console: Integrate Mutation and Evidence Accountability into evidence console and FogStack manifests SocioProphet/prophet-platform#441
• Ontogenesis ontology + SHACL gates: Model Mutation and Evidence Accountability ontology and SHACL gates SocioProphet/ontogenesis#60
• Exodus migration artifact taxonomy: Implement migration artifact taxonomy and accountable import/export receipts SocioProphet/exodus#12

Current validation status:

• Dedicated workflow: Mutation Evidence Accountability
• Latest run checked: docs: clarify repo topology and semantic role #3
• Conclusion: success
• Head SHA validated: 3b27da4bf00f7a614a4cdb942e131015f9b8be67

The PR remains draft only because the connector call to mark ready-for-review hit a GitHub GraphQL field-shape bug. Content-wise, this slice is ready for review as a contract-first spec package, with runtime implementation delegated to the issues above.