Record a purchase (one receipt). Idempotent per (source_ref, line_no).

Each item: {name, quantity, unit, price?, category?, line_no}. source: 'email' (purchased_at required — the receipt has a date) or 'manual' (purchased_at defaults to today). source_ref: retailer ORDER ID where extractable, else email Message-ID; manual fallback 'manual:::' (+':2' suffix on collision — a nonzero 'ignored' count on a fresh receipt signals one). Call get_stock() first and reuse existing item names exactly. Returns {inserted, ignored, rejected: [{line_no, reason}]}.

Current stock estimate. No argument: list all known items as {name, category} — call this before add_items to reuse exact names. With an item name: naive-baseline estimate with raw provenance (estimated_state is 'unknown' below 2 distinct purchase dates).

Items past their typical repurchase interval: >= 3 distinct purchase dates, days_since >= median interval, excluding items past 3x median (presumed discontinued). Sorted by overshoot ratio, highest first.

Correction path: void matching event lines (all lines of the receipt if line_no omitted). Voided rows are excluded from every estimate; re-inserting a corrected line for the same (source_ref, line_no) then works. Returns {voided: n}; zero matches is a no-op, not an error.

Ingestion agent plumbing: record a run (heartbeat + audit) after every ingestion pass, even one that wrote nothing. skipped: [{source_ref, reason}] for receipts/lines the agent could not parse (never guess — skip and log). Returns the backfill cursor: earliest_window_start already covered.

Read-only raw event access (explainability: every estimate is recomputable from these rows). Includes voided rows, flagged.