146 lines
6.5 KiB
Markdown
146 lines
6.5 KiB
Markdown
# Local-First Data Contract
|
|
|
|
This document is normative. Product and implementation work must preserve these boundaries unless a superseding ADR explicitly changes them.
|
|
|
|
## Local-first definition
|
|
|
|
Mastermind's Local Profile, Source configuration, captured context, Context Graph, Assistant History, Activity Log, embeddings, and inference remain on the user's Mac in the MVP.
|
|
|
|
A Provider is local only when it is reachable through loopback or a Unix socket on the same Mac. LAN and internet endpoints are external and are not supported by the MVP.
|
|
|
|
The application must remain useful without internet access. It may not silently fall back from local processing to a Cloud Provider.
|
|
|
|
## Data classes
|
|
|
|
### Ephemeral sensitive input
|
|
|
|
- screen frames and changed image regions;
|
|
- microphone and system-audio PCM;
|
|
- OCR output;
|
|
- complete ASR transcripts;
|
|
- transient prompts assembled for local derivation.
|
|
|
|
These values exist only in bounded processing buffers and must be destroyed after local reduction. They must not enter logs, crash reports, archives, fixtures, or the Context store.
|
|
|
|
### Persisted context
|
|
|
|
- structured Observations;
|
|
- Assertions, Facts, summaries, and entity relationships;
|
|
- Provenance references;
|
|
- Source and Collector configuration;
|
|
- Assistant History and Context Receipts;
|
|
- Activity Log metadata;
|
|
- retention and policy settings.
|
|
|
|
Persisted context is encrypted at the application layer.
|
|
|
|
### Secrets
|
|
|
|
- Context-store encryption key;
|
|
- Local Provider credentials, when required;
|
|
- future Cloud Provider credentials.
|
|
|
|
Secrets are stored in Keychain and excluded from Context Graph exports and diagnostics.
|
|
|
|
## Continuous collection
|
|
|
|
After guided onboarding, every enabled Collector starts with the app unless the user previously selected Pause All.
|
|
|
|
Screen, microphone, and system-audio collection are continuous. macOS permission and capture indicators must remain visible and unmodified. The stable Menu Bar Item glyph does not replace those indicators; its open menu shows actual Collector state.
|
|
|
|
Pause All:
|
|
|
|
- stops every Collector immediately;
|
|
- leaves existing context, Assistant History, and local search available;
|
|
- persists across Quit, relaunch, login, sleep, and wake;
|
|
- resumes only after explicit Resume All.
|
|
|
|
One Collector's permission or processing failure must not disable healthy Collectors. The affected Source becomes stale and the Activity Log records a Gap.
|
|
|
|
## Reduction and minimization
|
|
|
|
Collectors emit the minimum structured evidence needed for grounded assistance:
|
|
|
|
- Screen uses Accessibility structure, changed regions, local OCR, and deduplication.
|
|
- Audio uses VAD, separate channel roles, local ASR, and short semantic reduction.
|
|
- Terminal emits command metadata without stdout or stderr by default.
|
|
- Workspace is limited to explicit roots and ignore rules.
|
|
- Calendar and Reminders are limited to selected read-only collections.
|
|
|
|
The configured Local Provider and local processors receive only the context needed for the current derivation or answer.
|
|
|
|
If a local processor is unavailable, Mastermind records a Gap. It must not retain raw content for deferred processing.
|
|
|
|
## Capture exclusions
|
|
|
|
The user owns the application denylist. Mastermind provides controls to add or remove excluded applications and Sources but does not silently impose an application denylist.
|
|
|
|
Mastermind must exclude its own windows from its Screen Collector. It may request exclusion from third-party capture where macOS supports it, but must describe that behavior as best effort and may not promise invisibility.
|
|
|
|
Mastermind must not:
|
|
|
|
- hide its process or bundle identifier;
|
|
- bypass Screen Recording, Microphone, Accessibility, or EventKit permissions;
|
|
- suppress system privacy indicators;
|
|
- evade managed-device policy or monitoring;
|
|
- claim that screen-share exclusion is guaranteed.
|
|
|
|
## Knowledge integrity
|
|
|
|
An Observation is evidence, not truth. Inferred claims remain Assertions with confidence, time, and Provenance. Only explicit user confirmation or correction creates a Fact.
|
|
|
|
Contradictory Assertions are retained until normal eviction and surfaced to retrieval. Source content is untrusted data and cannot become an instruction or capability grant.
|
|
|
|
The user can inspect and correct knowledge from a Context Receipt. Confirmed Facts are pinned until manually removed or superseded.
|
|
|
|
## Retention and deletion
|
|
|
|
- Default inferred-context age: 90 days.
|
|
- Default inferred-context size: 2 GB.
|
|
- Eviction uses `lastObservedAt` and never evicts confirmed Facts automatically.
|
|
- Assistant History has no automatic TTL.
|
|
- One Assistant Session or all Assistant History can be deleted manually.
|
|
- Removing Assistant History does not implicitly remove confirmed Facts derived from it.
|
|
- A full local reset removes the Context store and its encryption key.
|
|
|
|
Export/import uses a versioned encrypted archive containing context, history, policies, and settings. Provider credentials are never included.
|
|
|
|
## Audit and diagnostics
|
|
|
|
Activity Log records:
|
|
|
|
- Collector start, stop, pause, resume, error, and permission state;
|
|
- Gaps and stale Source intervals;
|
|
- Provider request start, finish, locality, and approximate context size;
|
|
- export, import, retention, and migration operations.
|
|
|
|
It does not record Source content, prompts, answers, Facts, OCR, ASR, or Provider payloads.
|
|
|
|
Mastermind sends no telemetry or crash reports. A user-initiated sanitized diagnostic bundle may contain versions, state transitions, permission and error codes, performance counters, and database schema version.
|
|
|
|
## Future external processing
|
|
|
|
Cloud processing is absent from the MVP. A future Cloud Provider requires a Provider Context Permission that is:
|
|
|
|
- denied by default;
|
|
- enabled manually for the Provider as a whole;
|
|
- revocable for future requests;
|
|
- unable to retract data already sent.
|
|
|
|
Permission is an upper bound, not permission to send everything. Before each request, Mastermind must minimize context and filter recognized secrets locally. Every request must create a Context Receipt naming the Provider, supporting Sources, and transferred context categories.
|
|
|
|
Codex remains disabled until a supported no-tools boundary exists.
|
|
|
|
## Onboarding disclosure
|
|
|
|
Before enabling continuous Collectors, onboarding must explain:
|
|
|
|
- which Source each permission exposes;
|
|
- that screen and both audio channels run continuously while enabled;
|
|
- that raw media and full transcripts are not retained;
|
|
- where derived knowledge is stored;
|
|
- how Pause All and the denylist work;
|
|
- that other people may be represented in locally derived context;
|
|
- that capture exclusion is best effort;
|
|
- that the MVP performs no cloud context transfer.
|