Inbox Agent Configuration and Policy Specification

1. Purpose

This document defines how Inbox Agent configuration, user preferences, automation policy, provider capabilities, security thresholds, feature flags, runtime limits, and environment-specific behavior are represented and managed.

The goal is to keep configuration explicit, reviewable, typed, secure, auditable, and separate from application code wherever practical.

The configuration model must support:

The system must distinguish clearly between:

PLATFORM POLICY
What the application permits

USER POLICY
What the user prefers within allowed boundaries

AUTOMATION POLICY
What may execute without approval

SECURITY POLICY
What content and actions are allowed

RUNTIME CONFIGURATION
How infrastructure behaves

FEATURE FLAGS
Which capabilities are available

2. Core Configuration Principle

Configuration should follow this precedence:

HARD PLATFORM SECURITY CEILING
        ↓
ENVIRONMENT POLICY
        ↓
USER POLICY
        ↓
MAILBOX POLICY
        ↓
IDENTITY POLICY
        ↓
RULE-SPECIFIC EXECUTION POLICY
        ↓
MESSAGE-SPECIFIC USER OVERRIDE

Lower levels may narrow authority but may not exceed higher-level security constraints.

3. Configuration Domains

Primary domains:

4. Configuration Storage Classes

Configuration should be stored according to its nature.

4.1 Version-Controlled Defaults

Examples:

These should be code-reviewed.

4.2 Database-Managed Configuration

Examples:

These should be editable through the application.

4.3 Environment Configuration

Examples:

4.4 Secret Configuration

Examples:

Secrets must never be stored as ordinary settings.

5. Typed Configuration

Configuration should be strongly typed.

Avoid unstructured free-form settings such as:

{
  "settings": {
    "whatever": true
  }
}

Prefer explicit configuration models.

Example:

AutomationPolicy
- action_type
- mode
- scope
- risk_ceiling
- approval_required
- enabled

6. Configuration Validation

All configuration changes should be validated before activation.

Validation includes:

Invalid configuration must fail closed.

7. Configuration Versioning

Important configuration should support version history.

Examples:

A change should record:

version
changed_by
changed_at
previous_value
new_value
reason_optional

8. Global Application Settings

Examples:

application_name
default_timezone
default_locale
default_date_format
default_page_size
max_page_size
default_search_window

The current product should default to the user's configured timezone rather than server timezone.

9. Mailbox Configuration

Each MailAccount should have configuration such as:

mailbox_type
operating_mode
attention_weight
notification_weight
automation_enabled
security_profile
sync_frequency
historical_default

Supported mailbox types:

PERSONAL
PROFESSIONAL
COMMERCIAL
SYSTEM_SERVICE
APPLE_INFRASTRUCTURE
LEGACY

10. Mailbox Operating Modes

Supported modes:

ACTIVE
FORWARDING
READ_ONLY
MIGRATING
LEGACY
RETIRED_FROM_MAIL

Behavior should derive from operating mode rather than ad hoc flags.

11. Mailbox Attention Weight

Different mailboxes should influence workload differently.

Example defaults:

PERSONAL       HIGH
PROFESSIONAL   HIGH
COMMERCIAL     LOW
SYSTEM_SERVICE EXCEPTION_ONLY
LEGACY         BACKGROUND

This is not message priority. It is a mailbox-level default signal.

12. Identity Configuration

MailIdentity configuration may include:

address
identity_type
purpose
preferred_for
active
external_change_recommendations_enabled

Identity types:

PRIMARY
ALIAS
FORWARDED
LEGACY

13. Identity Purpose

Suggested purposes:

PERSONAL
PROFESSIONAL
PROJECT_AI
COMMERCIAL
SYSTEM_SERVICE
APPLE_SERVICES
LEGACY

The physical mailbox and identity purpose remain separate.

14. Security Policy

Security configuration should contain both immutable ceilings and user-adjustable preferences.

Platform-controlled examples:

raw_html_rendering = prohibited
email_content_as_instruction = prohibited
automatic_attachment_execution = prohibited
private_network_url_fetch = prohibited
provider_credentials_to_ai = prohibited

These are not user-disableable.

15. User Security Preferences

Examples:

block_remote_images
block_tracking_pixels
mediate_unknown_links
quarantine_authentication_failures
quarantine_macro_attachments
trusted_sender_behavior
security_summary_enabled

User preferences may strengthen security beyond defaults.

