Async exports and their guarantees

THREE SURFACES, THREE FORMATS

  Audit logs        CSV       aggregator
  Cost reports      CSV       aggregator
  Recommendations   .xlsx     recommender

IN-PROCESS (audit logs, cost reports)
  Concurrency bounded in-process at 5 concurrent exports.
  NO JOBS TABLE.
  A pod restart DROPS PROGRESS SILENTLY.
  You re-trigger from the UI.

PERSISTED (recommendations only)
  Every export lands in a table carrying status, the
  requested filters, the output key, any error, and lock
  fields.
  The owning pod HEARTBEATS its lock.
  A sweeper reclaims rows whose lock went stale (a
  likely pod crash) and marks them FAILED with the
  reason "lock expired (owning pod likely crashed)".
  You re-submit.

THE PRACTICAL DIFFERENCE
  A crashed recommendation export shows up as a FAILED
  ROW with a reason.
  A crashed audit-log export shows up as NOTHING AT ALL.

So for a long audit export, if it never arrives, do not
wait. Re-trigger.

RECOMMENDATIONS   an internal endpoint lists past export
                  rows, so support can see who exported
                  what and when, and can re-submit on a
                  customer's behalf.

AUDIT LOGS        no admin history.
COST REPORTS      no admin history.

Completed reports are written to object storage with a
SHORT-LIVED SIGNED DOWNLOAD URL, surfaced on the page
you started from.

For very long jobs the URL is ALSO EMAILED, so you can
close the tab.

SHEET 1: EXECUTIVE SUMMARY
  Report context and traceability: organisation name and
  id, who generated it, when, and the applied-filter
  scope.
  Headline totals: total recommendations, resources
  affected, overall potential monthly and annual savings.
  Breakdowns by recommendation type, cloud provider,
  service, severity and status.

SHEET 2: RECOMMENDATION DETAILS
  One row per recommendation: region, resource group,
  tags, cloud account, monthly and annual savings,
  recommended action, supporting evidence, first
  detected, age in days, last evaluated.

SUMMARY SAVINGS ARE DE-DUPLICATED PER RESOURCE.

It is a SUM OF MAX, never a raw sum: mutually-exclusive
levers do not stack, matching the product's own rollup.

CONSEQUENCE: BREAKDOWN ROWS MAY NOT ADD UP TO THE
OVERALL TOTAL. The sheet says so.

WHY IT MUST WORK THIS WAY

  One EC2 instance can carry a rightsizing recommendation
  and a schedule recommendation. You cannot capture both
  in full: rightsize it and the schedule saving changes;
  schedule it and the rightsizing saving changes.

  A naive sum would present leadership with a savings
  figure the org could never actually capture.

BEFORE A FIX IN 2026, THE RECOMMENDATION EXPORT
DOCUMENTED THAT IT HONOURED YOUR FILTERS AND DID NOT.
It hard-coded status=open and ignored every filter.

It now genuinely honours status, provider, category,
resource type, severity, cloud account, rule, search
and sort.

Severity appears in the sheet-1 breakdown and is an
accepted filter, and it is deliberately NOT a column on
sheet 2.

WHY: severity is not surfaced in the product UI, and the
export shows what the UI shows.

MONDAY: audit evidence
  Filter: all mutations, full previous year, one org.
  Export to CSV. Request returned immediately.

  40 minutes later: nothing.

  DIAGNOSIS: audit-log exports are IN-PROCESS with no
  jobs table. A pod restart drops progress silently, and
  there is no failed row to find. There was a deploy
  that afternoon.

  ACTION: re-triggered, subscribed to export.ready first
  so the second attempt would announce itself.
  Second attempt: signed URL arrived, plus an email.

  WHAT THEY CHANGED PERMANENTLY
    Long audit exports now run outside deploy windows,
    and export.ready is subscribed. Both take a minute
    to set up and remove the entire failure mode.

WEDNESDAY: the leadership workbook
  Recommendations export, filters: open + applied, all
  providers, savings above $100.

  Arrived as .xlsx with the traceability block naming
  the filter scope. That block is why the CFO's office
  accepted it as evidence rather than as a screenshot.

  THE QUESTION IN THE MEETING
    "Your provider breakdown adds to $61,200 and your
     headline says $48,900. Which is right?"

    The headline. Summary savings are de-duplicated per
    resource as a sum of max, because mutually-exclusive
    levers do not stack: an instance carrying both a
    rightsizing and a schedule recommendation cannot
    capture both in full.

    A raw sum would have promised $61,200 that the org
    could never have captured. The sheet states this,
    and the person who read the note was the one who
    asked the question.

  THE ARCHIVED-EXPORT TRAP, AVOIDED
    Someone produced a comparison export from eight
    months earlier. Its filters were not what the
    filename said: exports before the 2026 fix
    hard-coded status=open. The comparison was dropped
    rather than being made against a different
    population.

1. Start an audit-log export covering your longest
   available window. Note the model:
   in-process / persisted:  ________________
   If it never arrives, what will you see?  ________

2. Are you subscribed to export.ready?         Y / N
   If N, subscribe before running long exports.

3. Run a recommendations export. Open sheet 1.
   headline potential savings         $______
   sum of the provider breakdown      $______
   Do they match?                              Y / N
   Explain the difference in one line:
   ______________________________________________

4. On sheet 1, find the traceability block. What filter
   scope does it record?
   ______________________________________________

5. Check any archived recommendation export from before
   2026. Does its content match its stated filters?
                                               Y / N