Define bounded tabular source contracts

tests/test_tabular_source_contract.py

@@ -2,17 +2,25 @@ from __future__ import annotations
 
 import unittest
 
+from govoplan_core.core.datasources import (
+    DatasourceDescriptor,
+    DatasourceReadRequest,
+    DatasourceReadResult,
+)
 from govoplan_core.core.modules import ModuleContext, ModuleManifest
 from govoplan_core.core.registry import PlatformRegistry
 from govoplan_core.core.tabular_sources import (
     CAPABILITY_CONNECTORS_TABULAR_SNAPSHOT_WRITER,
     CAPABILITY_CONNECTORS_TABULAR_SOURCES,
     TabularColumn,
+    TabularPreviewDiagnostic,
+    TabularPushdown,
     TabularReadRequest,
     TabularReadResult,
     TabularSnapshotInput,
     TabularSnapshotWriter,
     TabularSource,
+    TabularSourceHealth,
     TabularSourceProvider,
     TabularSourceValidationError,
     parse_tabular_csv,
@@ -30,6 +38,13 @@ class _TabularProvider:
         schema=(TabularColumn(name="case_id", data_type="string", nullable=False),),
         fingerprint="abc123",
         row_count=1,
+        source_mode="cached",
+        pushdown=TabularPushdown(projections=True, pagination=True),
+        health=TabularSourceHealth(
+            status="healthy",
+            code="snapshot.ready",
+            summary="Immutable snapshot is ready.",
+        ),
     )
 
     def list_sources(self, session, principal, *, query="", limit=100):
@@ -51,6 +66,18 @@ class _TabularProvider:
             rows=selected,
             total_rows=len(rows),
             truncated=len(selected) < len(rows),
+            returned_bytes=18,
+            elapsed_ms=1,
+            effective_row_limit=request.limit,
+            effective_byte_limit=request.max_bytes,
+            effective_timeout_ms=request.timeout_ms,
+            diagnostics=(
+                TabularPreviewDiagnostic(
+                    severity="info",
+                    code="preview.bounded",
+                    message="The preview used explicit budgets.",
+                ),
+            ),
         )
 
     def create_snapshot(self, session, principal, *, snapshot):
@@ -96,8 +123,47 @@ class TabularSourceContractTests(unittest.TestCase):
         )
 
         self.assertEqual(({"case_id": "A-1"},), result.rows)
+        self.assertEqual("cached", result.source.source_mode)
+        self.assertTrue(result.source.pushdown.projections)
+        self.assertEqual("healthy", result.source.health.status)
+        self.assertEqual("preview.bounded", result.diagnostics[0].code)
+        self.assertEqual(1_000_000, request.max_bytes)
+        self.assertEqual(2_000, request.timeout_ms)
         self.assertEqual(provider.source, provider.create_snapshot(object(), object(), snapshot=snapshot))
 
+    def test_datasource_read_contract_preserves_live_preview_evidence(self) -> None:
+        request = DatasourceReadRequest(datasource_ref="datasource:monthly-cases")
+        result = DatasourceReadResult(
+            datasource=DatasourceDescriptor(
+                ref=request.datasource_ref,
+                source_name="monthly_cases",
+                name="Monthly cases",
+                kind="database",
+                mode="live",
+                shape="tabular",
+            ),
+            rows=(),
+            total_rows=0,
+            truncated=False,
+            returned_bytes=2,
+            elapsed_ms=3,
+            effective_row_limit=request.limit,
+            effective_byte_limit=request.max_bytes,
+            effective_timeout_ms=request.timeout_ms,
+            diagnostics=(
+                TabularPreviewDiagnostic(
+                    severity="info",
+                    code="preview.complete",
+                    message="The bounded preview completed.",
+                ),
+            ),
+        )
+
+        self.assertEqual(1_000_000, request.max_bytes)
+        self.assertEqual(2_000, request.timeout_ms)
+        self.assertEqual(2, result.returned_bytes)
+        self.assertEqual("preview.complete", result.diagnostics[0].code)
+
     def test_shared_csv_parser_preserves_identifier_zeroes_and_rejects_extra_values(self) -> None:
         rows = parse_tabular_csv(
             "case_id;amount;active\n0012;7.5;true\n\n",