16. Quarantine Thresholds

Security decisions should rely on structured findings rather than one opaque threshold alone.

Configuration may include:

quarantine_on_critical_finding = true
hold_unknown_executable = true
hold_macro_attachment_from_unknown_sender = true
require_review_for_high_risk_url = true

17. Trusted Sender Policy

Trust configuration should be scoped.

Supported trust scopes:

EXACT_ADDRESS
DOMAIN
RULE_CONDITION

Trust must never disable hard platform security controls.

18. Remote Content Policy

Suggested modes:

BLOCK_ALL
ALLOW_TRUSTED
ALLOW_ALL_EXCEPT_SUSPICIOUS

Recommended default:

ALLOW_TRUSTED

Quarantined mail should always block remote content.

19. URL Policy

Configuration may govern:

mediate_unknown_urls
resolve_redirects
block_ip_destinations
block_non_https
warn_on_display_mismatch
warn_on_homograph

Hard-blocked schemes should remain platform policy.

20. Attachment Policy

Possible settings:

max_attachment_size
max_archive_recursion
max_archive_expanded_size
scan_unknown_files
hold_macro_documents
hold_executables
deep_scan_threshold

21. Automation Policy

Automation must be action-specific.

Possible modes:

DISABLED
SUGGEST
APPROVAL_REQUIRED
AUTOMATIC

22. Initial Automation Defaults

Recommended initial policy:

CLASSIFY             AUTOMATIC
SUMMARIZE            AUTOMATIC
SET_ATTENTION        AUTOMATIC_WITH_REVIEW_ON_LOW_CONFIDENCE
SET_PRIORITY         AUTOMATIC
ARCHIVE               AUTOMATIC_ONLY_BY_APPROVED_LOW_RISK_RULE
MOVE                  APPROVAL_REQUIRED_OR_APPROVED_RULE
CREATE_DRAFT          AUTOMATIC
SEND                  APPROVAL_REQUIRED
PERMANENT_DELETE      APPROVAL_REQUIRED
CHANGE_FORWARDING     DISABLED
SECURITY_CONFIG       APPROVAL_REQUIRED

23. Automation Scope

Policy may be scoped to:

GLOBAL
MAILBOX
IDENTITY
RULE
ACTION_TYPE

The most restrictive applicable policy wins when conflicts occur.

24. Automation Pause

Required pause levels:

GLOBAL
PROVIDER
MAILBOX
ACTION_TYPE
MIGRATION
AI

A pause should stop mutations while permitting safe read-only behavior where possible.

25. Rule Execution Policy

Each rule should define:

SUGGEST_ONLY
REQUIRE_APPROVAL
EXECUTE_AUTOMATICALLY

A rule cannot select an execution level forbidden by platform/user policy.

26. Rule Limits

Configuration should protect against accidental rule explosion.

Possible limits:

max_active_rules
max_rule_conditions
max_rule_actions
regex_timeout
max_bulk_rule_simulation_items

27. AI Configuration

AI configuration should be abstracted from provider implementation.

Logical settings:

classification_model
complex_reasoning_model
draft_model
summary_model
max_context_tokens
classification_timeout
draft_timeout
structured_output_required

28. AI Routing Policy

Recommended principle:

DETERMINISTIC LOGIC FIRST
LOW-COST MODEL SECOND
HIGH-CAPABILITY MODEL ONLY WHEN JUSTIFIED

29. AI Privacy Configuration

Possible settings:

allow_full_body_processing
allow_attachment_text_processing
allow_historical_mail_ai_processing
body_cache_ttl
ai_trace_retention

Default should minimize content exposure.

30. AI Confidence Policy

Suggested confidence classes:

HIGH
MEDIUM
LOW

Configuration should map confidence to allowable outcomes.

Example:

HIGH   → normal low-risk automation
MEDIUM → classify but restrict consequence
LOW    → review queue

31. Notification Policy

Notification configuration should be attention-oriented.

Possible categories:

CRITICAL_SECURITY
HIGH_PRIORITY_HUMAN
SYSTEM_ALERT
WAITING_OVERDUE
DAILY_BRIEF
PROVIDER_HEALTH

Routine mail should not create push notifications by default.

32. Daily Brief Configuration

Settings:

enabled
delivery_time
include_security
include_waiting
include_system_alerts
include_identity_hygiene
include_processed_summary

33. Retention Policy

Retention configuration should distinguish:

PERMANENT
LONG_TERM
STANDARD
TEMPORARY
DISCARD_CANDIDATE

Attention state must remain independent.

34. Application Metadata Retention

Separate policies should exist for:

audit_events
security_findings
ai_traces
temporary_message_bodies
temporary_attachments
migration_logs
rule_executions
provider_diagnostics

35. Historical Mail Policy

Historical mail settings may include:

default_attention = ARCHIVE
run_ai_on_import = false
scan_attachments_on_demand = true
include_in_daily_brief = false
include_in_search = true

36. Migration Policy

Migration configuration may include:

batch_size
parallelism
dry_run_required
pilot_required
duplicate_threshold
source_delete_allowed
reconciliation_required

Recommended defaults:

dry_run_required = true
pilot_required = true
source_delete_allowed = false
reconciliation_required = true

37. Duplicate Policy

Suggested duplicate thresholds:

CONFIRMED
LIKELY
UNCERTAIN

Only confirmed duplicate behavior may be automated initially, and even then source deletion should remain separately authorized.

38. Search Configuration

Possible settings:

default_mailbox_scope
include_historical_by_default
provider_search_timeout
max_provider_search_parallelism
max_results

Partial results must be reported explicitly.

39. Sync Configuration

Per-provider settings may include:

incremental_sync_enabled
fallback_polling_interval
full_reconciliation_interval
subscription_renewal_margin

Provider-specific values belong behind adapter configuration.

40. Runtime Limits

Central runtime limits should include:

max_bulk_operation_size
max_parallel_provider_requests
max_worker_attempts
default_job_timeout
security_job_timeout
migration_batch_size

41. Blast-Radius Limits

High-risk operations should have configured blast-radius thresholds.

Example:

archive > 100 messages → preview required
move > 100 messages → approval
delete > 1 message → explicit approval
send > 1 recipient group → explicit review

Exact thresholds may evolve.

42. Feature Flags

Feature flags should control incomplete or high-risk capabilities.

Examples:

ENABLE_SEND
ENABLE_DELETE
ENABLE_GMAIL_WRITES
ENABLE_MICROSOFT_WRITES
ENABLE_ICLOUD_MIGRATION
ENABLE_DEEP_SECURITY_SCAN
ENABLE_NATIVE_PUSH
ENABLE_CONTACTS
ENABLE_CALENDAR_CONTEXT

43. Feature Flag Safety

A disabled capability must be inaccessible through:

UI
API
Agent tools
Background workers
Rules

not merely hidden from navigation.

44. Environment Policy

Environment policy should enforce:

LOCAL
mock-first

PREVIEW
non-production providers or read-only

PRODUCTION
real provider access

45. Production Mutation Guard

Preview/development should have:

production_mutations_allowed = false

as a hard environment guard.

46. Provider Capability Configuration

Provider adapters should expose capabilities such as:

can_read
can_search
can_archive
can_move
can_label
can_create_draft
can_send
can_delete
supports_push
supports_delta

Application behavior should use capabilities rather than provider-name conditionals.

47. Configuration API

Configuration changes should flow through application services.

Clients should not write directly to configuration tables.

48. Configuration Change Preview

High-impact configuration changes should show:

current value
new value
affected scope
risk
expected effect

before activation.

49. Configuration Audit

Audit changes to:

security policy
automation policy
trusted senders
mailbox roles
identity purposes
provider authorization
feature flags
retention
migration policy

50. Configuration Rollback

Versioned settings should support rollback where practical.

Rollback itself should be audited.

51. Configuration Export

A future configuration export should allow backup of:

rules
preferences
identity mappings
mailbox roles
automation policy
notification policy

without exposing secrets.

52. Configuration Import

Import should:

validate schema
show differences
exclude secrets
require review for consequential changes

53. Configuration Schema Documentation

The repository should maintain machine-readable schemas for configuration DTOs.

Generated documentation may be used by:

Web client
Future iOS client
Charter-generated implementation
Tests

54. Configuration Test Requirements

Tests must cover:

invalid values
precedence
security ceiling
mailbox overrides
feature flags
environment guards
rollback
audit

55. Core Configuration Invariant

The application must preserve:

CONFIGURATION
defines permitted behavior

RULES
define deterministic mail behavior

AI
handles ambiguity

POLICY
authorizes consequence

SECURITY CEILING
cannot be bypassed by any lower-level setting

56. Acceptance Criteria

This specification is satisfied when: