framework-m 0.7.1__tar.gz → 0.7.3__tar.gz

{framework_m-0.7.1 → framework_m-0.7.3}/CHANGELOG.md

@@ -1,4 +1,4 @@
-**framework-m** v0.7.1: internal dependency bump due to **framework-m-studio** update## framework-m v0.7.0
+**framework-m** v0.7.3: internal dependency bump due to **framework-m-core** update**framework-m** v0.7.2: internal dependency bump due to **framework-m-core** update**framework-m** v0.7.1: internal dependency bump due to **framework-m-studio** update## framework-m v0.7.0
 
 ### Features
 

{framework_m-0.7.1 → framework_m-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framework-m
-Version: 0.7.1
+Version: 0.7.3
 Summary: A modular, metadata-driven business application framework
 Project-URL: Homepage, https://gitlab.com/castlecraft/framework-m
 Project-URL: Documentation, https://gitlab.com/castlecraft/framework-m#readme
@@ -18,8 +18,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: framework-m-core>=0.11.4
-Requires-Dist: framework-m-standard>=0.8.0
+Requires-Dist: framework-m-core>=0.13.0
+Requires-Dist: framework-m-standard>=0.10.0
 Description-Content-Type: text/markdown
 
 # Framework M

{framework_m-0.7.1 → framework_m-0.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "framework-m"
-version = "0.7.1"
+version = "0.7.3"
 description = "A modular, metadata-driven business application framework"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -21,8 +21,8 @@ classifiers = [
 ]
 
 dependencies = [
-    "framework-m-core>=0.11.4",
-    "framework-m-standard>=0.8.0",
+    "framework-m-core>=0.13.0",
+    "framework-m-standard>=0.10.0",
 ]
 
 [tool.uv.sources]
@@ -126,7 +126,7 @@ select = [
     "PTH",    # flake8-use-pathlib
     "RUF",    # ruff-specific rules
 ]
-ignore = ["E501", "B008"]  # Line too long, Typer uses function calls in defaults
+ignore = ["E501"]  # Line length is handled by formatter, but we allow it for long docstrings/comments
 
 [tool.ruff.format]
 quote-style = "double"

framework_m-0.7.3/src/framework_m/core/services/__init__.py

@@ -0,0 +1,5 @@
+"""Service-layer components for Framework M."""
+
+from framework_m.core.services.correction import CorrectionService
+
+__all__ = ["CorrectionService"]

framework_m-0.7.3/src/framework_m/core/services/correction.py

@@ -0,0 +1,179 @@
+"""Correction service implementing amend, restore, and in-place edit flows."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from framework_m_core.domain.base_controller import BaseController
+from framework_m_core.domain.base_doctype import BaseDocType
+from framework_m_core.domain.mixins import DocStatus
+from framework_m_core.interfaces.audit import AuditLogProtocol
+from framework_m_core.interfaces.auth_context import UserContext
+from framework_m_core.interfaces.repository import RepositoryProtocol
+
+
+class CorrectionService:
+    """Service for RFC-0008 correction workflows on submitted documents."""
+
+    def __init__(
+        self,
+        repository: RepositoryProtocol[BaseDocType],
+        audit: AuditLogProtocol,
+    ) -> None:
+        self._repository = repository
+        self._audit = audit
+
+    async def amend(
+        self,
+        doc: BaseDocType,
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Cancel submitted doc and create a new draft copy with incremented name."""
+        self._ensure_submitted(doc)
+
+        cancelled = doc.model_copy(deep=True)
+        if hasattr(cancelled, "docstatus"):
+            cancelled.docstatus = DocStatus.CANCELLED
+        await self._repository.save(cancelled)
+
+        amended = self._clone_with_updates(
+            source=doc,
+            new_name=self._next_amended_name(doc.name),
+            docstatus=DocStatus.DRAFT,
+            drop_id=True,
+        )
+        saved_amended = await self._repository.save(amended)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="amend",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_amended
+
+    async def restore(
+        self,
+        doc: BaseDocType,
+        snapshot_data: dict[str, Any],
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Cancel submitted doc and recreate a submitted document from snapshot data."""
+        self._ensure_submitted(doc)
+        if not snapshot_data:
+            raise ValueError("snapshot_data cannot be empty")
+
+        cancelled = doc.model_copy(deep=True)
+        if hasattr(cancelled, "docstatus"):
+            cancelled.docstatus = DocStatus.CANCELLED
+        await self._repository.save(cancelled)
+
+        restored_data = dict(snapshot_data)
+        restored_data.pop("id", None)
+        restored_data["name"] = self._next_amended_name(doc.name)
+        restored_data["docstatus"] = DocStatus.SUBMITTED
+
+        restored_doc = type(doc).model_validate(restored_data)
+        saved_restored = await self._repository.save(restored_doc)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="restore",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_restored
+
+    async def in_place_edit(
+        self,
+        doc: BaseDocType,
+        reason: str,
+        user: UserContext,
+    ) -> BaseDocType:
+        """Keep same document identity, snapshot history, then reset to draft."""
+        if not getattr(type(doc), "_versioning_enabled", False):
+            raise ValueError("in_place_edit requires VersionedMixin")
+
+        self._ensure_submitted(doc)
+
+        history_snapshot = doc.model_copy(deep=True)
+        await self._repository.save(history_snapshot)
+
+        editable = doc.model_copy(deep=True)
+        if hasattr(editable, "docstatus"):
+            editable.docstatus = DocStatus.DRAFT
+
+        controller: BaseController[BaseDocType] = BaseController(editable)
+        await controller._validate_submitted_changes(editable, doc)
+
+        saved_editable = await self._repository.save(editable)
+
+        await self._audit.log(
+            user_id=user.id,
+            action="in_place_edit",
+            doctype=type(doc).__name__,
+            document_id=self._document_ref(doc),
+            changes=None,
+            metadata={"reason": reason},
+        )
+
+        return saved_editable
+
+    def _next_amended_name(self, name: str | None) -> str:
+        """Return incremented amended name: INV-001 -> INV-001-1, INV-001-1 -> INV-001-2."""
+        base_name = name or "DOC"
+        # Only treat trailing numeric segment as amendment counter when
+        # a prior amendment segment already exists (at least 2 hyphens).
+        if base_name.count("-") < 2:
+            return f"{base_name}-1"
+
+        match = re.match(r"^(.*)-(\d+)$", base_name)
+        if match is None:
+            return f"{base_name}-1"
+
+        prefix = match.group(1)
+        number = int(match.group(2))
+        return f"{prefix}-{number + 1}"
+
+    def _ensure_submitted(self, doc: BaseDocType) -> None:
+        """Validate that the document is in submitted state."""
+        if not hasattr(doc, "docstatus"):
+            raise ValueError("Only submitted documents can be corrected")
+
+        if doc.docstatus != DocStatus.SUBMITTED:
+            raise ValueError("Only submitted documents can be corrected")
+
+    def _clone_with_updates(
+        self,
+        source: BaseDocType,
+        new_name: str,
+        docstatus: DocStatus,
+        *,
+        drop_id: bool,
+    ) -> BaseDocType:
+        """Clone a document and apply correction-flow identity/status updates."""
+        data = source.model_dump(mode="python")
+        if drop_id:
+            data.pop("id", None)
+        data["name"] = new_name
+        if "docstatus" in type(source).model_fields:
+            data["docstatus"] = docstatus
+        return type(source).model_validate(data)
+
+    def _document_ref(self, doc: BaseDocType) -> str:
+        """Return preferred audit document reference (name first, then id)."""
+        if doc.name:
+            return str(doc.name)
+        return str(doc.id)
+
+
+__all__ = ["CorrectionService"]

framework_m-0.7.3/tests/core/test_correction_service.py

@@ -0,0 +1,328 @@
+"""Tests for CorrectionService (RFC-0008 Step 8.1)."""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+from framework_m_core.domain.base_doctype import BaseDocType, Field
+from framework_m_core.domain.mixins import DocStatus, SubmittableMixin, VersionedMixin
+from framework_m_core.interfaces.audit import AuditLogProtocol
+from framework_m_core.interfaces.auth_context import UserContext
+from framework_m_core.interfaces.repository import RepositoryProtocol
+
+from framework_m.core.services.correction import CorrectionService
+
+
+class Invoice(BaseDocType, SubmittableMixin):
+    """Test invoice doctype for correction-flow tests."""
+
+    customer: str = Field(description="Customer")
+    amount: float = Field(default=0.0, description="Amount")
+
+
+class VersionedInvoice(Invoice, VersionedMixin):
+    """Versioned invoice doctype for in-place correction tests."""
+
+
+@pytest.fixture
+def mock_repository() -> AsyncMock:
+    """Repository mock implementing save semantics."""
+
+    def _save(entity: BaseDocType, version: int | None = None) -> BaseDocType:
+        _ = version
+        return entity
+
+    repo = AsyncMock(spec=RepositoryProtocol[BaseDocType])
+    repo.save = AsyncMock(side_effect=_save)
+    return repo
+
+
+@pytest.fixture
+def mock_audit_adapter() -> AsyncMock:
+    """Audit adapter mock for correction-flow logging."""
+    audit = AsyncMock(spec=AuditLogProtocol)
+    audit.log = AsyncMock(return_value="audit-entry-001")
+    return audit
+
+
+@pytest.fixture
+def service(
+    mock_repository: AsyncMock,
+    mock_audit_adapter: AsyncMock,
+) -> CorrectionService:
+    """CorrectionService under test."""
+    return CorrectionService(
+        repository=mock_repository,
+        audit=mock_audit_adapter,
+    )
+
+
+@pytest.fixture
+def user_context() -> UserContext:
+    """User context fixture for audit metadata."""
+    return UserContext(
+        id="user-001",
+        email="user-001@example.com",
+        name="Test User",
+        roles=["Employee"],
+    )
+
+
+@pytest.fixture
+def submitted_invoice() -> Invoice:
+    """Submitted invoice fixture for amend/restore tests."""
+    return Invoice(
+        name="INV-001",
+        customer="Acme",
+        amount=100.0,
+        docstatus=DocStatus.SUBMITTED,
+    )
+
+
+@pytest.fixture
+def versioned_submitted_invoice() -> VersionedInvoice:
+    """Submitted versioned invoice fixture for in-place edit tests."""
+    return VersionedInvoice(
+        name="INV-001",
+        customer="Acme",
+        amount=100.0,
+        docstatus=DocStatus.SUBMITTED,
+    )
+
+
+class TestCorrectionServiceAmend:
+    """Amend flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_amend_cancels_original_and_creates_new_draft(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        result = await service.amend(
+            doc=submitted_invoice,
+            reason="Typo fix",
+            user=user_context,
+        )
+
+        assert result.docstatus == DocStatus.DRAFT
+        assert result.name == "INV-001-1"
+        assert result.id != submitted_invoice.id
+
+        assert mock_repository.save.await_count == 2
+
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        amended_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert cancelled_doc.docstatus == DocStatus.CANCELLED
+        assert cancelled_doc.name == "INV-001"
+
+        assert amended_doc.docstatus == DocStatus.DRAFT
+        assert amended_doc.name == "INV-001-1"
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="amend",
+            doctype="Invoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Typo fix"},
+        )
+
+    def test_amend_name_increments_correctly(self, service: CorrectionService) -> None:
+        assert service._next_amended_name("INV-001") == "INV-001-1"
+        assert service._next_amended_name("INV-001-1") == "INV-001-2"
+
+    @pytest.mark.asyncio
+    async def test_amend_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.amend(
+                doc=draft,
+                reason="Need correction",
+                user=user_context,
+            )
+
+        mock_repository.save.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_amend_audit_failure_propagates(
+        self,
+        service: CorrectionService,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        mock_audit_adapter.log.side_effect = RuntimeError("audit write failed")
+
+        with pytest.raises(RuntimeError, match="audit write failed"):
+            await service.amend(
+                doc=submitted_invoice,
+                reason="Typo fix",
+                user=user_context,
+            )
+
+
+class TestCorrectionServiceRestore:
+    """Restore flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_restore_cancels_original_and_creates_snapshot_doc(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        snapshot_data: dict[str, Any] = {
+            "customer": "Acme Restored",
+            "amount": 120.0,
+        }
+
+        result = await service.restore(
+            doc=submitted_invoice,
+            snapshot_data=snapshot_data,
+            reason="Rollback to prior snapshot",
+            user=user_context,
+        )
+
+        assert result.name == "INV-001-1"
+        assert result.docstatus == DocStatus.SUBMITTED
+
+        assert mock_repository.save.await_count == 2
+
+        cancelled_doc = mock_repository.save.await_args_list[0].args[0]
+        restored_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert cancelled_doc.docstatus == DocStatus.CANCELLED
+        assert restored_doc.docstatus == DocStatus.SUBMITTED
+        assert restored_doc.customer == "Acme Restored"
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="restore",
+            doctype="Invoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Rollback to prior snapshot"},
+        )
+
+    @pytest.mark.asyncio
+    async def test_restore_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.restore(
+                doc=draft,
+                snapshot_data={"customer": "Acme"},
+                reason="Invalid state",
+                user=user_context,
+            )
+
+    @pytest.mark.asyncio
+    async def test_restore_raises_if_snapshot_empty(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        with pytest.raises(ValueError, match="snapshot_data cannot be empty"):
+            await service.restore(
+                doc=submitted_invoice,
+                snapshot_data={},
+                reason="Missing snapshot",
+                user=user_context,
+            )
+
+
+class TestCorrectionServiceInPlaceEdit:
+    """In-place edit flow tests."""
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_copies_to_history_and_resets_to_draft(
+        self,
+        service: CorrectionService,
+        mock_repository: AsyncMock,
+        mock_audit_adapter: AsyncMock,
+        versioned_submitted_invoice: VersionedInvoice,
+        user_context: UserContext,
+    ) -> None:
+        result = await service.in_place_edit(
+            doc=versioned_submitted_invoice,
+            reason="Operational correction",
+            user=user_context,
+        )
+
+        assert result.id == versioned_submitted_invoice.id
+        assert result.name == versioned_submitted_invoice.name
+        assert result.docstatus == DocStatus.DRAFT
+
+        assert mock_repository.save.await_count == 2
+
+        history_snapshot_doc = mock_repository.save.await_args_list[0].args[0]
+        editable_doc = mock_repository.save.await_args_list[1].args[0]
+
+        assert history_snapshot_doc.docstatus == DocStatus.SUBMITTED
+        assert editable_doc.docstatus == DocStatus.DRAFT
+        assert editable_doc.id == versioned_submitted_invoice.id
+        assert editable_doc.name == versioned_submitted_invoice.name
+
+        mock_audit_adapter.log.assert_awaited_once_with(
+            user_id=user_context.id,
+            action="in_place_edit",
+            doctype="VersionedInvoice",
+            document_id="INV-001",
+            changes=None,
+            metadata={"reason": "Operational correction"},
+        )
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_raises_if_not_versioned(
+        self,
+        service: CorrectionService,
+        submitted_invoice: Invoice,
+        user_context: UserContext,
+    ) -> None:
+        with pytest.raises(ValueError, match="in_place_edit requires VersionedMixin"):
+            await service.in_place_edit(
+                doc=submitted_invoice,
+                reason="Invalid flow",
+                user=user_context,
+            )
+
+    @pytest.mark.asyncio
+    async def test_in_place_edit_raises_if_not_submitted(
+        self,
+        service: CorrectionService,
+        versioned_submitted_invoice: VersionedInvoice,
+        user_context: UserContext,
+    ) -> None:
+        draft = versioned_submitted_invoice.model_copy(deep=True)
+        draft.docstatus = DocStatus.DRAFT
+
+        with pytest.raises(ValueError):
+            await service.in_place_edit(
+                doc=draft,
+                reason="Invalid state",
+                user=user_context,
+            )

framework_m-0.7.3/tests/integration/test_rfc_0008_audit.py

@@ -0,0 +1,170 @@
+"""RFC-0008 audit integration tests (Phase 12.1)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from datetime import datetime
+from typing import Any
+
+import pytest
+from framework_m_core.doctypes.activity_log import ActivityLog
+from framework_m_core.domain.base_controller import BaseController
+from framework_m_core.domain.base_doctype import BaseDocType, Field
+from framework_m_core.domain.mixins import AuditMixin, DocStatus, SubmittableMixin
+from framework_m_core.exceptions import ImmutableDocumentError
+from framework_m_core.interfaces.audit import AuditEntry, AuditLogProtocol
+from framework_m_standard.adapters.audit.database_audit import DatabaseAuditAdapter
+from framework_m_standard.adapters.db.generic_repository import GenericRepository
+from framework_m_standard.adapters.db.schema_mapper import SchemaMapper
+from sqlalchemy import MetaData
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class AuditedInvoice(BaseDocType, AuditMixin, SubmittableMixin):
+    """Audited + submittable DocType for integration tests."""
+
+    title: str = Field(description="Invoice title")
+    total: float = Field(default=0.0, description="Invoice total")
+
+
+class AuditedInvoiceController(BaseController[AuditedInvoice]):
+    """Controller that supports test-time audit adapter injection."""
+
+    audit_adapter: AuditLogProtocol | None = None
+
+    def __init__(self, doc: AuditedInvoice) -> None:
+        super().__init__(doc)
+        self._audit_adapter = type(self).audit_adapter
+
+
+class _SessionBoundActivityRepository:
+    """Expose RepositoryProtocol-style methods backed by a bound DB session."""
+
+    def __init__(
+        self,
+        repo: GenericRepository[ActivityLog],
+        session: AsyncSession,
+    ) -> None:
+        self._repo = repo
+        self._session = session
+
+    async def get(
+        self,
+        id: Any,
+        as_of: datetime | None = None,
+    ) -> ActivityLog | None:
+        return await self._repo.get(self._session, id, as_of=as_of)
+
+    async def save(
+        self,
+        entity: ActivityLog,
+        version: int | None = None,
+    ) -> ActivityLog:
+        return await self._repo.save(self._session, entity, version=version)
+
+    async def list(
+        self,
+        filters: list[Any] | None = None,
+        order_by: list[Any] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        as_of: datetime | None = None,
+    ) -> Any:
+        return await self._repo.list_entities(
+            self._session,
+            filters=filters,
+            order_by=order_by,
+            limit=limit,
+            offset=offset,
+            as_of=as_of,
+        )
+
+
+@pytest.fixture
+async def audit_stack(
+    db_session: AsyncSession,
+    clean_tables: MetaData,
+) -> AsyncGenerator[
+    tuple[GenericRepository[AuditedInvoice], DatabaseAuditAdapter], None
+]:
+    """Create repositories and a database-backed audit adapter."""
+    mapper = SchemaMapper()
+    audited_table = mapper.create_table(AuditedInvoice, clean_tables)
+    activity_table = mapper.create_table(ActivityLog, clean_tables)
+
+    conn = await db_session.connection()
+    await conn.run_sync(clean_tables.create_all)
+
+    invoice_repo = GenericRepository(
+        model=AuditedInvoice,
+        table=audited_table,
+        controller_class=AuditedInvoiceController,
+    )
+    activity_repo = GenericRepository(model=ActivityLog, table=activity_table)
+    audit_repo_adapter = _SessionBoundActivityRepository(activity_repo, db_session)
+    audit_adapter = DatabaseAuditAdapter(repository=audit_repo_adapter)
+
+    AuditedInvoiceController.audit_adapter = audit_adapter
+    yield invoice_repo, audit_adapter
+    AuditedInvoiceController.audit_adapter = None
+
+
+async def _entries_for_document(
+    audit: DatabaseAuditAdapter,
+    document_id: str,
+) -> list[AuditEntry]:
+    """Query all audit entries for an AuditedInvoice by document reference."""
+    return await audit.query(
+        filters={"doctype": "AuditedInvoice", "document_id": document_id},
+        limit=100,
+        offset=0,
+    )
+
+
+@pytest.mark.asyncio
+async def test_rfc_0008_audit_flow_end_to_end(
+    audit_stack: tuple[GenericRepository[AuditedInvoice], DatabaseAuditAdapter],
+    db_session: AsyncSession,
+) -> None:
+    """Insert/update/submit should audit, while submitted edits are blocked."""
+    repo, audit = audit_stack
+
+    invoice = AuditedInvoice(name="INV-001", title="Initial", total=10.0)
+
+    # Create -> create audit entry
+    await repo.save(db_session, invoice)
+    entries_after_create = await _entries_for_document(audit, "INV-001")
+    assert any(entry.action == "create" for entry in entries_after_create)
+
+    # Update -> update audit entry with diff
+    invoice.total = 25.0
+    await repo.save(db_session, invoice)
+    entries_after_update = await _entries_for_document(audit, "INV-001")
+    update_entries = [
+        entry for entry in entries_after_update if entry.action == "update"
+    ]
+    assert len(update_entries) >= 1
+    assert update_entries[0].changes == {"total": {"old": 10.0, "new": 25.0}}
+
+    # Submit -> submit audit entry
+    invoice.docstatus = DocStatus.SUBMITTED
+    await repo.save(db_session, invoice)
+    entries_after_submit = await _entries_for_document(audit, "INV-001")
+    assert any(entry.action == "submit" for entry in entries_after_submit)
+
+    # Direct edit on submitted doc -> immutable error and no extra update entry
+    update_count_before_illegal = len(
+        [entry for entry in entries_after_submit if entry.action == "update"]
+    )
+
+    illegal_edit = invoice.model_copy(deep=True)
+    illegal_edit.total = 99.0
+
+    with pytest.raises(ImmutableDocumentError):
+        await repo.save(db_session, illegal_edit)
+
+    entries_after_illegal = await _entries_for_document(audit, "INV-001")
+    update_count_after_illegal = len(
+        [entry for entry in entries_after_illegal if entry.action == "update"]
+    )
+    assert update_count_after_illegal == update_count_before_illegal

framework_m-0.7.3/tests/integration/test_rfc_0008_correction.py

@@ -0,0 +1,228 @@
+"""RFC-0008 correction integration tests (Phase 12.3)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import pytest
+from framework_m_core.doctypes.activity_log import ActivityLog
+from framework_m_core.domain.base_doctype import BaseDocType, Field
+from framework_m_core.domain.mixins import DocStatus, SubmittableMixin, VersionedMixin
+from framework_m_core.interfaces.auth_context import UserContext
+from framework_m_standard.adapters.audit.database_audit import DatabaseAuditAdapter
+from framework_m_standard.adapters.db.generic_repository import GenericRepository
+from framework_m_standard.adapters.db.schema_mapper import SchemaMapper
+from sqlalchemy import MetaData, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from framework_m.core.services.correction import CorrectionService
+
+
+class CorrectableInvoice(BaseDocType, VersionedMixin, SubmittableMixin):
+    """Submittable + versioned DocType for correction-flow integration."""
+
+    customer: str = Field(description="Customer")
+    amount: float = Field(default=0.0, description="Amount")
+
+
+class _SessionBoundRepositoryAdapter:
+    """Expose RepositoryProtocol-style methods backed by a bound DB session."""
+
+    def __init__(
+        self,
+        repo: GenericRepository[Any],
+        session: AsyncSession,
+    ) -> None:
+        self._repo = repo
+        self._session = session
+
+    async def get(
+        self,
+        id: Any,
+        as_of: datetime | None = None,
+    ) -> Any | None:
+        return await self._repo.get(self._session, id, as_of=as_of)
+
+    async def save(
+        self,
+        entity: Any,
+        version: int | None = None,
+    ) -> Any:
+        return await self._repo.save(self._session, entity, version=version)
+
+    async def list(
+        self,
+        filters: list[Any] | None = None,
+        order_by: list[Any] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        as_of: datetime | None = None,
+    ) -> Any:
+        return await self._repo.list_entities(
+            self._session,
+            filters=filters,
+            order_by=order_by,
+            limit=limit,
+            offset=offset,
+            as_of=as_of,
+        )
+
+
+@pytest.fixture
+def test_user() -> UserContext:
+    """User context used by correction service audit logging."""
+    return UserContext(
+        id="user-001",
+        email="user-001@example.com",
+        roles=["Employee"],
+    )
+
+
+@pytest.fixture
+async def correction_stack(
+    db_session: AsyncSession,
+    clean_tables: MetaData,
+) -> tuple[
+    GenericRepository[CorrectableInvoice],
+    object,
+    DatabaseAuditAdapter,
+    CorrectionService,
+]:
+    """Create repository/audit/correction service wired to real SQLite tables."""
+    mapper = SchemaMapper()
+    tables = mapper.create_versioned_tables(
+        CorrectableInvoice,
+        clean_tables,
+        {"compliance": {"versioning_enabled": True}},
+    )
+    invoice_table, history_table = tables[0], tables[1]
+    activity_table = mapper.create_table(ActivityLog, clean_tables)
+
+    conn = await db_session.connection()
+    await conn.run_sync(clean_tables.create_all)
+
+    invoice_repo = GenericRepository(CorrectableInvoice, invoice_table)
+    activity_repo = GenericRepository(ActivityLog, activity_table)
+
+    invoice_repo_adapter = _SessionBoundRepositoryAdapter(invoice_repo, db_session)
+    activity_repo_adapter = _SessionBoundRepositoryAdapter(activity_repo, db_session)
+
+    audit_adapter = DatabaseAuditAdapter(repository=activity_repo_adapter)
+    correction_service = CorrectionService(
+        repository=invoice_repo_adapter,
+        audit=audit_adapter,
+    )
+
+    return invoice_repo, history_table, audit_adapter, correction_service
+
+
+async def _create_submitted_invoice(
+    repo: GenericRepository[CorrectableInvoice],
+    session: AsyncSession,
+    name: str,
+) -> CorrectableInvoice:
+    """Persist a submitted invoice record for correction tests."""
+    invoice = CorrectableInvoice(
+        name=name,
+        customer="Acme Corp",
+        amount=100.0,
+    )
+    await repo.save(session, invoice)
+
+    invoice.docstatus = DocStatus.SUBMITTED
+    await repo.save(session, invoice)
+
+    return invoice
+
+
+@pytest.mark.asyncio
+async def test_rfc_0008_correction_amend_flow(
+    correction_stack: tuple[
+        GenericRepository[CorrectableInvoice],
+        object,
+        DatabaseAuditAdapter,
+        CorrectionService,
+    ],
+    db_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+    test_user: UserContext,
+) -> None:
+    """amend() should cancel the original and create a new draft with new name."""
+    monkeypatch.setenv("FRAMEWORK_M_STRONGSYNC_VERSIONING", "true")
+
+    repo, _history_table, audit, correction_service = correction_stack
+    original = await _create_submitted_invoice(repo, db_session, "INV-100")
+
+    amended = await correction_service.amend(
+        doc=original,
+        reason="Typo fix",
+        user=test_user,
+    )
+
+    persisted_original = await repo.get(db_session, original.id)
+    assert persisted_original is not None
+    assert persisted_original.docstatus == DocStatus.CANCELLED
+
+    assert amended.id != original.id
+    assert amended.name == "INV-100-1"
+    assert amended.docstatus == DocStatus.DRAFT
+
+    amended_lookup = await repo.get_by_name(db_session, "INV-100-1")
+    assert amended_lookup is not None
+    assert amended_lookup.docstatus == DocStatus.DRAFT
+
+    entries = await audit.query(
+        filters={"doctype": "CorrectableInvoice", "document_id": "INV-100"},
+        limit=100,
+        offset=0,
+    )
+    assert any(entry.action == "amend" for entry in entries)
+
+
+@pytest.mark.asyncio
+async def test_rfc_0008_correction_in_place_edit_flow(
+    correction_stack: tuple[
+        GenericRepository[CorrectableInvoice],
+        object,
+        DatabaseAuditAdapter,
+        CorrectionService,
+    ],
+    db_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+    test_user: UserContext,
+) -> None:
+    """in_place_edit() should keep identity, reset docstatus, and record audit/history."""
+    monkeypatch.setenv("FRAMEWORK_M_STRONGSYNC_VERSIONING", "true")
+
+    repo, history_table, audit, correction_service = correction_stack
+    original = await _create_submitted_invoice(repo, db_session, "INV-200")
+
+    edited = await correction_service.in_place_edit(
+        doc=original,
+        reason="Operational correction",
+        user=test_user,
+    )
+
+    assert edited.id == original.id
+    assert edited.name == original.name
+    assert edited.docstatus == DocStatus.DRAFT
+
+    persisted = await repo.get(db_session, original.id)
+    assert persisted is not None
+    assert persisted.docstatus == DocStatus.DRAFT
+
+    history_count = await db_session.scalar(
+        select(func.count())
+        .select_from(history_table)
+        .where(history_table.c.id == original.id)
+    )
+    assert history_count is not None
+    assert history_count >= 3
+
+    entries = await audit.query(
+        filters={"doctype": "CorrectableInvoice", "document_id": "INV-200"},
+        limit=100,
+        offset=0,
+    )
+    assert any(entry.action == "in_place_edit" for entry in entries)

framework_m-0.7.3/tests/integration/test_rfc_0008_versioning.py

@@ -0,0 +1,101 @@
+"""RFC-0008 versioning integration tests (Phase 12.2)."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+
+import pytest
+from framework_m_core.domain.base_doctype import BaseDocType, Field
+from framework_m_core.domain.mixins import VersionedMixin
+from framework_m_core.exceptions import TemporalQueryNotSupportedError
+from framework_m_standard.adapters.db.generic_repository import GenericRepository
+from framework_m_standard.adapters.db.schema_mapper import SchemaMapper
+from sqlalchemy import MetaData, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class VersionedInvoice(BaseDocType, VersionedMixin):
+    """Versioned DocType for temporal integration checks."""
+
+    title: str = Field(description="Title")
+    total: float = Field(default=0.0, description="Amount")
+
+
+@pytest.fixture
+async def versioned_repo(
+    db_session: AsyncSession,
+    clean_tables: MetaData,
+) -> tuple[GenericRepository[VersionedInvoice], object]:
+    """Create a versioned repository with provisioned history table."""
+    mapper = SchemaMapper()
+    tables = mapper.create_versioned_tables(
+        VersionedInvoice,
+        clean_tables,
+        {"compliance": {"versioning_enabled": True}},
+    )
+
+    main_table, history_table = tables[0], tables[1]
+    conn = await db_session.connection()
+    await conn.run_sync(clean_tables.create_all)
+
+    return GenericRepository(VersionedInvoice, main_table), history_table
+
+
+@pytest.mark.asyncio
+async def test_rfc_0008_versioning_history_and_temporal_query(
+    versioned_repo: tuple[GenericRepository[VersionedInvoice], object],
+    db_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Versioned saves should create history and support as_of lookup."""
+    monkeypatch.setenv("FRAMEWORK_M_STRONGSYNC_VERSIONING", "true")
+
+    repo, history_table = versioned_repo
+
+    invoice = VersionedInvoice(name="VINV-001", title="v1", total=10.0)
+    await repo.save(db_session, invoice)
+
+    between = datetime.now(UTC)
+    await asyncio.sleep(0.01)
+
+    invoice.total = 20.0
+    await repo.save(db_session, invoice)
+
+    history_count = await db_session.scalar(
+        select(func.count())
+        .select_from(history_table)
+        .where(history_table.c.id == invoice.id)
+    )
+    assert history_count == 2
+
+    version_rows = await db_session.execute(
+        select(history_table)
+        .where(history_table.c.id == invoice.id)
+        .order_by(history_table.c._version_no.asc())
+    )
+    version_numbers = [row._mapping["_version_no"] for row in version_rows.fetchall()]
+    assert version_numbers == [1, 2]
+
+    as_of_doc = await repo.get(db_session, invoice.id, as_of=between)
+    assert as_of_doc is not None
+    assert as_of_doc.total == pytest.approx(10.0)
+
+
+@pytest.mark.asyncio
+async def test_rfc_0008_versioning_disabled_rejects_temporal_query(
+    versioned_repo: tuple[GenericRepository[VersionedInvoice], object],
+    db_session: AsyncSession,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """as_of must fail fast when versioning is disabled."""
+    repo, _history_table = versioned_repo
+
+    invoice = VersionedInvoice(name="VINV-002", title="v1", total=33.0)
+
+    monkeypatch.setenv("FRAMEWORK_M_STRONGSYNC_VERSIONING", "true")
+    await repo.save(db_session, invoice)
+
+    monkeypatch.setenv("FRAMEWORK_M_STRONGSYNC_VERSIONING", "false")
+    with pytest.raises(TemporalQueryNotSupportedError):
+        await repo.get(db_session, invoice.id, as_of=datetime.now(UTC))