feat(core): define managed tabular file contract

tests/test_files_tabular_contract.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import unittest
+from datetime import UTC, datetime
+
+from govoplan_core.core.files import (
+    CAPABILITY_FILES_TABULAR_CONTENT,
+    ManagedTabularFile,
+    ManagedTabularFileContent,
+    ManagedTabularFileProvider,
+    managed_tabular_file_provider,
+)
+
+
+class _Provider:
+    def list_tabular_files(self, session, principal, *, query="", limit=100):
+        del session, principal, query, limit
+        return ()
+
+    def get_tabular_file(
+        self,
+        session,
+        principal,
+        *,
+        file_asset_id,
+        file_version_id=None,
+    ):
+        del session, principal, file_asset_id, file_version_id
+        return None
+
+    def read_tabular_file(
+        self,
+        session,
+        principal,
+        *,
+        file_asset_id,
+        file_version_id,
+        max_bytes,
+    ):
+        del session, principal, file_asset_id, file_version_id, max_bytes
+        file = ManagedTabularFile(
+            file_asset_id="asset-1",
+            file_version_id="version-1",
+            filename="source.csv",
+            display_path="Imports/source.csv",
+            content_type="text/csv",
+            size_bytes=8,
+            sha256="a" * 64,
+            updated_at=datetime(2026, 8, 21, tzinfo=UTC),
+        )
+        return ManagedTabularFileContent(file=file, payload=b"id\n1\n")
+
+
+class _Registry:
+    def __init__(self, provider):
+        self.provider = provider
+
+    def has_capability(self, name):
+        return name == CAPABILITY_FILES_TABULAR_CONTENT
+
+    def require_capability(self, name):
+        if not self.has_capability(name):
+            raise KeyError(name)
+        return self.provider
+
+
+class ManagedTabularFileContractTests(unittest.TestCase):
+    def test_runtime_protocol_and_registry_resolution(self) -> None:
+        provider = _Provider()
+
+        self.assertIsInstance(provider, ManagedTabularFileProvider)
+        self.assertIs(provider, managed_tabular_file_provider(_Registry(provider)))
+        self.assertIsNone(managed_tabular_file_provider(None))
+
+    def test_exact_version_content_retains_safe_metadata(self) -> None:
+        result = _Provider().read_tabular_file(
+            object(),
+            object(),
+            file_asset_id="asset-1",
+            file_version_id="version-1",
+            max_bytes=100,
+        )
+
+        self.assertEqual("version-1", result.file.file_version_id)
+        self.assertEqual("a" * 64, result.file.sha256)
+        self.assertEqual(b"id\n1\n", result.payload)
+
+
+if __name__ == "__main__":
+    unittest.main()