docs: add helper causal receipts architecture spec

[mdheller]

Summary

Adds the initial Helper Causal Receipts v0.1 architecture spec for SourceOS Shell.

This captures the design response from the macOS unified-log helper-cascade analysis:

• root-intent-bound helper receipts
• declared helper spawn reasons
• capability request/decision receipts
• denial classification
• teardown normalization
• local-only preview policy profiles
• web-thumbnail hostile-content treatment
• native file picker isolation
• terminal preview secret isolation
• user-facing “Why did this run?” inspector requirements

Why this belongs in sourceos-shell

SourceOS Shell is the right runtime/spec home because it is the user-facing shell and receipt/inspector boundary for helper activity across preview, PDF/document rendering, browser integration, terminal integration, and local-first observability.

Downstream repos should align to this contract:

• SourceOS-Linux/BearBrowser: browser file picker, cache cleanup, preview, web thumbnail enforcement
• SourceOS-Linux/TurtleTerm: terminal preview helper isolation and shell-secret denial
• SocioProphet/ontogenesis: ontology + SHACL vocabulary
• SocioProphet/prophet-platform: evidence envelope mapping and CI trust gates

Validation

• Documentation-only PR.
• Local artifact packet produced parser/correlator/fixtures and validation separately.
• Future implementation PRs should add schema, policy YAML, parser/correlator, and CI gates after this architecture contract is accepted.

Follow-up implementation checklist

• Add JSON Schema for sourceos.helper_causal_receipt.v0.1.
• Add policy YAML profiles.
• Add helper wrapper runtime.
• Add receipt store.
• Add “Why did this run?” inspector.
• Add parser/correlator tooling for imported logs.
• Add CI checks for local-only preview invariants.

[mdheller]

Cross-repo implementation trace

This PR is the source architecture contract for Helper Causal Receipts v0.1. Downstream implementation work is now opened across the relevant repos:

• SourceOS Shell PR docs: add helper causal receipts architecture spec #13: architecture contract and runtime home for helper receipts / inspector.
• Implement helper causal receipts for file picker, previews, cache cleanup, and web thumbnails BearBrowser#26: browser file picker, previews, cache cleanup, and web-thumbnail enforcement.
• Implement helper causal receipts for terminal previews and shell-secret isolation TurtleTerm#11: terminal previews and shell-secret isolation.
• Model Helper Causal Receipts ontology and SHACL constraints SocioProphet/ontogenesis#59: ontology, SHACL, classes/properties for helper causal receipts.
• Implement helper causal receipts evidence-envelope mapping and CI gates SocioProphet/prophet-platform#435: evidence-envelope mapping, CI gates, and trust metrics.

Implementation split

• SourceOS Shell owns the canonical event model, parser/correlator tooling, receipt store, and user-facing “Why did this run?” inspector.
• BearBrowser owns browser-side root intents, preview/cache/thumbnail policies, and session/credential isolation.
• TurtleTerm owns terminal preview receipts and shell-secret denial enforcement.
• Ontogenesis owns RDF/OWL/SHACL vocabulary and validation constraints.
• Prophet Platform owns evidence envelopes, policy-regression CI gates, and evidence-console visualization.

Next sourceos-shell artifacts planned on this branch

• JSON Schema for sourceos.helper_causal_receipt.v0.1.
• Service taxonomy and Apple service-family taxonomy.
• Parser/correlator tools for imported unified-log style evidence.
• CI gate script and tests for local-only helper policy invariants.