Report jobs

Report Factory accepts a versioned, host-neutral job envelope. The same document can be preflighted by wolfxl-report-factory or scheduled by the durable wolfxl-runner; hosts do not need to know the Python request class for the selected recipe.

{
  "schema_version": 1,
  "kind": "report_job",
  "workflow": "monthly_operating_review",
  "request": {
    "schema_version": 1,
    "request_id": "august-review",
    "template_path": "monthly-review.xlsx",
    "outputs": {
      "xlsx": "out/august-review.xlsx",
      "pdf": "out/august-review.pdf"
    },
    "transactions": [
      {
        "period": "Aug",
        "region": "West",
        "account": "Services",
        "revenue": 125.0,
        "expense": 70.0
      }
    ],
    "kpis": {"total_revenue": 125.0, "target_revenue": 150.0},
    "periods": [{"label": "Aug", "revenue": 125.0}],
    "max_rows": 1000,
    "max_columns": 5,
    "logo": null,
    "data_sheet": "Data"
  }
}

The envelope schema and the recipe request schema are intentionally versioned separately. Unknown envelope fields, workflow identifiers, kinds, and schema versions fail closed before a workbook is opened. Workflow dispatch is closed and engine-owned; a request cannot import or execute a caller-named Python function.

Single-job execution

wolfxl-report-factory preflight report-job.json
wolfxl-report-factory generate report-job.json

For compatibility, these commands still accept the original unwrapped monthly_operating_review request document. New durable integrations should write the explicit envelope.

Durable batches

Batch schema version 2 stores report-job envelopes:

{
  "schema_version": 2,
  "policy": "per_job",
  "max_concurrency": 4,
  "items": [
    {
      "schema_version": 1,
      "kind": "report_job",
      "workflow": "monthly_operating_review",
      "request": {"...": "same request fields as above"}
    }
  ]
}

Batch schema version 1 remains readable and resumable. It contains unwrapped monthly operating review request objects in items. The runner promotes each one to a report job in memory and persists new immutable plans with the generic envelope; it never rewrites an existing version 1 run.

The existing MonthlyOperatingReviewRequest, preflight_monthly_operating_review, generate_monthly_operating_review, and run_monthly_operating_review Python APIs remain supported as the compatibility recipe surface.