ms-markets 2.2.2.dev11__tar.gz → 2.2.3.dev12__tar.gz

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project follows versioned releases.
 
 ## [Unreleased]
 
+### Added
+
+- The portfolio, portfolio-group and asset-category bulk-delete preflights
+  report what the delete reaches through foreign keys. They return the
+  MetaTables `delete_rows` impact as `impact`, describe each cascade,
+  `SET NULL` or `SET DEFAULT` action in `warnings`, and add MetaTables'
+  blockers (for example a cascade into a table the caller cannot write), which
+  also stop the bulk delete with `409`. If MetaTables cannot compute the
+  impact, a warning says so and the delete is not blocked.
+  `BulkDeletePreflightResponse` and the `TableImpact` models are exported from
+  `msm.api.http`, and `delete_rows_impact` from `msm.services`.
+
 ## [2.2.2] - 2026-10-03
 
 ### Changed

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-markets
-Version: 2.2.2.dev11
+Version: 2.2.3.dev12
 Summary: Financial markets ORM, engines, and application management extensions for Main Sequence.
 Project-URL: Changelog, https://github.com/mainsequence-projects/MainSequenceMarkets/blob/main/CHANGELOG.md
 Project-URL: Source, https://github.com/mainsequence-projects/MainSequenceMarkets

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/docs/fast_api/v1/command_center_bulk_actions.md

@@ -46,6 +46,29 @@ selected UID and reports `allowed`, `matched_count`, `blockers`, and `warnings`
 without mutating data. Portfolio preflight also evaluates protected
 VirtualFund and target-position references.
 
+Each bulk-delete preflight also reports what deleting rows from the resource's
+table reaches through foreign keys. It asks MetaTables
+(`MetaTable.get_impact(action="delete_rows")`) and adds:
+
+- `impact`: the MetaTables impact graph. Nodes are the tables the delete
+  reaches, with their effects and the caller's effective write. Edges are
+  classified as `cascade_delete`, `cascade_update`, `set_null`, `set_default`,
+  `restrict` or `reads`. MetaTables' blockers are included.
+- `warnings`: one sentence for each foreign-key action the delete triggers, for
+  example "PortfolioGroupMembership rows that reference deleted PortfolioGroup
+  rows are deleted too (ON DELETE CASCADE)." Command Center shows warnings
+  without custom rendering.
+- `blockers`: MetaTables' reasons the caller may not run the delete, such as a
+  cascade into a table the caller cannot write, prefixed with that table. The
+  preflight then answers `allowed: false` and execution answers `409` before
+  the database refuses the delete.
+
+Deleting portfolios or portfolio groups cascades to their
+`PortfolioGroupMembership` rows; deleting asset categories cascades to their
+`AssetCategoryMembership` rows. If MetaTables cannot compute the impact,
+`impact` is `null` and a warning says so. The preflight is not blocked, because
+the database still applies and enforces every foreign-key action.
+
 Execution repeats preflight immediately before invoking domain deletion. A
 blocked selection returns HTTP `409` and does not call the delete service. The
 underlying delete operation still performs its own conflict checks, protecting

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-markets"
-version = "2.2.2.dev11"
+version = "2.2.3.dev12"
 description = "Financial markets ORM, engines, and application management extensions for Main Sequence."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/src/msm/api/http/__init__.py

