docs: add helper causal receipts architecture spec

[mdheller]

Summary

Adds the Helper Causal Receipts v0.1 architecture contract plus the first reviewable implementation skeleton 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

Included in this PR

• Architecture contract:
  • docs/architecture/helper-causal-receipts-v0.1.md
• Event schema:
  • schemas/helper-causal-receipts.schema.json
• Taxonomies/policies:
  • policies/helper-receipts/service_taxonomy.v0.1.yaml
  • policies/helper-receipts/apple_service_family_taxonomy.v0.1.yaml
• Tools:
  • tools/check_helper_receipts.py
  • tools/unified_log_helper_parser.py
  • tools/unified_log_helper_correlator.py
• Tests/fixtures:
  • tests/test_unified_log_helper_parser.py
  • tests/test_unified_log_helper_correlator.py
  • tests/fixtures/helper-receipts/*.json

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

Cross-repo implementation trace

• SourceOS-Linux/BearBrowser#26
• SourceOS-Linux/TurtleTerm#11
• SocioProphet/ontogenesis#59
• SocioProphet/prophet-platform#435

Validation commands

python -m pytest tests/test_unified_log_helper_parser.py tests/test_unified_log_helper_correlator.py
python tools/check_helper_receipts.py tests/fixtures/helper-receipts/preview_local_only_pass.json tests/fixtures/helper-receipts/web_thumbnail_pass_clipboard_denied.json
python tools/check_helper_receipts.py tests/fixtures/helper-receipts/preview_local_only_fail_network_allowed.json || true
python tools/check_helper_receipts.py tests/fixtures/helper-receipts/helper_spawn_missing_root_intent_fail.json || true

Notes

Generated evidence artifacts from the local analysis packet are intentionally not committed here. This PR lands the normative contract, lightweight parser/correlator tooling, policy taxonomies, CI gate, and fixtures only.

[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.