Metadata-Version: 2.4
Name: govoplan-datasources
Version: 0.1.17
Summary: Governed datasource catalogue, staging, and materialization lifecycle for GovOPlaN.
Author: GovOPlaN
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: govoplan-core>=0.1.17

# govoplan-datasources

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

`govoplan-datasources` is GovOPlaN's provider-neutral data access layer. It owns
the tenant catalogue, lifecycle, staging, immutable materializations, frozen
states, schema and fingerprint metadata, provenance, and bounded reads.

The module deliberately separates two layers:

- **Datasources** describe governed data that modules can consume consistently.
- **Connectors** acquire data from external systems and expose provider origins.

Dataflow, Workflow, Reporting, Risk Compliance, and other consumers depend on
Datasource contracts rather than connector implementations.

The first executable slice supports tabular static uploads, connector-backed
live and cached sources, staging and promotion, refresh, immutable snapshots,
explicit frozen states, previews, retirement, and atomic producer publication.
Origin discovery retains each provider's source mode, structured health, and
declared pushdown support. Live previews preserve the provider's effective row,
serialized-byte, and elapsed-time limits and its redacted diagnostics.
Producer modules can append a bounded tabular result or create a new static
datasource through an idempotent capability. The publication ledger retains the
producer run, output materialization, provenance, and replay identity. On
PostgreSQL, a transaction-scoped advisory lock serializes each tenant, producer,
and idempotency identity before any output side effect, so retries from multiple
application or worker nodes resolve to one durable publication.

Tabular staging also evaluates governed quality rules and classifies schema
changes before promotion. Blocking stages remain inspectable, and successful
promotion preserves the exact policy hash and validation result in immutable
materialization provenance. The supported contract is documented in
[docs/QUALITY_POLICY.md](docs/QUALITY_POLICY.md).

The contracts already model database, HTTP/REST, directory, file, feed,
document, binary, directory, and stream sources so providers can be added
without changing consumers. Larger durable artifact-backed publications remain
a later storage-provider slice.

See [docs/CONCEPT.md](docs/CONCEPT.md) for ownership and lifecycle details.
