feat(files): expose exact versions for records filing

src/govoplan_files/backend/manifest.py

@@ -13,6 +13,7 @@ from govoplan_core.core.files import (
 )
 from govoplan_core.core.module_guards import drop_table_retirement_provider, persistent_table_uninstall_guard
 from govoplan_core.core.modules import (
+    CapabilityDocumentation,
     DocumentationCondition,
     DocumentationLink,
     DocumentationTopic,
@@ -46,6 +47,10 @@ from govoplan_files.backend.provider_state import (
     remote_storage_provider_states,
 )
 from govoplan_files.backend.search_source import create_files_search_source
+from govoplan_files.backend.record_source import (
+    CAPABILITY_RECORD_SOURCE_FILES,
+    create_files_record_source,
+)
 
 register_files_change_tracking()
 
@@ -281,11 +286,12 @@ manifest = ModuleManifest(
     name="Files",
     version="0.1.18",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
-    optional_dependencies=("campaigns", "encryption", "search"),
+    optional_dependencies=("campaigns", "encryption", "records", "search"),
     provides_interfaces=(
         ModuleInterfaceProvider(name="files.access", version="0.1.6"),
         ModuleInterfaceProvider(name="files.campaign_attachments", version="0.1.6"),
         ModuleInterfaceProvider(name=CAPABILITY_FILES_ARTIFACT_STORE, version="0.1.14"),
+        ModuleInterfaceProvider(name=CAPABILITY_RECORD_SOURCE_FILES, version="1.0.0"),
     ),
     requires_interfaces=(
         ModuleInterfaceRequirement(
@@ -343,6 +349,49 @@ manifest = ModuleManifest(
         ),
     ),
     documentation=(
+        DocumentationTopic(
+            id="files.records.exact-version-source",
+            title="File exact versions into an eAkte",
+            summary="Let Records preserve an immutable Files version reference after current access and integrity checks.",
+            body=(
+                "When Records is enabled, Files exposes exact managed FileVersion identities through the "
+                "provider-neutral record-source contract. Filing verifies the active tenant, current Files "
+                "permission and owner/share access, the immutable version identity, and the managed blob "
+                "integrity gate. Records receives the filename, path, version, digest, media type, size, "
+                "protection state, and filing launch link; Files continues to own the bytes."
+            ),
+            layer="configured",
+            documentation_types=("admin", "user"),
+            audience=("file_user", "file_manager", "records_manager", "auditor"),
+            related_modules=("records",),
+            order=40,
+            conditions=(
+                DocumentationCondition(
+                    required_modules=("files", "records"),
+                    required_scopes=("files:file:read",),
+                ),
+            ),
+            links=(
+                DocumentationLink(label="Files", href="/files", kind="runtime"),
+                DocumentationLink(label="Records", href="/records", kind="runtime"),
+                DocumentationLink(label="Files handbook", href="govoplan-files/docs/FILES_HANDBOOK.md", kind="repository"),
+            ),
+            metadata={
+                "kind": "workflow",
+                "help_contexts": ["files.list", "records.action.file"],
+                "prerequisites": [
+                    "The exact file version exists and passes the current Files integrity gate.",
+                    "You currently have Files read access and Records filing authority.",
+                ],
+                "steps": [
+                    "Select the exact managed file version that belongs to the institutional record.",
+                    "Choose the destination record and state the access purpose and filing reason.",
+                    "Confirm filing; Files rechecks current access and resolves the exact version.",
+                    "Open the record chronology and verify the version identity and SHA-256 digest.",
+                ],
+                "outcome": "Records preserves an exact governed reference while Files remains byte authority.",
+            },
+        ),
         DocumentationTopic(
             id="files.search.managed-content",
             title="Search managed files and folders",
@@ -903,6 +952,14 @@ manifest = ModuleManifest(
         CAPABILITY_FILES_ACCESS: lambda context: __import__("govoplan_files.backend.capabilities", fromlist=["access_capability"]).access_capability(context),
         CAPABILITY_FILES_ARTIFACT_STORE: lambda context: __import__("govoplan_files.backend.capabilities", fromlist=["artifact_store_capability"]).artifact_store_capability(context),
         "files.campaign_attachments": lambda context: __import__("govoplan_files.backend.capabilities", fromlist=["campaign_capability"]).campaign_capability(context),
+        CAPABILITY_RECORD_SOURCE_FILES: create_files_record_source,
+    },
+    capability_documentation={
+        CAPABILITY_RECORD_SOURCE_FILES: CapabilityDocumentation(
+            label="Files record source",
+            summary="Resolves currently authorized immutable managed file versions for Records filing.",
+            contract_version="1.0.0",
+        ),
     },
     operational_check_providers=(
         OperationalCheckProviderRegistration(