# Reporting Administration Guide

## Definition graph

Reporting definitions form an exact graph:

```text
Dataset revision -> Semantic-model revision -> Report revision
                 -> Quality-plan revision
```

Create parents before children. An active child may reference only an active,
existing parent revision. Editing creates a new immutable revision and
requires the currently observed revision number. Existing runs continue to
reference the historical revisions they used.

Each definition also records system, tenant, group, or user governance scope,
whether it is inherited, and whether lower scopes may run, reuse, or automate
it. A child may tighten but never broaden any effective ancestor limit. System
definitions require system governance permission; tenant definitions are bound
to the active tenant; group and user definitions require the matching subject
unless a Reporting administrator performs the operation. Policy is consulted
for view, edit, run, reuse, and automation decisions.

Datasets may bind a static fixture, a pinned Dataflow output, or a capability
published by a source-owning module. Do not expose another module's ORM or an
unbounded SQL connection as a report source. Configure an explicit schema,
freshness policy, source fingerprint expectations, purpose, privacy,
retention, and a row-policy provider where source access alone is not enough.

On PostgreSQL installations, Reporting compiles bounded semantic filters,
grouping, measures, calculated measures, ordering, offsets, and limits into a
parameterized PostgreSQL plan over the already authorized provider rows. Field
paths and values are bound parameters and result limits remain mandatory. Pivot
plans retain the safe provider-neutral engine fallback. SQLite development and
other database engines use the same typed semantics through the bounded runtime
engine.

## Access and publication

Tenant-visible definitions are readable by principals with Reporting read
permission. Restricted reports use normalized account, identity, group, role,
function, assignment, organization-unit, or service-account grants. The
creator and Reporting administrators retain management access.

Scheduled output publication requires an installed capability implementing
the Reporting publication-target contract. The target receives one immutable
execution payload and an idempotency key. It must return bounded evidence and
must not expose credentials in that evidence.

Reporting ships two optional adapters. `reporting.publication.files` calls
`files.artifact_store` and stores an idempotent managed artifact with execution,
revision, output-hash, and file-version evidence. `reporting.publication.mail`
calls `mail.notificationDelivery` and submits an idempotent report notice to the
Mail outbox. The latter does not bypass Mail profile, credential, or transport
policy. Adapter availability is evaluated at runtime, so Reporting remains
usable with neither Files nor Mail installed.

Drill contexts expire after 20 minutes, are bound to the creating account, store
only token and context hashes, and must match the original execution output and
source fingerprints. Resolution re-runs definition and row-level authorization.
Treat a fingerprint mismatch as a required report rerun, not as a recoverable
client warning.

## Cross-module provider governance

Source modules register `reporting.report_provider.<provider-id>` capabilities;
do not grant Reporting direct table access to those modules. Review every
descriptor's result schema, required privacy transforms, retention class,
export formats, and re-identification risk before enabling it in production.
Provider authorization remains mandatory even when the Reporting role allows
the user to run reports.

When Policy is enabled, configure `reporting_governance_policy` in system or
tenant settings. Tenant settings may only tighten the system result. Supported
fields are:

```json
{
  "reporting_governance_policy": {
    "allow_exports": true,
    "allowed_export_formats": ["json"],
    "allow_high_reidentification_risk": false,
    "max_retention_days": 30,
    "required_privacy_transforms": ["small_cell_suppression"]
  }
}
```

Malformed explicit policy fails closed. The ordinary privacy-retention setting
`stored_report_detail_retention_days` is an additional ceiling. A tenant cannot
re-enable an export format, high-risk report, or longer retention period that
the system policy denied.

## Import assessments

Import assessment accepts declarative metadata only. Native datasets,
dimensions, hierarchies, measures, parameters, tables, pivots, charts,
quality assertions, and saved views map exactly. Provider-specific formatting,
dialect functions, and dashboard layouts require explicit approximation
acceptance. Raw SQL, procedures, scripts, implicit authorization, unchecked
functions, and unknown features block activation.