mainsequence-metatable 0.1.16.dev28__tar.gz → 0.1.17__tar.gz

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -138,6 +138,14 @@ A null cutoff requires a scope. Do not replace that workflow with ad hoc SQL.
 Deletion/cascade requires edit access, relevant protection checks, and explicit
 cascade intent; it is not an administrator-role bypass or migration repair.
 
+Before a destructive action, or to show impact in an application UI, call
+`table.get_impact(action=...)` with `delete_rows`, `update_keys` or `drop_table`.
+The API returns whether the caller may run it, every blocker, and a graph of
+affected tables, foreign-key effects and reading updates; render that result
+rather than re-deriving foreign-key or permission rules in the client. Cascading
+foreign keys are allowed, but write on a table requires write on every table its
+cascades modify; a cascade into an unregistered table makes the parent read-only.
+
 On a TimescaleDB DataSource, time-index tables are hypertables. Their compression
 and retention policies are set only through `TimeIndexMetaTable.set_timescale_policies`
 (Writer) and read with `get_timescale_policies`. Do not add policies to table

{mainsequence_metatable-0.1.16.dev28/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.16.dev28
+Version: 0.1.17
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/adr/api/0007-database-enforced-table-access.md

@@ -14,6 +14,15 @@
 > `metatables` schema and tables in the DataSource's default schema; it need not
 > own the database.
 
+> Amendment (2026-10-03): Cascading foreign keys are allowed. The database runs
+> `CASCADE`, `SET NULL` and `SET DEFAULT` actions as the table owner, so a role
+> keeps write on a table only while every login reaching it can also write each
+> table those actions modify, following chains of cascades. A cascade into an
+> unregistered table leaves the parent read-only. Registration and reconciliation
+> record each table's cascade targets; nothing inspects submitted queries. This
+> replaces the rule that foreign keys must use `restrict` or `no action`, which the
+> implementation applied on every engine, not only where the explorer is enabled.
+
 
 Date: 2026-09-29
 
@@ -193,8 +202,8 @@ client.
 - Any role can see the names, columns and row counts of every table in PostgreSQL's
   system catalogs, but not their data. MetaTables accepts this where the explorer
   is enabled. Role names are opaque, because table permissions are visible too.
-- PostgreSQL runs foreign-key cascades as the table owner. Where the explorer is
-  enabled, foreign keys must use `restrict` or `no action`.
+- Databases run foreign-key cascades as the table owner. Write on a table
+  requires write on every table its cascades modify (amendment 2026-10-03).
 - Heavy queries still consume resources. Per-role connection limits, time limits
   and, optionally, a read replica bound them.
 
@@ -274,7 +283,8 @@ and [MySQL implicit commits](https://dev.mysql.com/doc/refman/8.4/en/implicit-co
 - The DataSource login needs `CREATEROLE` and the right to create the `metatables`
   schema; it does not need to own the database.
 - Physical table names become visible to explorer users.
-- Cascading foreign keys are unavailable where the explorer is enabled.
+- Cascading foreign keys narrow write access to callers who can write the whole
+  cascade; a cascade into an unregistered table makes its parent read-only.
 - Team membership reaches the database at the pace of the existing one-hour
   platform-fact cache.
 

mainsequence_metatable-0.1.17/docs/adr/api/0016-impact-preflight.md

@@ -0,0 +1,109 @@
+# ADR 0016: Impact pre-flight for cascades and deletes
+
+Date: 2026-10-03
+
+Status: Accepted.
+
+Implementation status: implemented. Tests cover the planner through the Python
+client against an isolated catalog and the SQLite engine. PostgreSQL,
+TimescaleDB, MySQL and SQL Server cascade-target queries have not yet been run
+against their containers.
+
+Owner: MetaTables API. The Python client exposes the result; consuming projects
+own their UIs.
+
+Related decisions: [ADR 0001](0001-unified-api-storage-and-local-sqlite.md) (the SDK
+makes no access decisions of its own), [ADR 0002](0002-application-administration-and-table-ownership.md)
+(cascades need access to every affected table) and [ADR 0007](0007-database-enforced-table-access.md)
+(amended 2026-10-03: write requires write on every cascade target).
+
+## Context
+
+Cascading foreign keys are now allowed. A caller keeps write on a table only while
+they can write every table its `CASCADE`, `SET NULL` and `SET DEFAULT` actions
+modify. A project that builds its own UI needs to show, before acting, which
+tables a delete or key update reaches, what happens to each, and why a write is
+or is not available. Before this decision, a caller could only try the action
+and read the error.
+
+## Decision
+
+The API answers one question: *what would this action do, and may I do it?* The
+API computes the answer from the catalog and the recorded cascade targets. The
+client returns it unchanged.
+
+```
+GET /meta-tables/{uid}/impact/?action=delete_rows|update_keys|drop_table
+GET /time-index-meta-tables/{uid}/impact/?action=...
+```
+
+`drop_table` also accepts the `delete-with-cascade` options. The client method is
+`MetaTable.get_impact(action=...) -> MetaTableImpact`, inherited by
+`TimeIndexMetaTable`.
+
+```python
+impact = table.get_impact(action="delete_rows")
+if not impact.allowed:
+    for blocker in impact.blockers:
+        print(blocker.code, blocker.node, blocker.message)
+```
+
+The response is a graph rooted at the table:
+
+- **Nodes**:
+  - `meta_table` nodes carry the uid, identifier, namespace and physical name.
+  - `relation` nodes are unregistered physical tables, identified by physical
+    name only.
+  - `update` nodes are updates that read an affected table.
+  - `hidden` nodes are tables the caller cannot view. They are opaque: an effect
+    with no names.
+
+  Each node lists its `effects` (`drop`, `delete`, `update`, `input_changed`) and
+  the caller's `can_write`. For row actions, `can_write` is the database
+  privilege after cascade narrowing, computed by the same function the
+  reconciler uses. For `drop_table`, it is the edit grant the drop requires.
+- **Edges**: each edge points from the dependent to what it depends on, as in
+  the schema graph. Edges are classified by effect: `cascade_delete`,
+  `cascade_update`, `set_null`, `set_default`, `restrict` (fails while
+  referencing rows exist), `drop`, and `reads`.
+- **Verdict**: `allowed` and every blocker, each with a code and the node it
+  concerns:
+  - `cascade_target_unregistered`
+  - `cascade_target_not_writable`
+  - `table_not_writable`
+  - `writes_unsupported`
+  - `data_source_read_only`
+  - `retained_referencing_table`
+  - `alembic_protection`
+  - `deletion_protected`
+
+`delete-with-cascade` runs the same planner (`persistence/impact.py`) and refuses
+with its first blocker's status and message, so a preview and the confirmed
+delete cannot disagree. Recorded cascade targets now carry each foreign key's
+`on_delete` and `on_update` action and are recorded for every table, so read-only
+callers see the same graph.
+
+The pre-flight is advisory. The database and the confirmed actions still enforce
+every rule at execution time.
+
+## Remaining gaps
+
+| Need | Today |
+| --- | --- |
+| `on_update` in the catalog | `MetaTableForeignKey` and contracts carry only `on_delete`; contracts reject `set default`. Row-action edges use the physical actions, which are complete. |
+| Effective write in table responses | `permissions.write` reflects catalog grants and can say yes when cascade narrowing says no. Callers should use the pre-flight. |
+| Plain delete | `DELETE /meta-tables/{uid}/` still answers 409 without listing references. |
+| Contract changes | No `change_contract` action; a PATCH that would invalidate an incoming key fails with a text message. |
+| Schema and update graphs | `get_schema_graph` returns an untyped dict; `update-graph` has no client method. |
+| Views | No view-to-table dependency tracking; views stay read-only registrations. |
+| Admin visibility | `GET /security/database-permissions/` does not show cascade targets. |
+
+## Consequences
+
+- Consuming projects can render cascade and impact views without reimplementing
+  permission or foreign-key rules, and their UIs stay correct when those rules
+  change.
+- One planner serves both the preview and the confirmed delete.
+- Opaque nodes reveal that hidden tables are affected, but not which ones.
+- Reconciliation now inspects foreign keys for every registered table, not only
+  writable ones.

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/adr/index.md

@@ -36,3 +36,4 @@ decisions belong in the SDK repository and are linked as dependencies.
 | [0013: Application-owned migrations](api/0013-application-owned-migrations.md) | Accepted and implemented | Application-side Alembic, environment database authority, API catalog integration and separate system migrations. |
 | [0014: System migrations in the deployment workflow](api/0014-main-sequence-release-jobs-and-production-migrations.md) | Accepted; implemented on development; hosted verification pending | A Main Sequence Job verifies, migrates and registers the declared runtime database from the candidate image before each API rollout, including the first. |
 | [0015: TimescaleDB compression and retention policies](api/0015-timescale-compression-and-retention-policies.md) | Accepted; implemented on branch; TimescaleDB verification pending | Time-index tables on TimescaleDB become hypertables; Writers set compression and retention through the API/Admin; Timescale keeps the jobs, and the Admin shows their status. |
+| [0016: Impact pre-flight for cascades and deletes](api/0016-impact-preflight.md) | Accepted; implemented; container engine verification pending | `get_impact` returns what a row delete, key update or table drop reaches, every blocker and the caller's effective write, from the planner the confirmed delete runs; projects render it in their own UIs. |

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/api/openapi.json

@@ -6001,6 +6001,96 @@
         ]
       }
     },
