Outbox Reconcile Rules

Decision rules for an OFFLINE-FIRST CLIENT'S outbox drain and cache reconcile step. Not a sync engine -- the correctness rules that sit on top of one.

THE SILENT FAILURE. An offline-first client keeps a local cache and an outbox of pending writes, and reconciles against the server when it reconnects. The reconcile step decides what the server "really" has and prunes anything local the server does not know about. Every failure mode below ends with USER DATA QUIETLY DELETED, and NONE OF THEM THROW.

AN EMPTY RESPONSE READ AS AN EMPTY ACCOUNT. The server returns nothing because the request was unauthorized, hit a cold cache, or answered with a demo/placeholder payload -- a deployment with no database configured, returning a stub. A naive client concludes the account is empty and prunes the user's entire local catalogue. This is the worst outcome available and it arrives as a successful HTTP 200.

The distinction the client needs is between "the server says you have nothing" and "the server did not tell me what you have". Those are different answers and a bare empty array is both.

IT CLASSIFIES rather than assumes: which outbox entries are safe to send, which server responses are evidence of state and which are merely the absence of evidence, and when a prune is authorised at all. Anything short of positive evidence refuses to delete.

VERIFIED: 92 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function backoffDelayMs(attempts: number, rand: ();
  export function classifyOutboxResult(status: number | 'network'): OutboxOutcome;
  export function planOutboxStep( entry: OutboxEntryFacts, outcome: OutboxOutcome, now: number, rand: ();
  export function selectSendableOutboxEntries( entries: readonly OutboxQueueEntry[], now: number, paused: boolean, ): readonly string[];
  export function planPruning( read: ReadOutcome, records: readonly LocalRecordFacts[], now: number, graceMs: number = DEFAULT_GRACE_MS, ): readonly PruneDecision[];
  export function classifyServerRead(facts: ServerReadFacts): ReadOutcome;
  export function authProvenReadResumesOutbox(read: ReadOutcome): boolean;

  export type ReadOutcome = | { readonly kind: 'authoritative';