Browse pages
Reporting and Exports
Reporting separates complex joins, aggregate analysis, and large exports from normal request projections when cost or duration exceeds the baseline read path.
Intent#
Reporting separates complex joins, aggregate analysis, and large exports from normal request projections when cost or duration exceeds the baseline read path.
Activation#
Activation scope: local.
Applicable specification kinds: use-case.
The consumer enables report for a documented query or export with complex relational SQL, large results, long processing, object storage, or exceptional latency budget.
Baseline relationship#
None. Ordinary queries stay under litespec/backend/persistence#query-through-the-read-session; this extension governs reads whose cost or duration exceeds that path.
limit. Selecting report requires Limit records for the request budget and the report bounds.
Standards#
Record reporting need#
ruleguidancelitespec/ext/report#record-reporting-needA reporting proposal MUST record the report, representative data volume, plan or limitation, latency target, maximum result, and operating owner.
Why
The record establishes why a normal request projection cannot meet the documented boundary. The use-case page carries the record with its owner and status.
Checka reviewer answers
Does the use-case page record the report, volume, plan, target, maximum, and owner?
Marked guidance: a reviewer answers this question.
Avoid speculative reporting systems#
ruleguidancelitespec/ext/report#avoid-speculative-reporting-systemsA project MUST NOT create reporting infrastructure for possible future analytics.
Why
Reporting infrastructure needs an accepted query or export with a present cost boundary.
Checka reviewer answers
Does reporting serve an accepted current query or export?
Marked guidance: a reviewer answers this question.
Parameterize report SQL#
ruleguidancelitespec/ext/report#parameterize-report-sqlA reporting query MUST parameterize every actor, tenant, filter, range, sort, and pagination value.
Why
Parameters preserve data isolation and protect raw SQL from injection.
Checka reviewer answers
Does every report query bind actor, tenant, filter, range, sort, and pagination values?
Marked guidance: a reviewer answers this question.
Keep raw SQL in Infrastructure#
ruleguidancelitespec/ext/report#keep-raw-sql-in-infrastructureInfrastructure MUST own raw reporting SQL and connection handling.
Why
Provider-specific query and connection behavior stays outside Application and Domain.
Checka reviewer answers
Do raw report SQL and connection handling live in Infrastructure?
Marked guidance: a reviewer answers this question.
Review report plans#
ruleguidancelitespec/ext/report#review-report-plansA report owner MUST review query plans and indexes with representative data.
Why
Representative volumes reveal cost that small local datasets can hide.
Checka reviewer answers
Did the owner review plans and indexes on representative data?
Marked guidance: a reviewer answers this question.
Apply item-read authorization#
ruleguidancelitespec/ext/report#apply-item-read-authorizationA report or export MUST enforce actor, role, ownership, tenant, and sensitive-field rules that apply to item reads.
Why
A bulk interface cannot bypass data access checks applied to individual resources.
Checka reviewer answers
Does each report and export enforce the item-read rules?
Marked guidance: a reviewer answers this question.
Run budget-exceeding exports in Worker#
ruleguidancelitespec/ext/report#run-budget-exceeding-exports-in-workerAn export exceeding its request budget MUST run through Worker, with the budget a Limit record the export's use case names.
Why
Worker execution frees the HTTP request from long-running report work.
Checka reviewer answers
Does each export past its request budget run through Worker?
Marked guidance: a reviewer answers this question.
Protect export output#
ruleguidancelitespec/ext/report#protect-export-outputAn export worker MUST store output in approved object storage with an owner, expiry, and short-lived authorized download.
Why
Export files can contain sensitive data and need controlled access and retention.
Checka reviewer answers
Does export output carry an owner and expiry with short-lived authorized download?
Marked guidance: a reviewer answers this question.
Scope export output to the tenant#
ruleguidancelitespec/ext/report#scope-export-output-to-the-tenantAn export MUST store its output under a tenant-scoped object-storage path.
Why
A shared output path lets one tenant guess another tenant's export address.
Checka reviewer answers
Does each export store its output under a tenant-scoped path?
Marked guidance: a reviewer answers this question.
Define report limits#
ruleguidancelitespec/ext/report#define-report-limitsA report specification MUST state each bound as a Limit record: maximum date range, rows, execution time, concurrent jobs, output size, and storage lifetime.
Why
Explicit limits bound database, Worker, and object-storage cost.
Checka reviewer answers
Does each report bound live as a Limit record?
Marked guidance: a reviewer answers this question.
Support report cancellation#
ruleguidancelitespec/ext/report#support-report-cancellationA report implementation MUST support cancellation and remove expired outputs.
Why
Cancellation and expiry prevent abandoned work and files from consuming resources indefinitely.
Checka reviewer answers
Does report work cancel, and does expired output clear?
Marked guidance: a reviewer answers this question.
Escape formula-leading export values#
ruleguidancelitespec/ext/report#escape-formula-leading-export-valuesA CSV or spreadsheet export MUST escape formula-leading values unless a reviewed field intentionally contains a formula.
Why
Spreadsheet applications can interpret unescaped values as executable formulas.
Checka reviewer answers
Are formula-leading export values escaped except for reviewed formula fields?
Marked guidance: a reviewer answers this question.
Define export encoding and columns#
ruleguidancelitespec/ext/report#define-export-encoding-and-columnsAn export format MUST use explicit character encoding and a stable column contract.
Why
Stable output lets consumers parse data without locale or implementation assumptions.
Checka reviewer answers
Does each export state its encoding and stable columns?
Marked guidance: a reviewer answers this question.
Conventions#
Keep report definitions in Application#
conventionguidancelitespec/ext/report#keep-report-definitions-in-applicationKeep report definitions in Application under their business module.
ReplacementA consumer replaces this default by recording an Exception for this provision, with reason and review date.
Why
Business meaning and authorization belong with the module that owns the report.
Checka reviewer answers
Do report definitions live in their module or a recorded Exception?
Marked guidance: a reviewer answers this question.
Keep report providers in Infrastructure#
conventionguidancelitespec/ext/report#keep-report-providers-in-infrastructureKeep SQL, row mappings, and storage providers in Infrastructure.
ReplacementA consumer replaces this default by recording an Exception for this provision, with reason and review date.
Why
Query and storage implementation details are provider boundaries.
Checka reviewer answers
Do SQL and storage code live in Infrastructure or a recorded Exception?
Marked guidance: a reviewer answers this question.
Separate Worker orchestration#
conventionguidancelitespec/ext/report#separate-worker-orchestrationKeep Worker orchestration separate from report business rules.
ReplacementA consumer replaces this default by recording an Exception for this provision, with reason and review date.
Why
Worker scheduling and execution do not define report authorization or meaning.
Checka reviewer answers
Is Worker orchestration separate from report business rules or a recorded Exception?
Marked guidance: a reviewer answers this question.
Dependencies#
The extension selects no report or object-storage package by default. Each provider needs a decision and manifest pin.
Verification#
| ID | Mark | Evidence |
|---|---|---|
| litespec/ext/report#record-reporting-need | guidance | Does the use-case page record the report, volume, plan, target, maximum, and owner? |
| litespec/ext/report#avoid-speculative-reporting-systems | guidance | Does reporting serve an accepted current query or export? |
| litespec/ext/report#parameterize-report-sql | guidance | Does every report query bind actor, tenant, filter, range, sort, and pagination values? |
| litespec/ext/report#keep-raw-sql-in-infrastructure | guidance | Do raw report SQL and connection handling live in Infrastructure? |
| litespec/ext/report#review-report-plans | guidance | Did the owner review plans and indexes on representative data? |
| litespec/ext/report#apply-item-read-authorization | guidance | Does each report and export enforce the item-read rules? |
| litespec/ext/report#run-budget-exceeding-exports-in-worker | guidance | Does each export past its request budget run through Worker? |
| litespec/ext/report#protect-export-output | guidance | Does export output carry an owner and expiry with short-lived authorized download? |
| litespec/ext/report#scope-export-output-to-the-tenant | guidance | Does each export store its output under a tenant-scoped path? |
| litespec/ext/report#define-report-limits | guidance | Does each report bound live as a Limit record? |
| litespec/ext/report#support-report-cancellation | guidance | Does report work cancel, and does expired output clear? |
| litespec/ext/report#escape-formula-leading-export-values | guidance | Are formula-leading export values escaped except for reviewed formula fields? |
| litespec/ext/report#define-export-encoding-and-columns | guidance | Does each export state its encoding and stable columns? |
| litespec/ext/report#keep-report-definitions-in-application | guidance | Do report definitions live in their module or a recorded Exception? |
| litespec/ext/report#keep-report-providers-in-infrastructure | guidance | Do SQL and storage code live in Infrastructure or a recorded Exception? |
| litespec/ext/report#separate-worker-orchestration | guidance | Is Worker orchestration separate from report business rules or a recorded Exception? |