# Architecture ## Components The compatibility layer translates OpenAI and Anthropic requests into tasks on one configured queue, waits for the Dot to complete them, and translates results back. Everything below it is a general task exchange; the Dot is its only intended worker. The HTTP layer authenticates requests and bounds input. The service layer validates grants and applies task transitions. SQLite persists identities, token fingerprints, tasks, subscriptions, audit metadata, rate windows, and outbound events. The event worker maintains deadlines and leases and delivers the durable outbox. Administrative commands operate directly on local storage. Dot2API never interprets instructions as executable code. A receiving agent decides how to execute a claimed task under its own permissions. ## Task lifecycle Tasks begin in `queued`. An atomic claim changes the task to `running`, increments its attempt counter, and returns a lease credential once. Only the claiming principal with that credential can renew, release, or complete the task. Lease credentials are stored as hashes. `running` tasks become `completed` when their results are submitted, `queued` after a retryable release or lease expiration with budget remaining, or `failed` when retries are exhausted. Creators may cancel active tasks. Deadlines move active tasks to `expired`. Terminal states are `completed`, `failed`, `cancelled`, and `expired`. A lease cannot extend beyond the task deadline. Expiration is reconciled by the background worker and before lifecycle operations. Submission deduplicates on tenant, creator, and idempotency key; a different request with the same key conflicts. Completion can be repeated with the same lease and identical result. Other operations are not universally safe to retry after an ambiguous network failure: retrieve current state first. A lost claim response is recovered by lease expiration. Claims and state changes serialize through SQLite transactions. An expired lease cannot complete a subsequently claimed task. This fences Dot2API state; it cannot undo external effects already performed by a worker. Executors must make external effects idempotent independently. ## Authorization Each principal belongs to one tenant and has explicit queue grants and scopes. Read-only producers see their own tasks; principals with work permission may see tasks in granted queues. Cancellation requires the creator and submit permission. All grants are rechecked during state-changing transactions. Administrators have local filesystem access rather than a remote administrative API. Subscriptions belong to principals. Delivery rechecks principal status, scopes, queue grants, and task visibility. Token revocation prevents further requests using that token; disable the identity or unsubscribe to stop its existing event subscriptions. A callback already in flight cannot be recalled. ## Events State changes and outbox insertion commit in one transaction. Events carry task identifiers, queue, status, and revision, without task instructions or results. Consumers retrieve authorized task data separately. A stable event ID survives delivery retries. Changes may be delayed, duplicated, or received out of order; retrieve current task state before acting. Subscriptions cover future transitions. There is no historical replay cursor. After subscribing and after reconnecting, reconcile with `list_tasks`. Pagination is by monotonically increasing task sequence, not modification time. To reconcile changed older tasks, rescan the relevant state from the first page. Delivery uses bounded retry attempts with exponential delay and jitter. Redirects and permanent client errors stop retries; timeout, connection errors, HTTP 408/429 and server errors are retried. HTTP 410 disables the subscription. Exhausted deliveries remain available for local administrative recovery. Delivery reservations expire so an interrupted process can resume work. A crash after remote receipt and before local acknowledgment may duplicate an event. ## Storage and deployment boundary Use one process and a local persistent filesystem. SQLite WAL supports concurrent request threads; it is not a multi-host storage design. The service does not automatically purge task history, audit rows, subscriptions, or delivery rows. Monitor disk growth and establish a retention policy before sustained deployment. Automated retention, clustering, and online schema migration are outside this release.