controller-sovereignty-contract-20260603

docs/controller-sovereignty/event-contract.md

@@ -0,0 +1,165 @@
+# Controller Event Contract
+
+This document defines the first SourceOS controller-sovereignty event vocabulary. The goal is to make autonomous system behavior attributable, budgeted, and explainable.
+
+A controller event is a durable record that says who acted, what authority was used, what resource class was touched, and what policy state resulted.
+
+## Event envelope
+
+```yaml
+event_id: <stable-event-id>
+event_type: ControllerRegistered
+timestamp: <rfc3339>
+host_ref: <redacted-host-ref>
+controller_id: com.sourceos.example
+controller_name: Example Controller
+owner_trust_domain: first_party
+source:
+  service: <service-name>
+  binary_ref: <redacted-binary-ref>
+policy:
+  profile: workstation
+  decision: observed
+  reason: <human-readable reason>
+privacy:
+  contains_private_payload: false
+  redaction_level: summarized
+```
+
+## Required event types
+
+### ControllerRegistered
+
+Emitted when a controller becomes known to the system registry.
+
+Required fields:
+
+- `controller_id`
+- `controller_name`
+- `owner_trust_domain`
+- `declared_capabilities`
+- `declared_budgets`
+
+### ControllerCapabilityDeclared
+
+Emitted when a controller declares or changes an authority surface.
+
+Capability classes:
+
+- `network.physical_interface`
+- `network.peer_interface`
+- `network.tunnel`
+- `network.proxy`
+- `network.low_power_presence`
+- `storage.file_read`
+- `storage.file_write`
+- `storage.database_mutation`
+- `storage.indexing`
+- `storage.filesystem_traversal`
+- `cloud.sync`
+- `cloud.push`
+- `cloud.private_compute`
+- `compute.cpu`
+- `compute.gpu`
+- `compute.accelerator`
+- `power.idle_work`
+- `power.sleep_work`
+
+### ControllerBudgetObserved
+
+Emitted when a controller consumes a measured budget interval without crossing a limit.
+
+Required fields:
+
+- `budget_class`
+- `observed_amount`
+- `budget_window`
+- `policy_profile`
+
+### ControllerBudgetExceeded
+
+Emitted when a controller exceeds a declared budget.
+
+Required fields:
+
+- `budget_class`
+- `observed_amount`
+- `configured_limit`
+- `budget_window`
+- `platform_response`
+- `recommended_user_action`
+
+### ControllerTouchedResourceClass
+
+Emitted when a controller touches a class of local state.
+
+Resource classes:
+
+- `user_documents`
+- `media_library`
+- `metadata_index`
+- `filesystem_metadata`
+- `application_cache`
+- `cloud_sync_database`
+- `network_configuration`
+- `wireless_radio_state`
+- `security_policy_state`
+
+### ControllerOpenedNetworkSurface
+
+Emitted when a controller opens or observes a network surface.
+
+Surface classes:
+
+- `physical_interface`
+- `peer_wireless_interface`
+- `tunnel_interface`
+- `proxy_service`
+- `name_resolution`
+- `push_channel`
+- `local_discovery`
+- `service_proxy`
+
+### ControllerEnteredIdleWork
+
+Emitted when a controller begins work while the user is not actively foregrounding that controller.
+
+Required fields:
+
+- `controller_id`
+- `idle_state`
+- `declared_reason`
+- `expected_duration`
+- `budget_ref`
+
+### ControllerExitedIdleWork
+
+Emitted when an idle work interval completes.
+
+Required fields:
+
+- `controller_id`
+- `duration`
+- `resource_summary`
+- `completion_state`
+
+### ControllerPolicyChanged
+
+Emitted when the effective policy profile changes for a controller.
+
+Required fields:
+
+- `previous_profile`
+- `new_profile`
+- `changed_by`
+- `reason`
+
+## Interpretation rule
+
+Raw telemetry is not the product. The product is a stable diagnosis beside the raw signal. Every event should support an operator narrative:
+
+> Controller X used capability Y under policy Z, consumed resource R, and left residual risk Q.
+
+## Privacy rule
+
+Controller events should be useful without exposing private payloads. Store file classes, service classes, redacted references, and aggregate resource amounts by default. Raw local artifacts stay local unless explicitly exported through a redaction workflow.

docs/controller-sovereignty/implementation-backlog.md

@@ -0,0 +1,165 @@
+# Controller Sovereignty Implementation Backlog
+
+This backlog converts the controller-sovereignty doctrine into implementable SourceOS work.
+
+## P0 — Contract hardening
+
+### CS-P0-001: Event envelope fixture
+
+Create canonical JSON fixtures for the event envelope.
+
+Acceptance:
+
+- Contains one valid fixture for each required event type.
+- Fixtures contain no private local data.
+- Fixtures are schema-checkable.
+
+### CS-P0-002: Controller registry fixture
+
+Create sample controller registry entries for:
+
+- metadata indexer
+- media analyzer
+- filesystem maintainer
+- wireless policy controller
+- application updater
+- network policy extension
+
+Acceptance:
+
+- Each fixture declares owner, capabilities, budgets, allowed states, and observability fields.
+- Fixtures are redacted and synthetic.
+
+### CS-P0-003: Case-file exemplar
+
+Create a synthetic case-file exemplar showing a budget-exceeded metadata controller.
+
+Acceptance:
+
+- No real hostnames, device identifiers, user paths, or diagnostic records.
+- Includes user-control gap and SourceOS design requirement.
+
+## P1 — Parser to event mapper
+
+### CS-P1-001: Map resource summary rows to controller events
+
+Extend the summary parser so each row can be converted into a candidate SourceOS event.
+
+Acceptance:
+
+- Disk-write rows map to `ControllerBudgetObserved` or `ControllerBudgetExceeded`.
+- CPU rows map to `ControllerBudgetObserved` or `ControllerBudgetExceeded`.
+- Unknown controller rows map to `Unclassified` with explicit confidence.
+- Raw private evidence is not emitted by default.
+
+### CS-P1-002: Add confidence and classification fields
+
+Add confidence fields to parsed records.
+
+Acceptance:
+
+- controller confidence
+- stack-family confidence
+- evidence confidence
+- privacy redaction level
+
+### CS-P1-003: Add synthetic unit fixtures
+
+Add local synthetic report snippets for parser tests.
+
+Acceptance:
+
+- No private logs.
+- Includes representative Spotlight, Photos, APFS, Wireless, and updater cases.
+
+## P2 — Controller registry integration
+
+### CS-P2-001: Registry loader
+
+Build a loader for controller registry YAML documents.
+
+Acceptance:
+
+- Validates required fields.
+- Reports missing budgets and undeclared capabilities.
+- Produces normalized controller records.
+
+### CS-P2-002: Capability diff
+
+Compare observed event capabilities against declared controller capabilities.
+
+Acceptance:
+
+- Emits an advisory when a controller uses an undeclared capability.
+- Emits an advisory when a controller acts outside allowed states.
+
+### CS-P2-003: Budget evaluator
+
+Evaluate event streams against declared budgets.
+
+Acceptance:
+
+- Supports CPU, disk-write, memory, and network budget classes.
+- Produces budget state: within_budget, near_limit, exceeded, unknown.
+
+## P3 — Dashboard prototype
+
+### CS-P3-001: Terminal dashboard
+
+Build a terminal-first sovereignty dashboard.
+
+Acceptance:
+
+- Groups events by controller class.
+- Shows current policy profile.
+- Shows last event, budget state, and recommended action.
+
+### CS-P3-002: Profile simulation
+
+Simulate Workstation, Investigation, Personal, and Maintenance profiles against an event stream.
+
+Acceptance:
+
+- Shows which events would be allowed, blocked, budgeted, or escalated.
+- Produces a human-readable explanation.
+
+## P4 — SourceOS runtime bridge
+
+### CS-P4-001: SourceOS State Integrity Report extension
+
+Extend the State Integrity Report model to include controller-sovereignty summaries.
+
+Acceptance:
+
+- Report includes controller counts, budget state, recent violations, and active profile.
+- Report remains local-first and suitable for signed evidence.
+
+### CS-P4-002: PolicyFabric bridge
+
+Define how PolicyFabric consumes controller events and profiles.
+
+Acceptance:
+
+- Specifies policy inputs and outputs.
+- Distinguishes observation, advisory, budget enforcement, and operator approval.
+
+### CS-P4-003: Lampstand evidence bridge
+
+Define which controller events should become signed evidence.
+
+Acceptance:
+
+- Budget exceeded events are eligible.
+- Profile transitions are eligible.
+- Raw private artifacts are not stored by default.
+
+## Done criteria
+
+The controller-sovereignty lane is minimally complete when SourceOS can:
+
+1. Register controllers.
+2. Declare capabilities and budgets.
+3. Summarize local events without private payloads.
+4. Evaluate budget state.
+5. Explain user-control gaps.
+6. Emit a State Integrity Report section for controller sovereignty.