GovOPlaN/govoplan-records
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(records): govern lifecycle recovery and transfer evidence

Browse Source
This commit is contained in:
zemion
2026-08-06 05:36:18 +02:00
parent f316523a1d
commit df51bb1787
22 changed files with 4954 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/test_records.py
+416 -5
View File
@@ -2,16 +2,22 @@ from __future__ import annotations
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
import json
from pathlib import Path
import unittest
from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from govoplan_core.core.records import (
RecordArchiveProviderState,
RecordArchiveReceipt,
RecordFilingRequest,
RecordSourceLocator,
RecordSourceReference,
)
from govoplan_core.core.recovery import RecoveryCheckpoint, RecoveryOperation
from govoplan_core.core.approvals import ApprovalCheck, ApprovalRequestRef
from govoplan_core.core.temporal import (
TemporalDataContext,
bind_temporal_data_context,
@@ -20,12 +26,16 @@ from govoplan_core.core.temporal import (
from govoplan_records.backend.db.models import (
RecordChronologyEntry,
RecordClassRevision,
RecordDispositionRevision,
RecordFilePlanRevision,
RecordHoldRevision,
RecordIdentity,
RecordItem,
RecordRevision,
RecordTransferPackageRevision,
RecordVolumeRevision,
)
from govoplan_records.backend.archive import SimulatedRecordArchiveProvider
from govoplan_records.backend.service import RecordConflictError, SqlRecordRegistry
@@ -63,21 +73,114 @@ class SourceProvider:
)
class UnknownOutcomeArchiveProvider:
provider_id = "unknown_simulation"
def __init__(self) -> None:
self.dispatch_count = 0
def state(self):
return RecordArchiveProviderState(
provider_id=self.provider_id,
label="Unknown-outcome simulation",
profiles=("govoplan-unknown-outcome-v1",),
authority_modes=("linked_reference",),
healthy=True,
checked_at=NOW,
simulated=True,
)
def dispatch(self, session, principal, *, request):
del session, principal
self.dispatch_count += 1
return RecordArchiveReceipt(
provider_id=self.provider_id,
package_id=request.package.package_id,
outcome="outcome_unknown",
observed_at=NOW + timedelta(minutes=12),
receipt_sha256="b" * 64,
retry_safe=False,
simulated=True,
metadata={"custody_transferred": False},
)
class Registry:
def __init__(self) -> None:
self.provider = SourceProvider()
self.archive_provider = SimulatedRecordArchiveProvider()
self.unknown_archive_provider = UnknownOutcomeArchiveProvider()
self.approvals = ApprovalProvider()
def capability_names(self):
return ("records.source.files",)
return (
"records.source.files",
"records.archive.simulation",
"records.archive.unknown_simulation",
)
def tenant_capability(self, name, session, *, tenant_id):
del session
return (
self.provider
if name == "records.source.files" and tenant_id == "tenant-1"
else None
if tenant_id != "tenant-1":
return None
return {
"records.source.files": self.provider,
"records.archive.simulation": self.archive_provider,
"records.archive.unknown_simulation": self.unknown_archive_provider,
"approvals.requests": self.approvals,
}.get(name)
class ApprovalProvider:
def __init__(self) -> None:
self.approved = False
self.request = None
def create_request(self, session, principal, *, command, idempotency_key):
del session, principal, idempotency_key
self.request = command
return ApprovalRequestRef(id="approval-1", revision=1, state="pending")
def check_approved(
self,
session,
principal,
*,
request_id,
subject_module,
subject_type,
subject_id,
subject_version,
subject_digest,
):
del session, principal
return ApprovalCheck(
request_id=request_id,
revision=2 if self.approved else 1,
state="approved" if self.approved else "pending",
approved=self.approved,
subject_module=subject_module,
subject_type=subject_type,
subject_id=subject_id,
subject_version=subject_version,
subject_digest=subject_digest,
)
def create_template(self, *args, **kwargs):
raise NotImplementedError
def revise_template(self, *args, **kwargs):
raise NotImplementedError
def publish_template(self, *args, **kwargs):
raise NotImplementedError
def get_request(self, *args, **kwargs):
return None
def decide(self, *args, **kwargs):
raise NotImplementedError
class RecordsTests(unittest.TestCase):
def setUp(self) -> None:
@@ -90,6 +193,11 @@ class RecordsTests(unittest.TestCase):
RecordVolumeRevision.__table__,
RecordItem.__table__,
RecordChronologyEntry.__table__,
RecordHoldRevision.__table__,
RecordDispositionRevision.__table__,
RecordTransferPackageRevision.__table__,
RecoveryOperation.__table__,
RecoveryCheckpoint.__table__,
):
table.create(self.engine)
self.session = Session(self.engine)
@@ -400,6 +508,309 @@ class RecordsTests(unittest.TestCase):
self.records.source_providers(self.session, self.principal),
)
def test_governed_lifecycle_hold_disposition_and_transfer_simulation(self) -> None:
fixture = json.loads(
(
Path(__file__).parent / "fixtures/service_to_decision_journey.json"
).read_text(encoding="utf-8")
)
expected = fixture["expected"]
self._create_record()
closed = self.records.close_record(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_revision": 1,
"purpose": "close completed case record",
"reason": "The administrative decision is final.",
"recorded_at": NOW + timedelta(minutes=2),
"idempotency_key": "record-close-1",
},
)
self.assertEqual(expected["closed_state"], closed["state"])
self.assertEqual(
NOW + timedelta(minutes=2, days=3650),
datetime.fromisoformat(str(closed["retention_due_at"])),
)
appraised = self.records.appraise_record(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_revision": 2,
"outcome": "transfer",
"purpose": "appraise completed record",
"reason": "Transfer to the institutional archive after review.",
"policy_refs": ["records-policy:v1"],
"override_retention_not_due": True,
"recorded_at": NOW + timedelta(minutes=3),
"idempotency_key": "record-appraise-1",
},
)
self.assertEqual(expected["appraised_state"], appraised["state"])
hold = self.records.apply_hold(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_record_revision": 3,
"reason": "Pending judicial review.",
"authority": "Court order 2026-17",
"purpose": "preserve evidence",
"recorded_at": NOW + timedelta(minutes=4),
"idempotency_key": "record-hold-1",
},
)
with self.assertRaisesRegex(RecordConflictError, "active record hold"):
self.records.propose_disposition(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_record_revision": 3,
"action": "transfer",
"reason": "Transfer after retention.",
"purpose": "dispose record",
"recorded_at": NOW + timedelta(minutes=5),
"idempotency_key": "record-disposition-blocked",
},
)
self.records.release_hold(
self.session,
self.principal,
record_id="record-1",
hold_id=str(hold["hold_id"]),
payload={
"expected_hold_revision": 1,
"reason": "Judicial review is complete.",
"purpose": "resume disposition",
"recorded_at": NOW + timedelta(minutes=6),
"idempotency_key": "record-hold-release-1",
},
)
disposition = self.records.propose_disposition(
self.session,
self.principal,
record_id="record-1",
payload={
"disposition_id": "disposition-1",
"expected_record_revision": 3,
"action": "transfer",
"reason": "Transfer after independent review.",
"purpose": "dispose record",
"policy_refs": ["records-policy:v1"],
"recorded_at": NOW + timedelta(minutes=7),
"idempotency_key": "record-disposition-1",
},
)
self.assertEqual("review_pending", disposition["status"])
self.assertFalse(disposition["consequence_preview"]["external_effect"])
self.records.registry.approvals.approved = True
finalized = self.records.finalize_disposition(
self.session,
self.principal,
record_id="record-1",
disposition_id="disposition-1",
payload={
"expected_disposition_revision": 1,
"purpose": "approve disposition",
"recorded_at": NOW + timedelta(minutes=8),
"idempotency_key": "record-disposition-finalize-1",
},
)
self.assertEqual(expected["approved_state"], finalized["record"]["state"])
package = self.records.prepare_transfer_package(
self.session,
self.principal,
record_id="record-1",
payload={
"package_id": "package-1",
"disposition_id": "disposition-1",
"expected_record_revision": 4,
"provider_id": "simulation",
"profile": "govoplan-simulation-v1",
"purpose": "validate archive transfer",
"recorded_at": NOW + timedelta(minutes=9),
"idempotency_key": "record-package-1",
},
)
self.assertEqual("prepared", package["status"])
receipt = self.records.dispatch_transfer_package(
self.session,
self.principal,
record_id="record-1",
package_id="package-1",
payload={
"expected_package_revision": 1,
"purpose": "validate archive transfer",
"recorded_at": NOW + timedelta(minutes=10),
"idempotency_key": "record-package-dispatch-1",
},
)
self.session.commit()
self.assertEqual(expected["transfer_status"], receipt["status"])
self.assertTrue(receipt["simulated"])
self.assertEqual(
expected["custody_transferred"],
receipt["receipt"]["metadata"]["custody_transferred"],
)
detail = self.records.get_record(
self.session, self.principal, record_id="record-1"
)
self.assertEqual("released", detail["holds"][0]["status"])
self.assertEqual(
expected["disposition_status"], detail["dispositions"][0]["status"]
)
self.assertEqual("simulated_accepted", detail["transfer_packages"][0]["status"])
unknown_package = self.records.prepare_transfer_package(
self.session,
self.principal,
record_id="record-1",
payload={
"package_id": "package-unknown",
"disposition_id": "disposition-1",
"expected_record_revision": 4,
"provider_id": "unknown_simulation",
"profile": "govoplan-unknown-outcome-v1",
"purpose": "exercise unknown transfer recovery",
"recorded_at": NOW + timedelta(minutes=11),
"idempotency_key": "record-package-unknown",
},
)
unknown_receipt = self.records.dispatch_transfer_package(
self.session,
self.principal,
record_id="record-1",
package_id="package-unknown",
payload={
"expected_package_revision": unknown_package["revision"],
"purpose": "exercise unknown transfer recovery",
"recorded_at": NOW + timedelta(minutes=12),
"idempotency_key": "record-package-unknown-dispatch",
},
)
self.assertEqual("outcome_unknown", unknown_receipt["status"])
self.assertFalse(unknown_receipt["receipt"]["retry_safe"])
with self.assertRaisesRegex(
ValueError, "unknown outcomes require reconciliation"
):
self.records.dispatch_transfer_package(
self.session,
self.principal,
record_id="record-1",
package_id="package-unknown",
payload={
"expected_package_revision": 2,
"purpose": "must not retry unknown transfer",
"recorded_at": NOW + timedelta(minutes=13),
"idempotency_key": "record-package-unknown-retry",
},
)
self.assertEqual(
1, self.records.registry.unknown_archive_provider.dispatch_count
)
self.assertEqual(
"transfer_pending",
self.records.get_record(self.session, self.principal, record_id="record-1")[
"record"
]["state"],
)
recovery = self.records.recovery_status(
self.session, self.principal, record_id="record-1"
)
self.assertTrue(recovery["healthy"])
self.assertTrue(recovery["package_checks"][0]["manifest_verified"])
def test_disposition_waits_for_optional_approvals_and_can_be_withdrawn(
self,
) -> None:
self.records.registry.approvals = None
self._create_record()
self.records.close_record(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_revision": 1,
"purpose": "close record",
"reason": "Work completed.",
"recorded_at": NOW + timedelta(minutes=2),
"idempotency_key": "close-without-approvals",
},
)
self.records.appraise_record(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_revision": 2,
"outcome": "retain",
"purpose": "appraise record",
"reason": "Retain permanently.",
"override_retention_not_due": True,
"recorded_at": NOW + timedelta(minutes=3),
"idempotency_key": "appraise-without-approvals",
},
)
proposal = self.records.propose_disposition(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_record_revision": 3,
"action": "retain",
"purpose": "dispose record",
"reason": "Retain permanently.",
"recorded_at": NOW + timedelta(minutes=4),
"idempotency_key": "proposal-without-approvals",
},
)
self.assertEqual("review_unavailable", proposal["status"])
with self.assertRaisesRegex(ValueError, "not awaiting an available approval"):
self.records.finalize_disposition(
self.session,
self.principal,
record_id="record-1",
disposition_id=str(proposal["disposition_id"]),
payload={
"expected_disposition_revision": 1,
"purpose": "finalize disposition",
"recorded_at": NOW + timedelta(minutes=5),
"idempotency_key": "finalize-without-approvals",
},
)
withdrawn = self.records.withdraw_disposition(
self.session,
self.principal,
record_id="record-1",
disposition_id=str(proposal["disposition_id"]),
payload={
"expected_disposition_revision": 1,
"purpose": "correct disposition",
"reason": "The appraisal evidence needs correction.",
"recorded_at": NOW + timedelta(minutes=6),
"idempotency_key": "withdraw-without-approvals",
},
)
self.assertEqual("withdrawn", withdrawn["status"])
replacement = self.records.propose_disposition(
self.session,
self.principal,
record_id="record-1",
payload={
"expected_record_revision": 3,
"action": "retain",
"purpose": "dispose record",
"reason": "Corrected permanent-retention proposal.",
"recorded_at": NOW + timedelta(minutes=7),
"idempotency_key": "replacement-without-approvals",
},
)
self.assertEqual("review_unavailable", replacement["status"])
if __name__ == "__main__":
unittest.main()