# Reports and exports

Klineo reports connect a vault's recorded outcomes to the evidence used to compute them. A report identifies its UTC period, immutable artifact, source coverage, benchmark assumptions, finalized actions, costs, limitations, and reconciliation references. The workspace keeps the full evidence ledger private until the issuer completes a separate public publication workflow.

## Report types and lifecycle

Outcome reports support `DAILY` and `WEEKLY` cadences. Their lifecycle includes:

| State | Meaning |
| --- | --- |
| `DRAFT` | A report exists without ready publication status |
| `READY` | The private report is ready for review and may be admitted to publication |
| `DEGRADED` | Evidence or computations are incomplete; inspect availability flags and limitations |
| `PUBLICATION_PENDING` | An exact issuer-Safe publication handoff is prepared, but finalized publication has not been established |
| `PUBLISHED` | The report has complete finalized publication evidence |

Generation and publication are different actions. A generation job, signed download, successful HTTP response, or prepared Safe transaction does not itself establish a public publication.

## Generate and read a report

Authenticated outcome-report endpoints use `/api/liquidity-studio/v1`:

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/vaults/{vaultId}/reports` | Enqueue report generation for the selected vault |
| GET | `/reports` | List reports in the current organization |
| GET | `/reports/{reportId}` | Read the selected report |
| GET | `/vaults/{vaultId}/reports/{period}` | Read `latest`, a report ID, or a matching period-start date |
| GET | `/reports/{reportId}/performance-series` | Request evidence-backed performance chart data |
| GET | `/reports/{reportId}/exports/{format}` | Download an authenticated export |

Generation requires `report:generate`, a reviewed vault version, and a closed period; a requested `periodEnd` cannot be in the future. Reads remain scoped to the authenticated organization and require vault read permission. Use the authentication, idempotency, and version-precondition requirements in the API reference when issuing mutations.

The report artifact's own availability flags are authoritative. Source coverage does not replace checking whether NAV, benchmark values, fee attribution, capital flows, gas conversion, or execution settlements are available.

## Read the Outcome Ledger

The format-neutral Outcome Ledger supplies the same canonical rows to CSV, HTML, and PDF presentations. JSON retains the complete immutable report artifact. The ledger covers:

- Opening and closing snapshots, block identities, custody balances, reserves, positions, and pool state.
- Gross and net performance, external capital flows, realized loss, turnover, fees, and costs.
- Hold and passive full-range benchmarks, their versions, availability, and evidence hashes.
- Finalized actions, failed executions, transaction references, depth changes, and outcome attribution.
- Diversification mandate and settlement evidence when present.
- Incidents, pending next decisions, canonical limitations, and the evidence hash ledger.

`contentHash` binds the canonical report artifact. `bundleHash` binds that artifact, its content hash, and evidence references. These are identifiers for exact material; comparing only a title or reporting date is insufficient to identify a report version.

## Interpret performance correctly

Raw NAV movement can include deposits and withdrawals. Gross NAV change is adjusted for external capital flows. Net results depend on exact cost coverage and may be unavailable when required inputs are missing. Do not replace an unavailable cost with zero or calculate a result that the report explicitly withholds.

Net performance versus hold follows the report's published hold definition. The passive full-range benchmark has a separate availability status, policy hash, and artifact hash. Read those definitions before comparing two reports: a benchmark is a specified counterfactual, not a forecast or an asset price guarantee.

Atomic amounts are integer strings. Preserve them as strings or arbitrary-precision integers; converting them to JavaScript `number` can lose precision. Apply the exact token decimals from the relevant asset context before displaying a token amount. Quote-token amounts are not automatically fiat amounts.

Performance series are available only when their evidence can be reconstructed. The current weekly series path requires a complete unchanged seven-day UTC weekly report, seven unique complete daily reports, matching finalized boundary snapshots, and consistent chain, pool, precision, and NAV evidence. Individual benchmark lanes may still be unavailable. The public proof endpoint supplies period results, not daily chart points.

## Export authenticated evidence

The `format` values are `json`, `csv`, `html`, and `pdf`. The export service requires an available report signer, checks report integrity, and produces an Ed25519-signed export envelope. The signature binds a domain-specific signing payload to the exact `exportHash`, key ID, and public-key fingerprint. Each export is audited before response bytes are sent.

Use JSON when a downstream system needs the complete machine-readable artifact and signature material. Use CSV for ledger analysis and HTML or PDF for review. Downloading one of these files does not make the report public.

A public key embedded in an export establishes which key was used, but does not establish that you trust that key. Obtain the signing public key through an independently authenticated channel. If you have a Klineo source checkout containing the bundled verifier, it requires that trusted key and rejects a mismatch:

```sh
node scripts/liquidity-studio/verify-report-export.mjs \
  report-evidence.json \
  "$TRUSTED_REPORT_SIGNING_SPKI_BASE64"
```

The verifier checks the canonical export hash, key fingerprint, domain-specific signing payload, and Ed25519 signature. It verifies the export envelope; it does not independently replay each chain observation or prove that every financial assumption is correct.

## Publish an outcome proof

1. Review a `READY` report, its exact content hash, period integrity, benchmark definitions, and limitations. The current v1 publication permission belongs to the organization owner.
2. Choose a unique public slug and disclosure flags: `showTreasuryAmounts`, `showPolicyLimits`, and `showIncidents`. The application preview shows intended scope; the server constructs the exact public projection.
3. Submit `POST /reports/{reportId}/publish` with the reviewed report version, idempotency key, reason, slug, and disclosure. Admission requires the period to be closed by finalized evidence, fresh finalized Safe verification, the configured results-contract release, and a valid finalized source block range.
4. Review and execute the returned exact publication transaction through the issuer Safe. The prepared handoff has a fifteen-minute execution deadline.
5. Reconcile it using `POST /reports/{reportId}/publication-finalization` with the transaction hash and current version precondition. The service must establish successful finalized execution of the exact Safe, destination, calldata, runtime bindings, and handoff window before the report becomes `PUBLISHED`.

A worker can recover finalized pending publications from canonical indexed evidence. An expired handoff is released only after finalized absence is established. Do not create a second transaction merely because a first submission is slow to appear.

The server rejects publication when an immutable diversification mandate sets public reporting to `PRIVATE`. A superseding report must bind the finalized commitment it replaces. Public readers receive the issuer-approved projection described in [public proof and Liquidity Passports](/guides/proof).

## Signed simulation study reports

Simulation studies have a separate v2 reporting workflow. `POST /api/liquidity-studio/v2/studies/{id}/reports` accepts `JSON`, `PDF`, or `CSV` formats and disclosure flags `includeDrivers`, `includeTreasury`, and `includePolicy`. It requires a completed 10,000-path study and queues signed report persistence bound to the exact study version and artifact hash. Read `/studies/{id}/report-jobs` to inspect that study's reporting jobs.

Study reports describe modeled scenarios and assumptions. Signing preserves their identity and provenance; it does not turn simulated outcomes into realized returns. A queued reporting job is also separate from successful artifact registration and retrieval.