security/radio-spatial-context-receipts

docs/contract-additions/radio-spatial-derived-context.md

@@ -0,0 +1,93 @@
+# Radio-Spatial, Learned Location, and Home Context Boundaries
+
+Status: additive security-contract placement note.
+
+## Summary
+
+SourceOS treats radio-spatial context as high-sensitivity derived personal data.
+
+This boundary covers Wi-Fi RSSI/LQM, BSSID/AP observations, Bluetooth proximity, AWDL/Nearby discovery, Wi-Fi ranging capability, motion/PDR hints, micro-location, visit/routine inference, known-place state, HomeKit service-area state, Matter/Thread topology, and IntelligencePlatform-style derived context views.
+
+The motivating forensic evidence showed a same-evening local chain across Wi-Fi signal telemetry, Wi-Fi positioning, nearby/ranging discovery, CoreRoutine/routined learned-location state, HomeKit/assistant access, model asset handling, and IntelligencePlatform knowledge maintenance. The evidence supports a radio-spatial learned-location substrate. It does not, by itself, prove a direct Wi-Fi -> ANE -> room-map causal path.
+
+## Security rule
+
+Radio-spatial context is personal context.
+
+A trustworthy OS must expose receipts for:
+
+1. signal collection,
+2. location/routine/home derivation,
+3. model or heuristic use,
+4. protected or shared storage,
+5. cloud or mirroring behavior,
+6. export,
+7. retention,
+8. deletion, and
+9. user revocation.
+
+The user must not need to inspect private SQLite databases, protected plist stores, or opaque system logs to know whether radio-spatial derived context exists.
+
+## Claim discipline
+
+SourceOS receipts distinguish four different claims:
+
+- **subsystem present**: code paths, stores, schemas, or preferences exist;
+- **current visible activity**: counters, timestamps, logs, or receipts show activity in a known window;
+- **causal bridge proven**: the output of one stage is tied to the input of another stage;
+- **derived artifact found**: a room, home, routine, graph, or other derived object is identified.
+
+A zero current counter does not erase a subsystem. It only limits the claim about current activity.
+
+## Required receipt family
+
+This placement note introduces the following additive schemas:
+
+- `RadioSpatialSignalReceipt`
+- `RadioSpatialInferenceReceipt`
+- `LearnedLocationReceipt`
+- `RadioPOIReceipt`
+- `RoutineSchedulerReceipt`
+- `RadioSpatialModelAssetReceipt`
+- `RadioSpatialCorrelationReceipt`
+- `ProtectedContextStoreReceipt`
+
+Together these receipts capture signal collection, inferred location/routine/home context, model asset use, scheduled routine jobs, correlation windows, and protected stores.
+
+## Required user-visible controls
+
+The SourceOS shell should expose a Context Receipts surface showing:
+
+- radio-spatial signals collected,
+- inferred locations, visits, known places, and routines,
+- Home/Matter/Thread state used for inference,
+- model assets used,
+- local versus cloud/private compute boundaries,
+- shared containers and preference domains touched,
+- protected stores created,
+- cloud/mirroring state,
+- deletion and revocation status.
+
+## Integration points
+
+This boundary must compose with:
+
+- visual/OCR derived-context receipts,
+- shared-state and group-container receipts,
+- connector/tool-permission receipts,
+- model-asset receipts,
+- private-cloud and partner-compute receipts,
+- agent session and tool-call receipts.
+
+## Acceptance tests
+
+- A Wi-Fi-derived location fix emits `RadioSpatialSignalReceipt` and `RadioSpatialInferenceReceipt`.
+- Known-place identifiers are exported only as hashes or presence flags unless the user explicitly exports raw values.
+- BluePOI-like subsystem keys with zero counters produce `currentSnapshotActivity: inactive_or_zero_counter`.
+- Model asset use for motion/location/routine inference emits `RadioSpatialModelAssetReceipt`.
+- A protected context store emits `ProtectedContextStoreReceipt` even when raw contents are unavailable.
+- Deleting a source signal or source object deletes or tombstones derived radio-spatial context.
+
+## Non-goals
+
+This note does not define a vendor-specific Apple compatibility layer. It defines the open SourceOS receipt model we require from any implementation that collects or derives radio-spatial context.

