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.

[mdheller]

Partial capture update.

Merged #20 / 86a21b0d056ae5db88c55ffa50835d6d7c0e9a78 as a current-main replay of the core machine-checkable Helper Causal Receipts gate.

Captured in #20:

• schemas/helper-causal-receipts.schema.json
• tools/check_helper_receipts.py
• positive helper receipt fixtures
• negative local-only and missing-intent fixtures
• focused Helper Causal Receipts workflow

Validation observed on #20 head 39ccb3d4d76050ac4167e6cf7cf5189c6e5e676f:

• Helper Causal Receipts: success

Remaining from this PR and intentionally not closed yet:

• docs/architecture/helper-causal-receipts-v0.1.md
• policies/helper-receipts/service_taxonomy.v0.1.yaml
• policies/helper-receipts/apple_service_family_taxonomy.v0.1.yaml
• tools/unified_log_helper_parser.py
• tools/unified_log_helper_correlator.py
• parser/correlator unit tests

Reason: the raw parser/test payload includes unified-log pattern material that should be replayed separately and carefully; #20 captured the core schema/fixture gate without losing the remaining tranche.

[mdheller]

Final capture update.

Helper Causal Receipts v0.1 is now fully captured on current main across #20 and #21.

Merged #20 / 86a21b0d056ae5db88c55ffa50835d6d7c0e9a78:

• schemas/helper-causal-receipts.schema.json
• tools/check_helper_receipts.py
• positive helper receipt fixtures
• negative local-only and missing-intent fixtures
• focused Helper Causal Receipts workflow

Merged #21 / d4f30ffb3b8157bc4cff425558007856fc50be5a:

• docs/architecture/helper-causal-receipts-v0.1.md
• policies/helper-receipts/service_taxonomy.v0.1.yaml
• policies/helper-receipts/apple_service_family_taxonomy.v0.1.yaml
• tools/unified_log_helper_parser.py
• tools/unified_log_helper_correlator.py
• parser/correlator tests
• focused Helper Causal Parser workflow

Validation observed:

• Replay helper causal receipts core gate on current main #20 head 39ccb3d4d76050ac4167e6cf7cf5189c6e5e676f: Helper Causal Receipts success.
• Replay helper causal receipts follow-up on current main #21 head bde36c0d7db0deafb8f1d5d29c234c9eeda4db64: Helper Causal Parser success; PDF Runtime Scaffold success.

Content status: fully captured. This stale PR can be closed as superseded.