Mastermind/docs/privacy/local-first-data-contract.md

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.