schemas/RadioSpatialActivationReceipt.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RadioSpatialActivationReceipt.json",
+  "title": "RadioSpatialActivationReceipt",
+  "description": "Receipt proving radio-spatial intelligence was intentionally activated, scoped, and made visible to the user before collecting or deriving device, mesh, network, Home, or location context.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "capability",
+    "activationMode",
+    "scope",
+    "allowedDerivations",
+    "deniedDerivations",
+    "userVisible",
+    "revocation"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:receipt:radio-spatial-activation:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:receipt:radio-spatial-activation:<local-id>"
+    },
+    "type": {
+      "const": "RadioSpatialActivationReceipt",
+      "description": "Discriminator constant."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. 2.1.0."
+    },
+    "capability": {
+      "const": "radio_spatial_intelligence",
+      "description": "Capability activated by this receipt."
+    },
+    "activationMode": {
+      "type": "string",
+      "enum": ["user_enabled", "scheduled_diagnostic", "emergency", "admin_policy", "disabled"],
+      "description": "How the capability was activated."
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["location", "duration", "signalSources"],
+      "properties": {
+        "location": {
+          "type": "string",
+          "enum": ["home", "office", "lab", "travel", "custom", "unknown"],
+          "description": "User-visible site or environment scope."
+        },
+        "duration": {
+          "type": "string",
+          "description": "Activation duration, ISO 8601 interval, or policy label."
+        },
+        "signalSources": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "enum": ["wifi", "bluetooth", "awdl", "thread", "matter", "homekit", "motion", "location", "uwb", "other"]
+          },
+          "description": "Signal sources allowed under this activation."
+        }
+      }
+    },
+    "allowedDerivations": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["dead_zone_detection", "device_presence", "mesh_health", "rogue_device_detection", "room_inference", "automation_context", "home_topology", "routine_detection", "other"]
+      },
+      "description": "Derived context classes explicitly allowed by the user or policy."
+    },
+    "deniedDerivations": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["persistent_room_map", "cloud_mirroring", "partner_compute", "home_topology", "routine_detection", "raw_identifier_retention", "other"]
+      },
+      "description": "Derived context classes explicitly denied or disabled."
+    },
+    "userVisible": {
+      "type": "boolean",
+      "description": "Whether this activation is visible in the SourceOS Context Receipts surface."
+    },
+    "revocation": {
+      "type": "string",
+      "description": "Revocation control, e.g. one_click, policy_change, emergency_expiry, or disabled."
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Evidence references, consent proofs, policy decisions, or UI activation receipts."
+    }
+  }
+}

schemas/RadioSpatialInferenceReceipt.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RadioSpatialInferenceReceipt.json",
+  "title": "RadioSpatialInferenceReceipt",
+  "description": "Receipt for derived radio-spatial inference such as Wi-Fi location, micro-location, visit, location of interest, routine, nearby presence, home service area, room inference, or home topology. The receipt separates heuristic/model use from unproven causal bridges.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "type",
+    "specVersion",
+    "inputReceiptRefs",
+    "inferenceType",
+    "modelOrAlgorithm",
+    "outputStore",
+    "retentionPolicy",
+    "deletionPolicy",
+    "userVisible"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^urn:srcos:receipt:radio-spatial-inference:",
+      "description": "Stable URN identifier. Pattern: urn:srcos:receipt:radio-spatial-inference:<local-id>"
+    },
+    "type": {
+      "const": "RadioSpatialInferenceReceipt",
+      "description": "Discriminator constant."
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version of this document, e.g. 2.1.0."
+    },
+    "inputReceiptRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Signal, model, context, or prior inference receipts used as inputs."
+    },
+    "inferenceType": {
+      "type": "string",
+      "enum": [
+        "wifi_location",
+        "micro_location",
+        "visit",
+        "location_of_interest",
+        "routine",
+        "nearby_presence",
+        "home_service_area",
+        "room_inference",
+        "home_topology",
+        "other"
+      ],
+      "description": "Derived radio-spatial context class."
+    },
+    "modelOrAlgorithm": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "class", "aneUsed"],
+      "properties": {
+        "name": { "type": "string", "description": "Model, heuristic, daemon, or algorithm identifier." },
+        "class": { "type": "string", "enum": ["heuristic", "ml_model", "foundation_model", "rule", "unknown"], "description": "Computation class." },
+        "aneUsed": { "oneOf": [{"type": "boolean"}, {"const": "unknown"}], "description": "Whether Apple Neural Engine or equivalent NPU use is proven, denied, or unknown." },
+        "modelAssetRef": { "type": ["string", "null"], "description": "Optional model-asset receipt, hash, or URN." }
+      }
+    },
+    "outputStore": {
+      "type": "string",
+      "description": "Store, graph, cache, protected context store, or receipt sink where derived context was written."
+    },
+    "outputStoreHash": {
+      "type": ["string", "null"],
+      "pattern": "^(sha256:[a-fA-F0-9]{64})$",
+      "description": "Optional hash for the canonicalized output store descriptor."
+    },
+    "retentionPolicy": {
+      "type": "string",
+      "description": "Retention policy for the derived context."
+    },
+    "deletionPolicy": {
+      "type": "string",
+      "description": "Deletion or tombstoning policy coupled to source signal/object deletion."
+    },
+    "userVisible": {
+      "type": "boolean",
+      "description": "Whether the user-facing Context Receipts surface exposes this inference."
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Evidence references, hashes, logs, or provenance links."
+    },
+    "notes": {
+      "type": "string",
+      "description": "Optional operator-readable notes."
+    }
+  }
+}

