govoplan-core/docs/TABULAR_SOURCE_CONTRACT.md

# Tabular Source Preview Contract

Core defines provider-neutral DTOs for optional tabular source providers. A
source declares whether it is live, cached, file-backed, or static; its schema
and immutable fingerprint; structured health; and the exact projection,
pagination, filter, aggregation, and sorting operations that the provider can
push down. Consumers must not infer pushdown support from a provider name.

Every preview request carries independent row, byte, and elapsed-time budgets.
A provider may tighten these values but must return its effective limits,
returned byte count, elapsed milliseconds, truncation state, and structured
diagnostics. Equivalent fields on the Datasources read request and result
preserve that evidence when a live source is consumed through the catalogue.
A row that cannot fit within the byte budget fails explicitly rather than
leaking a partial value. Timeout, stale fingerprint, unavailable source, and
authorization failures remain distinct provider-neutral errors.

Connector health and preview diagnostics must contain no credentials, endpoint
userinfo, row values, or unbounded remote error bodies. A Datasource origin
preserves this contract so registration and staging do not erase source mode,
health, pushdown, or preview-limit evidence.

## Durable CSV imports and original evidence

`TabularCsvSource` optionally accompanies a durable `TabularSnapshotInput` or
`DatasourceStageInput`. It carries the exact submitted Unicode text, delimiter,
explicit value mode and parser profile. It is not part of ordinary catalogue,
preview or stage DTOs. Transient inspection does not retain original content.

The `text` mode preserves cell strings, including whitespace, leading zeroes,
decimal spelling, boolean-looking text and explicit empty cells. It rejects
malformed quoting and rows with missing or extra cells. Header normalization is
unchanged. The API default remains `legacy_typed` for existing integrations;
interactive CSV imports offer text mode by default and an explicit legacy choice.
JSON and existing stored snapshots are not reinterpreted. Core and Datasources
retain distinct versioned legacy parser profiles where their historical coercion
rules differ. Shared schema inference preserves first-seen column order, missing
value nullability and the owning provider's type naming.

Owners verify that the source reparses to exactly the stored projection, including
scalar types: `true`, `1` and `1.0` are not equivalent evidence. Raw input and row
projections each have a 5,000,000-byte limit; row parsing is capped at 10,000 rows.
The original text has its own UTF-8 SHA-256 and byte count, separate from the
existing row fingerprint. Only a small allowlisted source summary enters metadata.
Checksums detect drift; they are not digital signatures or protection against an
attacker who can rewrite the database and all its evidence.

Original exports are explicit owner APIs, tenant scoped, integrity checked and
`no-store`. Datasources additionally requires administrator scope, audits the
export, and denies the whole original when current or historical governance
restricts any row or field. Freezing verifies the prior summary before copying
source evidence and retains prior policy restrictions, including referenced
policy evaluations. At most 32 distinct governance snapshots may accompany one
original; further incompatible history fails explicitly. Payload disposal also
disposes retained original content. Connectors applies its own current read,
tenant and lifecycle checks. See the owning module's documentation for endpoints.

Original UTF-8 text is not proof of pre-decoding file bytes, and does not undo
CSV spreadsheet formula semantics. Exported content is deliberately unmodified;
operators must treat it as untrusted input when opening it in a spreadsheet.
New nullable columns require the owning modules' additive migrations. Historical
rows remain unchanged and report original content unavailable, not reconstructed.
Back up retained originals before any schema downgrade that removes those columns.

## Deutsch: CSV-Datentreue

Dauerhafte CSV-Importe können den unveränderten übermittelten Unicode-Text mit
Trennzeichen, Parserprofil und explizitem Wertemodus aufbewahren. Der Textmodus
erhält Zellwerte einschließlich Leerzeichen, führender Nullen und Dezimalschreibweise.
Fehlerhafte Zeilen werden abgewiesen. Die API bleibt aus Kompatibilitätsgründen bei
der bisherigen Typumwandlung als Standard; im Importdialog ist Text voreingestellt.
Bestehende Daten und JSON-Importe werden nicht neu interpretiert.

Original und Zeilenprojektion werden getrennt begrenzt und geprüft; boolesche
Werte, Ganzzahlen und Gleitkommazahlen sind keine austauschbaren Belege. Der
Originaltext erscheint weder im Katalog noch in Vorschauantworten. Die expliziten
Export-APIs prüfen Mandant, Berechtigungen, Lebenszyklus und gespeicherten Hash.
Datasources verlangt zusätzlich Administrationsrechte, protokolliert Exporte und
berücksichtigt aktuelle sowie historische Zeilen-, Feld- und Zugriffsrichtlinien.
Eingeschränkte Originale werden vollständig gesperrt, nicht teilweise freigegeben.
Eingefrorene Kopien übernehmen diese Einschränkungen; nach 32 unterschiedlichen
Richtlinienständen wird eine weitere Kopie mit neuer Richtlinie explizit abgewiesen.
Die Aufbewahrungsbereinigung entfernt auch das gespeicherte Original.

Die Grenzen betragen jeweils 5.000.000 UTF-8-Bytes für Original und Projektion
sowie 10.000 Zeilen. Prüfsummen sind keine Signaturen. Ein CSV-Original bleibt beim
Export unverändert und kann Tabellenkalkulationsformeln enthalten. Frühere
Dateikodierungen lassen sich daraus nicht rekonstruieren. Additive Migrationen
ändern keine historischen Zeilen; fehlende Originale werden nicht erfunden.
Vor einem Schema-Downgrade sind aufbewahrte Originale zu sichern.