+    "/meta-tables/{table_uid}/impact/": {
+      "get": {
+        "description": "Read-only pre-flight; the confirmed delete runs the same planner (ADR 0016).",
+        "operationId": "get_impact_meta_tables__table_uid__impact__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "table_uid",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "title": "Table Uid",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "action",
+            "required": true,
+            "schema": {
+              "enum": [
+                "delete_rows",
+                "update_keys",
+                "drop_table"
+              ],
+              "title": "Action",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "delete_referencing_meta_tables",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Delete Referencing Meta Tables",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "delete_referencing_time_index_meta_tables",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Delete Referencing Time Index Meta Tables",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "override_schema_management_protection",
+            "required": false,
+            "schema": {
+              "default": false,
+              "title": "Override Schema Management Protection",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Get Impact Meta Tables  Table Uid  Impact  Get",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Impact",
+        "tags": [
+          "MetaTables"
+        ]
+      }
+    },
     "/meta-tables/{table_uid}/introspect/": {
       "post": {
         "operationId": "introspect_meta_table_meta_tables__table_uid__introspect__post",
@@ -8978,6 +9068,96 @@
         ]
       }
     },
+    "/time-index-meta-tables/{table_uid}/impact/": {
+      "get": {
+        "description": "Read-only pre-flight; the confirmed delete runs the same planner (ADR 0016).",
+        "operationId": "time_index_get_impact_time_index_meta_tables__table_uid__impact__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "table_uid",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "title": "Table Uid",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "action",
+            "required": true,
+            "schema": {
+              "enum": [
+                "delete_rows",
+                "update_keys",
+                "drop_table"
+              ],
+              "title": "Action",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "delete_referencing_meta_tables",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Delete Referencing Meta Tables",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "delete_referencing_time_index_meta_tables",
+            "required": false,
+            "schema": {
+              "default": true,
+              "title": "Delete Referencing Time Index Meta Tables",
+              "type": "boolean"
+            }
+          },
+          {
+            "in": "query",
+            "name": "override_schema_management_protection",
+            "required": false,
+            "schema": {
+              "default": false,
+              "title": "Override Schema Management Protection",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "title": "Response Time Index Get Impact Time Index Meta Tables  Table Uid  Impact  Get",
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Time Index Get Impact",
+        "tags": [
+          "TimeIndexMetaTables"
+        ]
+      }
+    },
     "/time-index-meta-tables/{table_uid}/introspect/": {
       "post": {
         "operationId": "time_index_introspect_meta_table_time_index_meta_tables__table_uid__introspect__post",

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/api/reference.md

@@ -31,6 +31,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | GET | `/meta-tables/{table_uid}/` | Retrieve Table | 200 |
 | PATCH | `/meta-tables/{table_uid}/` | Patch Meta Table | 200 |
 | POST | `/meta-tables/{table_uid}/delete-with-cascade/` | Delete With Cascade | 200 |
+| GET | `/meta-tables/{table_uid}/impact/` | Get Impact | 200 |
 | POST | `/meta-tables/{table_uid}/introspect/` | Introspect Meta Table | 200 |
 | POST | `/meta-tables/{table_uid}/migration-connection/` | Migration Connection | 200 |
 | POST | `/meta-tables/{table_uid}/read/` | Read Rows | 200 |
@@ -89,6 +90,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | POST | `/time-index-meta-tables/{table_uid}/get-data-between-dates-from-remote/` | Get Data Between Dates From Remote | 200 |
 | POST | `/time-index-meta-tables/{table_uid}/get-last-observation/` | Get Last Observation | 200 |
 | GET | `/time-index-meta-tables/{table_uid}/get-stats/` | Get Time Index Stats | 200 |
+| GET | `/time-index-meta-tables/{table_uid}/impact/` | Time Index Get Impact | 200 |
 | POST | `/time-index-meta-tables/{table_uid}/introspect/` | Time Index Introspect Meta Table | 200 |
 | POST | `/time-index-meta-tables/{table_uid}/migration-connection/` | Time Index Migration Connection | 200 |
 | GET | `/time-index-meta-tables/{table_uid}/schema-graph` | Time Index Get Schema Graph | 200 |

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/reference/capabilities.md

@@ -60,6 +60,7 @@ This inventory records the support status of public resource methods and CLI com
 | `MetaTable.get_effective_access` | tested | `GET /meta-tables/{uid}/effective-access/` | Reader/Writer sharing through the application security API; changes require Writer or application admin, with revision conflict checks. Tests: `tests/permissions/test_security_api.py::test_public_client_access_roundtrip` |
 | `MetaTable.get_object_url` | internal |  | Transport, serialization, or model lifecycle helper; not a separate API operation. |
 | `MetaTable.get_or_none` | implemented | `GET /meta-tables/{table_uid}/` | Generic resource operation with a mounted API route. Check route constraints; method-specific evidence is not claimed. |
+| `MetaTable.get_impact` | tested | `GET /meta-tables/{table_uid}/impact/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_impact_preflight_matches_cascade_rules` |
 | `MetaTable.get_schema_graph` | tested | `GET /meta-tables/{table_uid}/schema-graph` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_local_actor_client_api.py::test_client_detail_validation_uses_platform_membership_and_revocation` |
 | `MetaTable.import_from_data_source` | tested | `POST /meta-tables/import-from-data-source/` | Import creates relational external registrations (preview by default); bounded reads enforce existing MetaTable grants and never accept SQL. Inherited methods use the shared MetaTable endpoint. Tests: `tests/database_backend/test_relation_import.py::test_python_client_import_read_and_writer_refresh` |
 | `MetaTable.introspect` | tested | `POST /meta-tables/{table_uid}/introspect/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_introspection_client_api.py::test_client_introspection_checks_grant_and_persists_snapshot` |
@@ -147,6 +148,7 @@ This inventory records the support status of public resource methods and CLI com
 | `TimeIndexMetaTable.get_object_url` | internal |  | Transport, serialization, or model lifecycle helper; not a separate API operation. |
 | `TimeIndexMetaTable.get_or_create` | tested | `POST /time-index-meta-tables/get-or-create/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_registration_bulk_and_time_index_get_or_create` |
 | `TimeIndexMetaTable.get_or_none` | implemented | `GET /time-index-meta-tables/{table_uid}/` | Generic resource operation with a mounted API route. Check route constraints; method-specific evidence is not claimed. |
+| `TimeIndexMetaTable.get_impact` | tested | `GET /time-index-meta-tables/{table_uid}/impact/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_impact_preflight_matches_cascade_rules` |
 | `TimeIndexMetaTable.get_schema_graph` | tested | `GET /time-index-meta-tables/{table_uid}/schema-graph` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_local_actor_client_api.py::test_client_detail_validation_uses_platform_membership_and_revocation` |
 | `TimeIndexMetaTable.import_from_data_source` | tested | `POST /meta-tables/import-from-data-source/` | Import creates relational external registrations (preview by default); bounded reads enforce existing MetaTable grants and never accept SQL. Inherited methods use the shared MetaTable endpoint. Tests: `tests/database_backend/test_relation_import.py::test_python_client_import_read_and_writer_refresh` |
 | `TimeIndexMetaTable.introspect` | tested | `POST /time-index-meta-tables/{table_uid}/introspect/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_introspection_client_api.py::test_client_introspection_checks_grant_and_persists_snapshot` |

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/reference/python.md

@@ -43,6 +43,10 @@ Import application APIs from `metatables`. This list is generated from `metatabl
 | `MetaTableCompiledSQLVersion` | `typing` | constant |
 | `MetaTableContract` | `metatables.models` | class |
 | `MetaTableForeignKeyPayload` | `metatables.models` | class |
+| `MetaTableImpact` | `metatables.models` | class |
+| `MetaTableImpactBlocker` | `metatables.models` | class |
+| `MetaTableImpactEdge` | `metatables.models` | class |
+| `MetaTableImpactNode` | `metatables.models` | class |
 | `MetaTableIndexPayload` | `metatables.models` | class |
 | `MetaTableManagementMode` | `typing` | constant |
 | `MetaTableMigrationConnection` | `metatables.models` | class |

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/docs/security/index.md

@@ -128,7 +128,9 @@ statement classification or function allowlist. The database enforces access in
 joins, CTEs, subqueries and permitted invoker routines. Database permissions are
 established during setup and schema changes. Catalog tables remain inaccessible,
 views cannot be registered, elevated routines cannot confer owner access, and
-triggered writes and cascading foreign keys are restricted by the engine's policy.
+triggered writes are restricted by the engine's policy. A table with cascading
+foreign keys is writable only by callers who can write every table the cascade
+modifies.
 
 PostgreSQL stores the catalog in `metatables` and owns managed tables through a
 non-login owner role. User, Team and namespace grants become database privileges

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/mkdocs.yml

@@ -82,3 +82,4 @@ nav:
           - "0013: Application-owned migrations": adr/api/0013-application-owned-migrations.md
           - "0014: System migrations in the deployment workflow": adr/api/0014-main-sequence-release-jobs-and-production-migrations.md
           - "0015: TimescaleDB compression and retention policies": adr/api/0015-timescale-compression-and-retention-policies.md
+          - "0016: Impact pre-flight": adr/api/0016-impact-preflight.md

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.16.dev28"
+version = "0.1.17"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.16.dev28
+Version: 0.1.17
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/src/mainsequence_metatable.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ docs/adr/api/0012-bounded-data-transfer-and-safe-retries.md
 docs/adr/api/0013-application-owned-migrations.md
 docs/adr/api/0014-main-sequence-release-jobs-and-production-migrations.md
 docs/adr/api/0015-timescale-compression-and-retention-policies.md
+docs/adr/api/0016-impact-preflight.md
 docs/adr/client/0003-api-endpoint-resolution.md
 docs/adr/client/0011-cli-local-development-with-managed-admin.md
 docs/api/authentication-and-errors.md
@@ -299,6 +300,7 @@ src/metatables/api/backend/migrations/versions/0006_local_credentials.py
 src/metatables/api/backend/migrations/versions/0007_external_relation_names.py
 src/metatables/api/backend/migrations/versions/0008_upload_receipts.py
 src/metatables/api/backend/migrations/versions/0009_timescale_policies.py
+src/metatables/api/backend/migrations/versions/0010_cascade_targets.py
 src/metatables/api/backend/migrations/versions/__init__.py
 src/metatables/api/backend/operations/__init__.py
 src/metatables/api/backend/operations/bootstrap_migrations.py
@@ -315,6 +317,7 @@ src/metatables/api/backend/persistence/cascade.py
 src/metatables/api/backend/persistence/catalog.py
 src/metatables/api/backend/persistence/database.py
 src/metatables/api/backend/persistence/grants.py
+src/metatables/api/backend/persistence/impact.py
 src/metatables/api/backend/persistence/labels.py
 src/metatables/api/backend/persistence/locking.py
 src/metatables/api/backend/persistence/models.py
@@ -523,6 +526,7 @@ tests/packaging/test_dev_release_version.py
 tests/packaging/test_distribution_sources.py
 tests/packaging/test_editable_build.py
 tests/packaging/test_installed_distribution.py
+tests/permissions/test_cascade_writes.py
 tests/permissions/test_governed_sql_scope.py
 tests/permissions/test_local_actor_membership.py
 tests/permissions/test_migration_boundary.py

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/src/metatables/__init__.py

@@ -140,6 +140,10 @@ _CLIENT_EXPORTS = (
     'MetaTableCascadeDeleteResponse',
     'MetaTableCascadeDeletedTimeIndexMetaTable',
     'MetaTableCascadeDeletedMetaTable',
+    'MetaTableImpact',
+    'MetaTableImpactBlocker',
+    'MetaTableImpactEdge',
+    'MetaTableImpactNode',
     'MetaTableMigrationConnection',
     'MetaTableMigrationConnectionRequest',
     'MetaTableColumnContract',

{mainsequence_metatable-0.1.16.dev28 → mainsequence_metatable-0.1.17}/src/metatables/api/app/routes/table_cascade.py

@@ -1,9 +1,9 @@
-"""Confirmed dependency deletion; every affected object needs a local edit grant."""
+"""Confirmed dependency deletion and its impact pre-flight; every affected object needs a local edit grant."""
 from collections import defaultdict
 from typing import Literal
 from uuid import UUID
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel
 from sqlalchemy import delete, select
 from sqlalchemy.exc import SQLAlchemyError
@@ -18,10 +18,12 @@ from metatables.api.backend.backends.operations import (
     PhysicalTableDeleteOutcomeUnknown,
     drop_tables,
 )
+from metatables.api.backend.domain.catalog_rules import CatalogInvariantError
 from metatables.api.backend.domain.data_source_rules import DataSourceAdmissionError
 from metatables.api.backend.domain.permission_rules import TrustedActorFacts
 from metatables.api.backend.integrations.runtime_data_sources import DataSourceIntegrationError
 from metatables.api.backend.persistence.grants import GrantRepository
+from metatables.api.backend.persistence.impact import DropOptions, ImpactPlanner
 from metatables.api.backend.persistence.locking import lock_catalog
 from metatables.api.backend.persistence.models import (
     MetaTable,
@@ -41,32 +43,37 @@ def cascade_deleter():
     return drop_tables
 
 def _plan(session, actor, root_uid, payload):
-    planned = {root_uid}
-    while True:
-        related = set(session.scalars(select(MetaTableForeignKey.source_table_uid).where(
-            MetaTableForeignKey.target_table_uid.in_(planned))))
-        related.update(session.scalars(select(MetaTable.uid).where(
-            MetaTable.alembic_version_meta_table_uid.in_(planned))))
-        remaining = related - planned
-        if not remaining:
-            break
-        planned.update(remaining)
-    rows = tuple(session.scalars(select(MetaTable).where(MetaTable.uid.in_(planned)).with_for_update()))
-    if len(rows) != len(planned):
-        raise HTTPException(404, 'MetaTable not found.')
-    for row in rows:
-        if (not GrantRepository(session).may_access_table(table_uid=row.uid, actor=actor, edit=True)):
-            raise HTTPException(404, 'An affected MetaTable was not found.')
-        if row.uid != root_uid and not (payload.delete_referencing_time_index_meta_tables if row.kind == 'time_index'
-                                       else payload.delete_referencing_meta_tables):
-            raise HTTPException(409, 'Deletion is blocked by a retained referencing table.')
-        alembic = row.schema_management_mode == 'alembic_managed'
-        if alembic and not payload.override_schema_management_protection:
-            raise HTTPException(409, 'Alembic protection requires explicit override.')
-        if (row.protect_from_deletion and not alembic):
-            raise HTTPException(409, 'An affected MetaTable is protected from deletion.')
+    rows, blockers = ImpactPlanner(session, actor).drop_closure(root_uid, _options(payload), lock=True)
+    if blockers:
+        raise HTTPException(blockers[0].status, blockers[0].message)
     return rows
 
+
+def _options(payload):
+    return DropOptions(
+        delete_referencing_meta_tables=payload.delete_referencing_meta_tables,
+        delete_referencing_time_index_meta_tables=payload.delete_referencing_time_index_meta_tables,
+        override_schema_management_protection=payload.override_schema_management_protection,
+    )
+
+
+@router.get('/{table_uid}/impact/')
+def get_impact(table_uid: UUID, action: Literal['delete_rows', 'update_keys', 'drop_table'] = Query(...),
+               delete_referencing_meta_tables: bool = True,
+               delete_referencing_time_index_meta_tables: bool = True,
+               override_schema_management_protection: bool = False,
+               actor: TrustedActorFacts = Depends(trusted_actor_facts),
+               session: Session = Depends(catalog_session)) -> dict:
+    """Read-only pre-flight; the confirmed delete runs the same planner (ADR 0016)."""
+    options = DropOptions(delete_referencing_meta_tables, delete_referencing_time_index_meta_tables,
+                          override_schema_management_protection)
+    try:
+        return ImpactPlanner(session, actor).plan(table_uid, action, options)
+    except CatalogInvariantError as exc:
+        if 'does not exist' in str(exc):
+            raise HTTPException(404, 'MetaTable not found.') from exc
+        raise HTTPException(422, str(exc)) from exc
+
 @router.post('/{table_uid}/delete-with-cascade/')
 def delete_with_cascade(table_uid: UUID, payload: CascadeRequest,
                         actor: TrustedActorFacts = Depends(trusted_actor_facts),