@@ -13,6 +13,7 @@ from .bulk_actions import (
     BulkActionPreflightResponse,
     BulkActionResourceId,
     BulkActionSelection,
+    BulkDeletePreflightResponse,
     blocked_preflight_detail,
     build_bulk_delete_action,
     explicit_uuid_selection,
@@ -78,6 +79,12 @@ from .tabular import (
     build_tabular_field,
     build_tabular_frame,
 )
+from .table_impact import (
+    TableImpact,
+    TableImpactBlocker,
+    TableImpactEdge,
+    TableImpactNode,
+)
 
 __all__ = [
     "BULK_ACTION_EXECUTION_CONTRACT",
@@ -98,6 +105,7 @@ __all__ = [
     "BulkActionPreflightResponse",
     "BulkActionResourceId",
     "BulkActionSelection",
+    "BulkDeletePreflightResponse",
     "ErrorCode",
     "ErrorResponse",
     "InMemoryOperationStore",
@@ -123,6 +131,10 @@ __all__ = [
     "ResourceSearchControl",
     "ResourceSelectFilter",
     "ResourceTextFilter",
+    "TableImpact",
+    "TableImpactBlocker",
+    "TableImpactEdge",
+    "TableImpactNode",
     "TabularFrameFieldResponse",
     "TabularFrameMetaResponse",
     "TabularFrameResponse",

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/src/msm/api/http/bulk_actions.py

@@ -8,6 +8,7 @@ from uuid import UUID
 from pydantic import Field, StrictFloat, StrictInt, field_validator, model_validator
 
 from ._base import HttpContractModel
+from .table_impact import TableImpact
 
 BULK_ACTION_EXECUTION_CONTRACT = "command-center.bulk_action_execution@v1"
 BULK_ACTION_PREFLIGHT_CONTRACT = "command-center.bulk_action_preflight@v1"
@@ -134,6 +135,20 @@ class BulkActionPreflightResponse(HttpContractModel):
     warnings: list[str] | None = None
 
 
+class BulkDeletePreflightResponse(BulkActionPreflightResponse):
+    """Bulk-delete preflight that also reports what deleting the selection reaches."""
+
+    impact: TableImpact | None = Field(
+        default=None,
+        description=(
+            "MetaTables delete_rows impact for the table the selected rows are deleted "
+            "from: the tables its foreign-key actions reach, the effect on each and the "
+            "caller's effective write. Each cascade is also summarized in warnings. "
+            "Null when nothing matched or MetaTables could not compute it."
+        ),
+    )
+
+
 def build_bulk_delete_action(
     *,
     action_id: str,
@@ -203,6 +218,7 @@ __all__ = [
     "BulkActionPreflightResponse",
     "BulkActionResourceId",
     "BulkActionSelection",
+    "BulkDeletePreflightResponse",
     "blocked_preflight_detail",
     "build_bulk_delete_action",
     "explicit_uuid_selection",

ms_markets-2.2.3.dev12/src/msm/api/http/table_impact.py

@@ -0,0 +1,78 @@
+"""MetaTables table-impact contract: what a row action reaches through foreign keys."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from ._base import HttpContractModel
+
+
+class _TableImpactModel(HttpContractModel):
+    # MetaTables owns this shape; drop fields that newer MetaTables releases add.
+    model_config = HttpContractModel.model_config | {"extra": "ignore"}
+
+
+class TableImpactNode(_TableImpactModel):
+    """A table, unregistered relation, update or hidden table the action reaches."""
+
+    id: str
+    type: str = Field(description="meta_table, relation, update or hidden.")
+    uid: str | None = None
+    identifier: str | None = None
+    namespace: str | None = None
+    table_kind: str | None = None
+    physical_schema: str | None = None
+    physical_table_name: str | None = None
+    output_table_uid: str | None = None
+    effects: list[str] = Field(
+        default_factory=list,
+        description="What the action does here: drop, delete, update or input_changed.",
+    )
+    can_write: bool | None = Field(
+        default=None,
+        description="The caller's effective write after cascade narrowing; null for updates.",
+    )
+
+
+class TableImpactEdge(_TableImpactModel):
+    """Points from the dependent (referencing table or reading update) to what it depends on."""
+
+    source: str
+    target: str
+    kind: str = Field(description="foreign_key, alembic_version or reads.")
+    effect: str = Field(
+        description=(
+            "cascade_delete, cascade_update, set_null, set_default, restrict "
+            "(fails while referencing rows exist), drop or reads."
+        )
+    )
+    name: str | None = None
+    on_delete: str | None = None
+    on_update: str | None = None
+
+
+class TableImpactBlocker(_TableImpactModel):
+    """A reason MetaTables gives for refusing the action, and the node it concerns."""
+
+    code: str
+    message: str
+    node: str | None = None
+
+
+class TableImpact(_TableImpactModel):
+    """MetaTables' answer to what an action on a table reaches and whether it may run."""
+
+    root_uid: str
+    action: str = Field(description="delete_rows, update_keys or drop_table.")
+    allowed: bool
+    nodes: list[TableImpactNode]
+    edges: list[TableImpactEdge]
+    blockers: list[TableImpactBlocker]
+
+
+__all__ = [
+    "TableImpact",
+    "TableImpactBlocker",
+    "TableImpactEdge",
+    "TableImpactNode",
+]

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/src/msm/services/__init__.py

@@ -41,6 +41,7 @@ _EXPORTS = {
     "create_portfolio": ".portfolios",
     "create_portfolio_group": ".portfolios",
     "create_virtual_fund": ".accounts",
+    "DeleteRowsImpact": ".table_impact",
     "delete_account": ".accounts",
     "delete_account_group": ".reference_data",
     "delete_account_target_allocation": ".accounts",
@@ -50,6 +51,7 @@ _EXPORTS = {
     "delete_asset_category": ".asset_categories",
     "delete_asset_category_record": ".asset_master_lists",
     "delete_index_record": ".asset_master_lists",
+    "delete_rows_impact": ".table_impact",
     "delete_calendar": ".reference_data",
     "delete_calendar_date_record": ".calendars",
     "delete_calendar_event_record": ".calendars",

ms_markets-2.2.3.dev12/src/msm/services/table_impact.py

@@ -0,0 +1,123 @@
+"""MetaTables delete impact, rendered as bulk-delete preflight warnings and blockers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from mainsequence.logconf import logger as _mainsequence_logger
+
+from msm.api.http import TableImpact, TableImpactEdge, TableImpactNode
+
+logger = _mainsequence_logger.bind(sub_application="markets", component="table_impact")
+
+IMPACT_UNAVAILABLE_WARNING = (
+    "MetaTables could not report which tables this delete reaches through foreign keys. "
+    "The database still applies every foreign-key action when the rows are deleted."
+)
+
+# What a foreign-key action does to the referencing rows, by MetaTables edge effect.
+_REFERENCING_ROW_OUTCOMES = {
+    "cascade_delete": "are deleted too",
+    "cascade_update": "are updated too",
+    "set_null": "have that reference set to NULL",
+    "set_default": "have that reference reset to its default",
+}
+# The edge effect each ON DELETE action produces; any other effect follows ON UPDATE.
+_ON_DELETE_EFFECTS = {
+    "cascade": "cascade_delete",
+    "set null": "set_null",
+    "set default": "set_default",
+}
+
+
+@dataclass(frozen=True)
+class DeleteRowsImpact:
+    """MetaTables' delete impact with the preflight warnings and blockers it implies."""
+
+    impact: TableImpact | None
+    warnings: list[str] = field(default_factory=list)
+    blockers: list[str] = field(default_factory=list)
+
+
+def delete_rows_impact(model: type[Any]) -> DeleteRowsImpact:
+    """Ask MetaTables what deleting rows from ``model``'s table reaches.
+
+    Each foreign-key action the delete triggers (cascades, SET NULL, SET DEFAULT)
+    becomes a warning, and each reason MetaTables gives for refusing the delete
+    becomes a blocker. The impact is advisory: the database enforces the same rules
+    when the rows are deleted, so an unavailable impact only adds a warning.
+    """
+
+    meta_table = model.get_meta_table()
+    if meta_table is None:
+        logger.warning("MetaTables delete impact skipped: model is not bound", model=model.__name__)
+        return DeleteRowsImpact(impact=None, warnings=[IMPACT_UNAVAILABLE_WARNING])
+    try:
+        impact = TableImpact.model_validate(
+            meta_table.get_impact(action="delete_rows").model_dump(mode="json")
+        )
+    except Exception:
+        logger.exception("MetaTables delete impact failed", model=model.__name__)
+        return DeleteRowsImpact(impact=None, warnings=[IMPACT_UNAVAILABLE_WARNING])
+
+    nodes = {node.id: node for node in impact.nodes}
+    warnings = [
+        _foreign_key_warning(edge, nodes)
+        for edge in impact.edges
+        if edge.kind == "foreign_key" and edge.effect in _REFERENCING_ROW_OUTCOMES
+    ]
+    blockers = [
+        f"{_label(nodes.get(blocker.node), sentence_start=True)}: {blocker.message}"
+        if blocker.node
+        else blocker.message
+        for blocker in impact.blockers
+    ]
+    return DeleteRowsImpact(
+        impact=impact,
+        warnings=list(dict.fromkeys(warnings)),
+        blockers=blockers,
+    )
+
+
+def _foreign_key_warning(edge: TableImpactEdge, nodes: dict[str, TableImpactNode]) -> str:
+    # Edges point from the referencing table (source) to the table it references.
+    source = nodes.get(edge.source)
+    target = nodes.get(edge.target)
+    deleted = (
+        target is not None
+        and "delete" in target.effects
+        and _ON_DELETE_EFFECTS.get((edge.on_delete or "").lower()) == edge.effect
+    )
+    action = edge.on_delete if deleted else edge.on_update
+    clause = f" (ON {'DELETE' if deleted else 'UPDATE'} {action.upper()})" if action else ""
+    return (
+        f"{_rows(source, sentence_start=True)} that reference "
+        f"{'deleted' if deleted else 'changed'} {_rows(target)} "
+        f"{_REFERENCING_ROW_OUTCOMES[edge.effect]}{clause}."
+    )
+
+
+def _rows(node: TableImpactNode | None, *, sentence_start: bool = False) -> str:
+    if node is None or node.type == "hidden":
+        return f"{'R' if sentence_start else 'r'}ows in a table you cannot view"
+    return f"{_label(node)} rows"
+
+
+def _label(node: TableImpactNode | None, *, sentence_start: bool = False) -> str:
+    # Hidden tables are opaque: MetaTables reports that they are affected, not which.
+    if node is None or node.type == "hidden":
+        return f"{'A' if sentence_start else 'a'} table you cannot view"
+    if node.identifier:
+        return node.identifier
+    if node.physical_table_name:
+        schema = f"{node.physical_schema}." if node.physical_schema else ""
+        return f"{schema}{node.physical_table_name}"
+    return node.id
+
+
+__all__ = [
+    "IMPACT_UNAVAILABLE_WARNING",
+    "DeleteRowsImpact",
+    "delete_rows_impact",
+]

{ms_markets-2.2.2.dev11 → ms_markets-2.2.3.dev12}/tests/msm/fastapi/v1/test_bulk_actions.py

@@ -8,6 +8,8 @@ from fastapi.testclient import TestClient
 
 from apps.v1.main import app
 from apps.v1.services import asset_categories, portfolio_groups, portfolios
+from msm.api.http import TableImpact
+from msm.services.table_impact import DeleteRowsImpact
 
 
 @pytest.mark.parametrize(
@@ -102,6 +104,7 @@ def test_bulk_action_preflight_preserves_blockers(
         "matched_count": 1,
         "blockers": ["Protected reference exists."],
         "warnings": [],
+        "impact": None,
         "domain_context": {"resource_uid": str(resource_uid)},
     }
 
@@ -180,8 +183,7 @@ def test_bulk_action_operations_are_exposed_by_command_center_adapter() -> None:
     response = TestClient(app).get("/.well-known/command-center/connection-contract")
     assert response.status_code == 200
     operations = {
-        operation["operationId"]: operation
-        for operation in response.json()["availableOperations"]
+        operation["operationId"]: operation for operation in response.json()["availableOperations"]
     }
 
     for operation_id in (
@@ -215,6 +217,9 @@ def test_asset_category_preflight_is_owned_by_apps_v1(monkeypatch) -> None:
         "_get_asset_category_frontend_detail",
         lambda context, uid: {"uid": uid} if uid == existing_uid else None,
     )
+    monkeypatch.setattr(
+        asset_categories, "_asset_category_delete_impact", lambda: DeleteRowsImpact(impact=None)
+    )
 
     result = asset_categories.preflight_bulk_delete_asset_categories(
         uids=[existing_uid, missing_uid, existing_uid]
@@ -226,6 +231,7 @@ def test_asset_category_preflight_is_owned_by_apps_v1(monkeypatch) -> None:
         "matched_count": 1,
         "blockers": [f"Asset category {missing_uid} was not found."],
         "warnings": [],
+        "impact": None,
     }
 
 
@@ -242,17 +248,19 @@ def test_portfolio_group_preflight_is_owned_by_apps_v1(monkeypatch) -> None:
         "_get_portfolio_group_by_uid",
         lambda context, uid: {"results": [{"uid": uid}]},
     )
-
-    result = portfolio_groups.preflight_bulk_delete_portfolio_groups(
-        uids=[first_uid, second_uid]
+    monkeypatch.setattr(
+        portfolio_groups, "_portfolio_group_delete_impact", lambda: DeleteRowsImpact(impact=None)
     )
 
+    result = portfolio_groups.preflight_bulk_delete_portfolio_groups(uids=[first_uid, second_uid])
+
     assert result.model_dump() == {
         "allowed": True,
         "detail": "2 portfolio groups are ready for deletion.",
         "matched_count": 2,
         "blockers": [],
         "warnings": [],
+        "impact": None,
     }
 
 
@@ -268,6 +276,9 @@ def test_portfolio_preflight_is_owned_by_apps_v1(monkeypatch) -> None:
         "_portfolio_delete_preflight_item",
         lambda context, uid: (True, ["VirtualFundTable references this portfolio."]),
     )
+    monkeypatch.setattr(
+        portfolios, "_portfolio_delete_impact", lambda: DeleteRowsImpact(impact=None)
+    )
 
     result = portfolios.preflight_bulk_delete_portfolios(uids=[portfolio_uid])
 
@@ -275,8 +286,101 @@ def test_portfolio_preflight_is_owned_by_apps_v1(monkeypatch) -> None:
         "allowed": False,
         "detail": "The portfolio selection cannot be deleted as submitted.",
         "matched_count": 1,
-        "blockers": [
-            f"Portfolio {portfolio_uid}: VirtualFundTable references this portfolio."
-        ],
+        "blockers": [f"Portfolio {portfolio_uid}: VirtualFundTable references this portfolio."],
         "warnings": [],
+        "impact": None,
     }
+
+
+def _stub_portfolio_group_preflight(monkeypatch, impact: DeleteRowsImpact) -> None:
+    monkeypatch.setattr(
+        portfolio_groups,
+        "_get_runtime",
+        lambda: SimpleNamespace(context=object()),
+    )
+    monkeypatch.setattr(
+        portfolio_groups,
+        "_get_portfolio_group_by_uid",
+        lambda context, uid: {"results": [{"uid": uid}]},
+    )
+    monkeypatch.setattr(portfolio_groups, "_portfolio_group_delete_impact", lambda: impact)
+
+
+def test_portfolio_group_preflight_reports_cascades(monkeypatch) -> None:
+    group_uid = str(uuid.uuid4())
+    membership_uid = str(uuid.uuid4())
+    warning = (
+        "PortfolioGroupMembership rows that reference deleted PortfolioGroup rows "
+        "are deleted too (ON DELETE CASCADE)."
+    )
+    impact = TableImpact(
+        root_uid=group_uid,
+        action="delete_rows",
+        allowed=True,
+        nodes=[
+            {
+                "id": group_uid,
+                "type": "meta_table",
+                "identifier": "PortfolioGroup",
+                "effects": ["delete"],
+                "can_write": True,
+            },
+            {
+                "id": membership_uid,
+                "type": "meta_table",
+                "identifier": "PortfolioGroupMembership",
+                "effects": ["delete"],
+                "can_write": True,
+            },
+        ],
+        edges=[
+            {
+                "source": membership_uid,
+                "target": group_uid,
+                "kind": "foreign_key",
+                "effect": "cascade_delete",
+                "on_delete": "cascade",
+                "on_update": "no action",
+            },
+        ],
+        blockers=[],
+    )
+    _stub_portfolio_group_preflight(
+        monkeypatch, DeleteRowsImpact(impact=impact, warnings=[warning])
+    )
+
+    response = TestClient(app).post(
+        "/api/v1/portfolio-group/bulk-delete/preflight/",
+        json={"selection": {"mode": "explicit", "uids": [group_uid]}, "options": {}},
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "allowed": True,
+        "detail": "1 portfolio group is ready for deletion.",
+        "matched_count": 1,
+        "blockers": [],
+        "warnings": [warning],
+        "impact": impact.model_dump(mode="json"),
+    }
+
+
+def test_cascade_blockers_stop_bulk_delete(monkeypatch) -> None:
+    blocker = "PortfolioGroupMembership: A cascade reaches a table you cannot write."
+    _stub_portfolio_group_preflight(monkeypatch, DeleteRowsImpact(impact=None, blockers=[blocker]))
+
+    def unexpected_delete(*args, **kwargs):
+        raise AssertionError("Deletion must not run after a blocked preflight.")
+
+    monkeypatch.setattr(
+        "apps.v1.routers.portfolio_groups.bulk_delete_portfolio_groups",
+        unexpected_delete,
+    )
+
+    response = TestClient(app).post(
+        "/api/v1/portfolio-group/bulk-delete/",
+        json={"selection": {"mode": "explicit", "uids": [str(uuid.uuid4())]}, "options": {}},
+    )
+
+    assert response.status_code == 409
+    assert response.json() == {"detail": blocker}