schemas/RadioSpatialSignalReceipt.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.srcos.ai/v2/RadioSpatialSignalReceipt.json",
+  "title": "RadioSpatialSignalReceipt",
+  "description": "Receipt for radio-spatial signal collection such as Wi-Fi, Bluetooth, AWDL, Nearby, location, motion, HomeKit, Matter, or Thread observations. Raw identifiers must be redacted or hashed unless explicitly exported by the user.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "specVersion", "source", "collector", "observedFeatures", "rawIdentifiersRedacted", "rawValuesCollected", "timestampWindow", "userVisible", "revocationPolicy"],
+  "properties": {
+    "id": {"type": "string", "pattern": "^urn:srcos:receipt:radio-spatial-signal:", "description": "Stable URN identifier. Pattern: urn:srcos:receipt:radio-spatial-signal:<local-id>"},
+    "type": {"const": "RadioSpatialSignalReceipt", "description": "Discriminator constant."},
+    "specVersion": {"type": "string", "description": "Spec version of this document, e.g. 2.1.0."},
+    "source": {"type": "string", "enum": ["wifi", "bluetooth", "awdl", "nearby", "location", "motion", "homekit", "matter", "thread", "uwb", "other"], "description": "Signal source class."},
+    "collector": {"type": "string", "description": "Daemon, service, app, or component that collected or observed the signal."},
+    "observedFeatures": {"type": "array", "minItems": 1, "items": {"type": "string", "enum": ["rssi", "per_antenna_rssi", "lqm", "snr", "channel", "ap_count", "bssid_hash", "wifi_location_fix", "bluetooth_hint", "wifi_hint", "motion_hint", "ranging_supported", "rssi_change_detection", "home_accessory_event", "thread_topology", "matter_fabric", "other"]}},
+    "rawIdentifiersRedacted": {"type": "boolean", "description": "True when SSIDs, BSSIDs, MACs, home IDs, accessory IDs, and equivalent identifiers are redacted or hashed."},
+    "rawValuesCollected": {"type": "boolean", "description": "True only when the receipt payload contains raw signal values rather than presence/count/hash evidence."},
+    "timestampWindow": {"type": "string", "description": "ISO 8601 interval or timestamp window covered by this receipt."},
+    "userVisible": {"type": "boolean", "description": "Whether the user-facing Context Receipts surface exposes this receipt."},
+    "revocationPolicy": {"type": "string", "description": "Policy or control used to disable future collection or revoke the derived context."},
+    "evidenceRefs": {"type": "array", "items": {"type": "string"}, "description": "Evidence references, hashes, or provenance links."},
+    "notes": {"type": "string", "description": "Optional operator-readable notes."}
+  }
+}