diff --git a/docs/contract-additions/radio-spatial-derived-context.md b/docs/contract-additions/radio-spatial-derived-context.md new file mode 100644 index 0000000..2bb8bcd --- /dev/null +++ b/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. diff --git a/schemas/RadioSpatialActivationReceipt.json b/schemas/RadioSpatialActivationReceipt.json new file mode 100644 index 0000000..78f01bc --- /dev/null +++ b/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:" + }, + "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." + } + } +} diff --git a/schemas/RadioSpatialInferenceReceipt.json b/schemas/RadioSpatialInferenceReceipt.json new file mode 100644 index 0000000..a4667e1 --- /dev/null +++ b/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:" + }, + "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." + } + } +} diff --git a/schemas/RadioSpatialSignalReceipt.json b/schemas/RadioSpatialSignalReceipt.json new file mode 100644 index 0000000..462dac0 --- /dev/null +++ b/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:"}, + "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."} + } +}