Inbox Agent — Non-Functional Requirements & Service Quality Specification

Status: Implementation Baseline
Audience: Cursor, Charter, engineering, QA, operations

1. Quality Model

Inbox Agent is a personal information system that handles private mail and may eventually coordinate multiple providers, contacts, and intelligent workflows. Correctness, privacy, recoverability, and trust take precedence over raw feature velocity.

Requirements use MUST, SHOULD, and MAY in their conventional normative sense.

2. Availability and Resilience

• Core local/API services MUST recover from process restarts without corrupting synchronization state.
• A failure in AI processing MUST NOT prevent mail synchronization.
• A failure for one connected account SHOULD NOT block unrelated accounts.
• Queued work MUST survive worker restarts.
• External-provider outages MUST degrade gracefully and preserve retryable work.
• Provider mutation workflows MUST be idempotent.

Initial MVP target: 99.5% monthly availability for Inbox Agent-owned API/UI services, excluding upstream provider outages and planned maintenance.

3. Data Durability and Recovery

• Canonical metadata and application state MUST be backed up.
• Schema migrations MUST be versioned and reproducible.
• Destructive migrations MUST have an explicit recovery plan.
• Synchronization MUST be reconstructable from provider data where provider retention permits.
• AI inference history and audit records MUST not be silently overwritten.
• Restore procedures MUST be testable.

Initial targets:

• RPO: 24 hours maximum for application-owned persistent state; lower where managed platform capabilities permit.
• RTO: 4 hours for MVP recovery from a recoverable application/database failure.

These are release targets, not promises about third-party mail provider recovery.

4. Performance

User-facing operations should remain responsive independently of background synchronization and AI workloads.

MVP service objectives:

• p95 API response for ordinary metadata reads: < 500 ms excluding client/network transit.
• p95 interactive mailbox list/search backed by local indexed data: < 1.5 s.
• UI acknowledgment of user state-change request: < 1 s when queued asynchronously.
• background event pickup after durable enqueue: p95 < 30 s under normal load.
• new-mail canonical availability after provider change is discoverable: p95 < 2 minutes under normal provider conditions.
• AI enrichment: asynchronous; target p95 < 5 minutes after canonical message availability under normal load.

Performance tests must use realistic mailbox/thread sizes.

5. Scalability

MVP must support a single user with multiple connected mail accounts without architectural assumptions that prevent future multi-user operation.

Design expectations:

• stateless horizontally scalable API where practical;
• independent worker scaling;
• bounded page/batch sizes;
• no mailbox-sized in-memory operations;
• indexes driven by actual query patterns;
• AI and attachment processing separated from synchronization throughput.

6. Correctness and Consistency

• Provider synchronization is eventually consistent but MUST converge.
• Duplicate provider events MUST NOT create duplicate canonical state.
• MailMessage identity MUST remain separate from MessageInstance identity.
• User-visible mutations MUST expose pending/failed state when provider convergence is not yet confirmed.
• Reconciliation MUST exist as a correctness mechanism, not only as an operations tool.
• Time values MUST be stored with unambiguous UTC/offset semantics while preserving source values where needed.

7. Security

• OAuth/provider credentials MUST never be stored in plaintext.
• Secrets MUST come from managed secret/environment facilities, never source control.
• Least-privilege provider scopes MUST be used.
• All external transport MUST use TLS.
• Sensitive data at rest MUST use platform encryption.
• Authorization MUST be enforced server-side.
• Message bodies, attachment content, tokens, and credentials MUST NOT appear in routine logs.
• Dependencies MUST be scanned and updated through a controlled process.
• Webhook authenticity MUST be validated.

8. Privacy

Inbox Agent is private-by-default.

• Mail content MUST only be sent to configured processing services required for the feature.
• AI processing data flow MUST be documented.
• Retention of model inputs/outputs MUST be minimized and configurable where providers permit.
• Telemetry MUST use metadata rather than message content whenever possible.
• User data MUST not be used for unrelated analytics.
• Future contact consolidation MUST preserve source/provenance and avoid silent destructive merging.
• Account disconnect and data-retention behavior MUST be explicit.

9. Auditability

Record material system decisions and mutations:

• account connect/disconnect;
• synchronization health transitions;
• provider write requests/results;
• reconciliation repairs;
• AI inference version and result metadata;
• human overrides of AI classification;
• contact merge decisions when implemented;
• administrative/configuration changes.

Audit records must identify actor, action, target, timestamp, and correlation context.

10. Observability

Use structured logs, metrics, and trace/correlation identifiers.

Required operational views include:

• account synchronization health;
• queue depth/age;
• worker error/retry rate;
• provider throttle state;
• webhook health;
• reconciliation drift;
• API latency/error rate;
• AI latency/error/schema-validity/cost;
• database saturation and slow queries.

Alerting must be actionable and avoid exposing private message content.

11. Maintainability

• Provider integrations MUST implement a common adapter boundary.
• Domain services MUST not depend directly on provider SDK objects.
• Contracts and schemas MUST be versioned.
• Configuration MUST be externalized.
• Significant architecture decisions SHOULD be captured as ADRs.
• Public/internal APIs MUST have automated contract tests.
• Database migrations MUST run in CI against a clean database.
• No production-only manual schema changes.

12. Testability

Minimum automated layers:

• unit tests for domain/policy logic;
• schema/contract tests;
• provider-adapter tests using recorded/synthetic fixtures;
• database integration tests;
• synchronization idempotency/replay tests;
• reconciliation tests;
• AI golden-set regression tests;
• end-to-end happy-path and failure-path tests.

Tests must explicitly cover duplicate, missing, delayed, and out-of-order provider events.

13. Accessibility and UX Quality

User-facing MVP should target WCAG 2.2 AA practices:

• keyboard operability;
• visible focus;
• semantic controls;
• sufficient contrast;
• screen-reader labels;
• no color-only status communication;
• understandable pending/error states.

AI uncertainty and synchronization failures must be understandable rather than hidden.

14. Compatibility and Portability

• Provider-specific features MUST be capability-gated.
• Canonical data MUST not require a particular mail provider.
• Database and storage choices may be implementation-specific, but domain contracts should remain portable.
• Client behavior MUST tolerate backward-compatible API evolution.

15. Cost Controls

Track and bound:

• AI tokens/calls per message;
• attachment processing;
• background retries;
• provider API consumption;
• storage growth;
• observability retention.

Avoid repeated AI processing when the canonical message fingerprint and inference version are unchanged.

16. Service Quality Gates for MVP

MVP is releasable only when:

• no known data-loss defect exists;
• synchronization replay/idempotency tests pass;
• reconciliation is operational;
• secrets and mail bodies are absent from routine logs;
• backup/restore procedure has been exercised;
• critical API and synchronization metrics are observable;
• AI regression gates pass;
• provider mutation failure is visible and recoverable;
• performance targets have been measured with representative data.