diff --git a/docs/controller-sovereignty/event-contract.md b/docs/controller-sovereignty/event-contract.md new file mode 100644 index 0000000..5137e5e --- /dev/null +++ b/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: +event_type: ControllerRegistered +timestamp: +host_ref: +controller_id: com.sourceos.example +controller_name: Example Controller +owner_trust_domain: first_party +source: + service: + binary_ref: +policy: + profile: workstation + decision: observed + 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. diff --git a/docs/controller-sovereignty/implementation-backlog.md b/docs/controller-sovereignty/implementation-backlog.md new file mode 100644 index 0000000..65552c4 --- /dev/null +++ b/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. diff --git a/docs/controller-sovereignty/operator-profiles.md b/docs/controller-sovereignty/operator-profiles.md new file mode 100644 index 0000000..54293a1 --- /dev/null +++ b/docs/controller-sovereignty/operator-profiles.md @@ -0,0 +1,110 @@ +# Controller Operator Profiles + +Operator profiles define what autonomous controllers may do under a given machine posture. + +The profile is not a convenience setting. It is a sovereignty boundary: it determines whether background controllers may consume resources, touch local state, use network surfaces, or run while idle. + +## Profile matrix + +| Capability | Workstation | Investigation | Personal | Maintenance | +|---|---:|---:|---:|---:| +| Metadata indexing | budgeted | restricted | allowed | allowed | +| Media analysis | restricted | blocked by default | allowed | allowed | +| Cloud photo sync | explicit | blocked by default | allowed | allowed | +| Filesystem traversal | budgeted | observed only | budgeted | allowed | +| Peer wireless | explicit | blocked by default | allowed | explicit | +| Network tunnels | explicit | explicit | allowed | explicit | +| Application updaters | maintenance window | blocked by default | allowed | allowed | +| Platform update | explicit | explicit | allowed | allowed | +| Low-power network presence | explicit | blocked by default | allowed | explicit | +| Private cloud compute | explicit | blocked by default | allowed | explicit | + +## Workstation profile + +Goal: stable development and daily work. + +Defaults: + +- Indexing is allowed only under budget. +- Generated directories and high-churn build outputs should be excluded from indexing. +- Media analysis is restricted. +- Cloud sync is allowed only for declared paths or services. +- Peer wireless is explicit rather than ambient. +- Update work is scheduled into a maintenance window. + +Required events: + +- `ControllerBudgetObserved` +- `ControllerBudgetExceeded` +- `ControllerEnteredIdleWork` +- `ControllerExitedIdleWork` + +## Investigation profile + +Goal: evidence preservation and minimal ambient mutation. + +Defaults: + +- Cloud/media analysis is blocked by default. +- Metadata indexing is restricted or paused unless explicitly allowed. +- Peer wireless and low-power network presence are blocked by default. +- Network extensions and tunnels must be visible. +- Raw outputs remain local and are summarized before they enter a repository. + +Required events: + +- `ControllerOpenedNetworkSurface` +- `ControllerTouchedResourceClass` +- `ControllerPolicyChanged` + +## Personal profile + +Goal: ordinary convenience with budget visibility. + +Defaults: + +- Cloud sync is allowed. +- Media analysis is allowed. +- Metadata indexing is allowed. +- Background work is still budgeted and visible. +- Budget excess produces user-visible explanation. + +Required events: + +- `ControllerBudgetObserved` +- `ControllerBudgetExceeded` + +## Maintenance profile + +Goal: deliberate system maintenance. + +Defaults: + +- Updates may run. +- Index rebuilds may run. +- Filesystem maintenance may run. +- Cloud repair jobs may run only if explicitly selected. +- Profile has a start and end time. + +Required events: + +- `ControllerPolicyChanged` +- `ControllerEnteredIdleWork` +- `ControllerExitedIdleWork` + +## Profile transition rule + +A profile transition must be explicit, durable, and auditable. SourceOS must record: + +- previous profile +- new profile +- actor that changed it +- reason +- timestamp +- controllers whose effective capabilities changed + +## Product requirement + +A user should be able to answer this question at any moment: + +> Which profile is active, which controllers gained authority from it, and what budget remains?