Native architecture · TraceRook

Three native processes, shared Swift packages, and separate authenticated UI and event transports.

Process responsibilities

Process	Responsibility
TraceRook.app	SwiftUI dashboard, MenuBarExtra, onboarding, UserNotifications, native review, settings
TraceRookAgent	Per-user nonprivileged LaunchAgent: policy, model scheduling, approval deadlines, SQLite, health
tracerook-hook	Signed arm64 CLI: bounded stdin, socket request, host output, shared catastrophic fallback

The app uses Swift 6 and standard Apple frameworks. There is no Electron or web view shell. The planned service registration uses a supported per-user mechanism with explicit consent. No service is registered in this milestone and no root daemon is part of the design.

How the components connect

Claude Code / CodexA supported local lifecycle hook provides host JSON.
Signed bridgeLength-prefixed JSON travels over a user-owned Unix socket.
Agent serviceNormalize, inspect, redact, classify, and bind the exact action.
Policy and providerLocal rules first; permitted selected context goes directly to Anthropic when needed.
Approval and native UIAuthenticated XPC publishes status and accepts authorized review mutations.
Host decision and historyReturn a host-compatible result; retain a sanitized, uncertainty-aware audit record.

Shared modules and concurrency

Contracts own versioned envelopes, enums, and provider-independent representations. AgentAdapters own host names and input/output mapping. Privacy owns redaction and minimization. Rules and Core own deterministic evidence, evaluation precedence, and state transitions.

Mutable stores, review coordination, analysis scheduling, and health monitors use actors. UI state is MainActor-isolated. Async/await carries deadlines and cancellation. The service alone writes SQLite; the UI reads through XPC rather than opening the live database concurrently.

Trust and transport boundaries

Input and model reasoning are untrusted. The planned CLI event socket must check kernel peer credentials and bound every frame. The tested v2 codec is implemented; an operating socket and peer authentication are not. Same-user malicious interference remains a coverage limit. Approval and trust mutations belong exclusively on an authenticated signed-client XPC endpoint.

UI peers require audit-token/code-signature validation against the intended signed family. The CLI socket must never accept approve or trust operations. This split is an explicit MVP2.1 prerequisite for live review.

Repository layout

App/                         Native SwiftUI + AppKit where needed
Agent/                       Background service executable
HookCLI/                     Signed command-line bridge
Packages/TraceRookContracts/  Versioned contracts
Packages/TraceRookCore/       Provider and approval foundations
Packages/TraceRookPrivacy/    Sanitization utilities
Packages/TraceRookAgentAdapters/
Packages/TraceRookFixtures/   Explicit demo resources
Tests/                       Swift Testing harness
Resources/                   Icon, Info.plist, LaunchAgent plist
website/                     Static product site and docs

The source milestone has executable foundations and native demo functionality. Service transport, durable history, safe installation, live rule enforcement, and Keychain-backed analysis remain pending. See the acceptance record.