Module outbox 

SQLite-backed outbox queue for fire-and-forget cloud uploads.

Every fire-and-forget cloud POST (trajectory, review_metrics, accepted_edit, mcp_query, imported_reviews) is first appended as a pending row in the global ~/.difflore/data.db. Drain is triggered synchronously from hook / CLI cold paths — there is deliberately no background daemon.

Claim/confirm semantics:

enqueue()     -> INSERT status='pending'
claim_next()  -> UPDATE status='processing' (atomic, oldest first)
confirm(id)   -> DELETE
mark_failed() -> UPDATE retry_count++; >=MAX_RETRY_COUNT -> status='abandoned'
reset_stale() -> processing > threshold seconds -> pending

Circuit breaker: three consecutive mark_failed calls trip the breaker for 60 s; while open, claim_next returns None so callers short- circuit without hammering an unreachable cloud. Any successful confirm resets the consecutive-failure counter.

Idempotency contract: claim_next deliberately self-heals stale processing rows after DEFAULT_STALE_SECONDS. A very slow upload can therefore be retried by a later drain pass. Every cloud endpoint reached from this queue must treat duplicate payloads as idempotent, keyed by the event id / request signature carried in the payload. The queue chooses at-least-once delivery over permanent local data loss.

Modules

kind

Supported outbox payload kinds. Stored as TEXT in cloud_outbox.kind; the drain_outbox dispatcher matches on these to pick the right POST route. Keep the string literals stable — changing one means abandoning every row in the queue at upgrade time.

Structs

AcceptedEditAttributionSummary

DrainSummary

Result of a drain_abandoned_older_than call (dry-run or real).

OutboxCounts

Summary row for difflore doctor / diagnostics.

OutboxDrainReport

OutboxItem

A row in cloud_outbox that has been claimed for processing.

OutboxQueue

Queue handle. Cheap to clone; all state is either on disk or inside an Arc<Atomic*> so multiple callers inside the same process observe the same breaker state.

Enums

CircuitState

Current state of the breaker. Open means callers should short- circuit until the until_unix_ms timestamp has passed.

Constants

CIRCUIT_FAILURE_THRESHOLD

How many consecutive mark_failed calls trip the circuit breaker.

CIRCUIT_OPEN_DURATION_MS

How long (ms) the circuit stays open before claim_next starts returning rows again.

DEFAULT_STALE_SECONDS

How long a processing row is allowed to sit before reset_stale will recover it. Anything claimed by a crashed / hung drain pass falls back to pending after this many seconds.

MAX_RETRY_COUNT

Maximum delivery attempts per outbox item. After this many failures, the item is marked abandoned and is no longer claimed.

Functions

drain_outbox

Drain at most max_items outbox rows. For each claimed row, invoke the appropriate CloudClient method, then confirm on success or mark_failed on HTTP / network failure. Returns (attempted, confirmed).

drain_outbox_kind

drain_outbox_kind_report

drain_outbox_report