mainsequence-metatable 0.1.59__tar.gz → 0.1.60.dev91__tar.gz

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -168,6 +168,14 @@ access; row/time limits and transaction handling remain in the API. Refer to the
 query guide for engine-specific statement/batch behavior. Application DDL belongs
 to the separate migration-provider workflow.
 
+A write that must change several tables together on SQLite, where `WITH` holds only
+`SELECT`, is a statement list: `compile_sqlalchemy_statements([...],
+operation=...)` and `MetaTable.execute_transaction(...)`, one API-owned transaction.
+Wrap a check in `GuardedStatement(statement, expect_rows=n or "at_least_one",
+label=...)`; a miss rolls back and raises `MetaTableTransactionGuardError`. Never
+put `COMMIT` or savepoints in a list. PostgreSQL and SQLite only; see the query
+guide's "Several statements in one transaction".
+
 To find tables, use `MetaTable.search` as described in the
 [table discovery skill](../metatables-table-discovery/SKILL.md). Legacy convenience
 sharing/label actions are not supported API workflows.

{mainsequence_metatable-0.1.59/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.60.dev91}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.59
+Version: 0.1.60.dev91
 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.59 → mainsequence_metatable-0.1.60.dev91}/docs/adr/api/0007-database-enforced-table-access.md

@@ -1,5 +1,12 @@
 # ADR 0007: Enforce table grants in the database
 
+> Amendment (2026-11-10, [MetaTables #98](https://github.com/mainsequence-projects/MetaTables/issues/98)):
+> [ADR 0026](0026-atomic-statement-lists.md) lets a write carry an ordered list of
+> statements that the API runs in one transaction. One statement per request still holds
+> for each statement: each goes to the driver alone, and after each one the driver must
+> report the API's transaction still open, or the API stops and rolls back. Reads keep
+> one statement.
+
 > Amendment (2026-10-19): [ADR 0024](0024-namespace-and-table-access-roles.md) keeps the two
 > privilege sets: `data_viewer` maps to Reader's `SELECT`, `data_writer`, `editor` and `owner`
 > to Writer's privileges, and `metadata_viewer` to none. An admin group role holds write
@@ -214,7 +221,8 @@ with `SET ROLE` is not safe: caller SQL can switch to another User's role with
 `set_config('role', …)`.
 
 Each request sends exactly one statement through PostgreSQL's extended query
-protocol, which rejects a second statement such as `COMMIT; DELETE …`. Read-only
+protocol, which rejects a second statement such as `COMMIT; DELETE …`. (A write may
+send an ordered list of such statements in one API transaction: see ADR 0026.) Read-only
 requests run in a `READ ONLY` transaction. The API cancels queries that exceed
 their time limit, because callers can change their own timeout settings.
 

mainsequence_metatable-0.1.60.dev91/docs/adr/api/0026-atomic-statement-lists.md

@@ -0,0 +1,138 @@
+# ADR 0026: Atomic statement lists
+
+Status: Accepted.
+
+Implementation status: implemented on development for 0.1.60. SQLite is tested in
+process, both on a source's own connection and on the local runtime's borrowed request
+transaction. The PostgreSQL path has not been run: its end-to-end test is written but
+skips without the disposable cluster of `scripts/test_postgresql.py`. MySQL and SQL
+Server refuse statement lists.
+
+Owner: MetaTables API, with the Python client.
+
+Related decisions: [ADR 0007](0007-database-enforced-table-access.md) (the database
+enforces table access; one statement per request),
+[ADR 0012](0012-bounded-data-transfer-and-safe-retries.md) (bounded transfers) and
+[ADR 0022](0022-concurrent-requests-and-connection-reuse.md) (connection reuse).
+Issue: [MetaTables#98](https://github.com/mainsequence-projects/MetaTables/issues/98).
+
+## Context
+
+Some client writes change several tables and must commit together. ms-markets writes
+an account snapshot as one PostgreSQL statement: data-modifying CTEs upsert the
+parents, delete the old rows and insert the new ones, after a check that every named
+portfolio is still live
+([MainSequenceMarkets#53](https://github.com/mainsequence-projects/MainSequenceMarkets/issues/53)).
+
+SQLite, the local runtime, allows only `SELECT` inside `WITH`. On SQLite the write
+must be several statements, but a compiled operation carries one statement and each
+request is its own transaction. Sending the statements as separate operations would
+leave half-written history after a failure, and the portfolio check would no longer
+share the write's transaction.
+
+## Decision
+
+### A write may carry an ordered list of statements
+
+`POST /meta-tables/execute-transaction/` accepts `compiled-sql.v1` with `statements`,
+a list of 1 to 32 compiled statements, and a write operation (`insert`, `update`,
+`delete` or `upsert`). The API opens one write transaction as the caller's own write
+identity and sends the statements in order. It commits after the last statement and
+rolls back on any error. The response has the shape of `execute-operation` and holds
+the last statement's rows.
+
+Statements do not pass values to each other. A later statement finds what an earlier
+one wrote by its key, in the same transaction.
+
+The client compiles the list with `compile_sqlalchemy_statements` and sends it with
+`MetaTable.execute_transaction`.
+
+### A statement may expect a row count
+
+A statement may carry `expect_rows`: an exact count, or `"at_least_one"`. The count is
+the statement's result rows, or the rows it changed when it returns none. When a
+statement misses its expectation, the API rolls back the whole transaction and answers
+409 with code `compiled_sql_guard_failed`, the statement's index and its optional
+`label`. The client raises `MetaTableTransactionGuardError`.
+
+A single PostgreSQL statement can hold such a check in a `WHERE`. Separate statements
+cannot abort a later one from SQL in a way that works on every engine and that the
+caller can tell from a database error, so the check is part of the request.
+
+### ADR 0007's boundary holds without reading the SQL
+
+ADR 0007 sends one statement per request so caller SQL cannot end the API's
+transaction and go on outside it, as in `COMMIT; DELETE …`. A statement list keeps
+that rule for each statement: each goes to the driver alone, through the same
+restricted path as `execute-operation`, so PostgreSQL's extended query protocol and
+Python's `sqlite3` still reject a second statement in one string.
+
+Between statements, the API asks the driver whether its transaction is still open:
+
+- **SQLite:** `sqlite3.Connection.in_transaction`. The engine authorizer already
+  denies `BEGIN`, `COMMIT`, `ROLLBACK` and savepoints, so this check is a second line.
+- **PostgreSQL:** the connection's transaction status must be "in transaction", and
+  the statement's command tag must not be transaction control (`BEGIN`, `COMMIT`,
+  `ROLLBACK`, `SAVEPOINT`, `RELEASE`, `PREPARE TRANSACTION` and the prepared forms).
+  The tag is needed because `COMMIT AND CHAIN` leaves a new transaction open, without
+  the API's settings.
+
+Both answers come from the driver and the server, not from the SQL text. When the
+check fails, the API stops before the next statement, rolls back what is still open
+and answers 400 with `compiled_sql_transaction_ended`. On PostgreSQL a caller's
+`COMMIT` has already committed the statements before it; the API cannot undo that.
+The caller loses only its own atomicity: no statement runs after the API's
+transaction ended.
+
+Lists are refused for reads, so ADR 0007's `READ ONLY` transaction for reads is
+unchanged.
+
+Inside one transaction, a setting one statement makes, such as `SET LOCAL` or
+`set_config('role', …, true)`, applies to the next. This gives no new access: the
+login role is the caller's own and inherits all its memberships (ADR 0007), the API
+enforces the time limit with its own cancellation, and `DISCARD ALL` resets the
+connection before reuse (ADR 0022).
+
+### Limits cover the whole list
+
+- One time limit, `statement_timeout_ms` (at most 60 seconds), covers every statement:
+  SQLite's progress handler and the API's cancellation timer each start once.
+- `max_rows` and `offset` apply to the last statement's rows. Earlier statements'
+  rows are counted for their expectations and never returned.
+- A list holds at most 32 statements, and the request body stays within the transfer
+  limits of ADR 0012.
+
+### Engines
+
+SQLite and PostgreSQL, including TimescaleDB, run statement lists. On SQLite a source
+either opens its own connection, with `BEGIN IMMEDIATE` and a commit at the end, or
+borrows the request's catalog transaction, as the local runtime does; there the
+request's commit or rollback decides.
+
+MySQL and SQL Server refuse a list with 422 and `compiled_sql_statement_list_unsupported`.
+DDL in MySQL commits implicitly, and a SQL Server batch can commit before a later
+error, so each needs its own design.
+
+### The compiler refuses CTEs SQLite cannot run
+
+`compile_sqlalchemy_statement` raises `ValueError` when a CTE wraps `INSERT`, `UPDATE`
+or `DELETE` and the dialect is SQLite, MySQL or SQL Server. It inspects the SQLAlchemy
+object, so the error comes at compile time instead of a syntax error from the database.
+
+## Alternatives
+
+- **Several statements in one SQL string.** The API would have to split the text,
+  which is the parsing ADR 0007 removed.
+- **Separate operations in sequence.** Not atomic.
+- **A route for each client's write.** Ties the API to one client's tables.
+- **Guards as SQL that raises.** SQLite raises only inside triggers, and the caller
+  could not tell the failure from a database error.
+
+## Consequences
+
+- Clients write several tables atomically on the local runtime with the same code
+  path they use on PostgreSQL, sending a list where PostgreSQL takes one statement.
+- A PostgreSQL client that puts `COMMIT` in a list loses its own atomicity and gets
+  `compiled_sql_transaction_ended`.
+- The API holds one write transaction for up to the whole time limit, as a long single
+  statement already can.

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/adr/index.md

@@ -43,6 +43,7 @@ decisions belong in the SDK repository and are linked as dependencies.
 | [0022: Concurrent requests per pod and reused database connections](api/0022-concurrent-requests-and-connection-reuse.md) | Accepted; implemented on development; deployment and load verification pending | One number per pod sizes its threads, data-request admission, catalog pool and login-role connections; connections are reused only by the role that opened them, and maximum pods × 3T stays within the database's connection limit. |
 | [0023: A daily security check instead of a sweep in every deployment](api/0023-daily-security-check.md) | Accepted; implemented on development; deployment and first scheduled run pending | A deployment sets up only what the new release needs; a daily Job, which administrators can also start, repairs whatever differs from the plan without pausing caller SQL and records its outcome. |
 | [0024: Access roles for namespaces and tables](api/0024-namespace-and-table-access-roles.md) | Accepted; implemented on development (API and Admin); hosted deployment pending | Actions and roles (`metadata_viewer`, `data_viewer`, `data_writer`, `editor`, `owner`) replace Reader/Writer; `namespaces.create` and `tables.create` are checked on the parent, the creator of a namespace owns it, admins hold every action, workloads use access but never manage it, and an ordinary user deploys a new application without an admin. |
+| [0026: Atomic statement lists](api/0026-atomic-statement-lists.md) | Accepted; implemented on development for 0.1.60; SQLite tested, PostgreSQL not yet run | A write may carry up to 32 compiled statements that the API runs in order in one transaction it owns, with optional row expectations; each statement is sent alone and the driver must report the transaction still open after it, so ADR 0007's boundary holds without parsing SQL. PostgreSQL and SQLite only. |
 
 ## Agents
 

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/api/openapi.json

@@ -294,6 +294,62 @@
         "title": "CompiledOperation",
         "type": "object"
       },
+      "CompiledTransaction": {
+        "additionalProperties": false,
+        "properties": {
+          "data_source_uid": {
+            "format": "uuid",
+            "title": "Data Source Uid",
+            "type": "string"
+          },
+          "dialect": {
+            "default": "postgresql",
+            "enum": [
+              "postgresql",
+              "sqlite",
+              "mysql",
+              "mssql"
+            ],
+            "title": "Dialect",
+            "type": "string"
+          },
+          "limits": {
+            "$ref": "#/components/schemas/Limits"
+          },
+          "operation": {
+            "enum": [
+              "insert",
+              "update",
+              "delete",
+              "upsert"
+            ],
+            "title": "Operation",
+            "type": "string"
+          },
+          "statements": {
+            "items": {
+              "$ref": "#/components/schemas/TransactionStatement"
+            },
+            "maxItems": 32,
+            "minItems": 1,
+            "title": "Statements",
+            "type": "array"
+          },
+          "version": {
+            "const": "compiled-sql.v1",
+            "default": "compiled-sql.v1",
+            "title": "Version",
+            "type": "string"
+          }
+        },
+        "required": [
+          "operation",
+          "statements",
+          "data_source_uid"
+        ],
+        "title": "CompiledTransaction",
+        "type": "object"
+      },
       "CompressedStatistics": {
         "properties": {
           "data": {
@@ -4580,6 +4636,88 @@
         "title": "TimescaleTablePolicies",
         "type": "object"
       },
+      "TransactionStatement": {
+        "additionalProperties": false,
+        "properties": {
+          "expect_rows": {
+            "anyOf": [
+              {
+                "minimum": 0.0,
+                "type": "integer"
+              },
+              {
+                "const": "at_least_one",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Expect Rows"
+          },
+          "label": {
+            "anyOf": [
+              {
+                "maxLength": 200,
+                "minLength": 1,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Label"
+          },
+          "parameter_types": {
+            "anyOf": [
+              {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Parameter Types"
+          },
+          "parameters": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "items": {},
+                "type": "array"
+              }
+            ],
+            "title": "Parameters"
+          },
+          "paramstyle": {
+            "default": "pyformat",
+            "enum": [
+              "pyformat",
+              "named",
+              "qmark"
+            ],
+            "title": "Paramstyle",
+            "type": "string"
+          },
+          "sql": {
+            "maxLength": 1000000,
+            "minLength": 1,
+            "title": "Sql",
+            "type": "string"
+          }
+        },
+        "required": [
+          "sql"
+        ],
+        "title": "TransactionStatement",
+        "type": "object"
+      },
       "TransferLimits": {
         "properties": {
           "chunk_receipts": {
@@ -5750,6 +5888,46 @@
         ]
       }
     },
+    "/meta-tables/execute-transaction/": {
+      "post": {
+        "description": "Run compiled statements in order in one API-owned transaction (ADR 0026).\n\nThe API commits after the last statement and rolls back on any error, on a\nstatement that misses its ``expect_rows`` (409 ``compiled_sql_guard_failed``) and\non caller SQL that ends or controls the transaction. The last statement's rows\nreturn in the ``execute-operation`` response shape.",
+        "operationId": "execute_transaction_meta_tables_execute_transaction__post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompiledTransaction"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Execute Transaction",
+        "tags": [
+          "MetaTables"
+        ]
+      }
+    },
     "/meta-tables/filter/": {
       "post": {
         "operationId": "filter_meta_tables_meta_tables_filter__post",
@@ -8841,6 +9019,46 @@
         ]
       }
     },
+    "/time-index-meta-tables/execute-transaction/": {
+      "post": {
+        "description": "Run compiled statements in order in one API-owned transaction (ADR 0026).\n\nThe API commits after the last statement and rolls back on any error, on a\nstatement that misses its ``expect_rows`` (409 ``compiled_sql_guard_failed``) and\non caller SQL that ends or controls the transaction. The last statement's rows\nreturn in the ``execute-operation`` response shape.",
+        "operationId": "time_index_execute_transaction_time_index_meta_tables_execute_transaction__post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompiledTransaction"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Time Index Execute Transaction",
+        "tags": [
+          "TimeIndexMetaTables"
+        ]
+      }
+    },
     "/time-index-meta-tables/filter/": {
       "post": {
         "operationId": "time_index_filter_meta_tables_time_index_meta_tables_filter__post",

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/api/reference.md

@@ -23,6 +23,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | POST | `/meta-tables/` | Reserve Tables | 201 |
 | GET | `/meta-tables/column-search/` | Column Search | 200 |
 | POST | `/meta-tables/execute-operation/` | Execute Operation | 200 |
+| POST | `/meta-tables/execute-transaction/` | Execute Transaction | 200 |
 | POST | `/meta-tables/filter/` | Filter Meta Tables | 200 |
 | POST | `/meta-tables/finalize-managed/` | Finalize Managed | 200 |
 | POST | `/meta-tables/import-from-data-source/` | Import Source | 200 |
@@ -83,6 +84,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | POST | `/time-index-meta-tables/` | Reserve Tables | 201 |
 | GET | `/time-index-meta-tables/column-search/` | Time Index Column Search | 200 |
 | POST | `/time-index-meta-tables/execute-operation/` | Time Index Execute Operation | 200 |
+| POST | `/time-index-meta-tables/execute-transaction/` | Time Index Execute Transaction | 200 |
 | POST | `/time-index-meta-tables/filter/` | Time Index Filter Meta Tables | 200 |
 | POST | `/time-index-meta-tables/finalize-managed/` | Time Index Finalize Managed | 200 |
 | POST | `/time-index-meta-tables/get-data-between-dates-from-table-update/` | Get Data Between Dates From Table Update | 200 |

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/api/tables-and-migrations.md

@@ -150,6 +150,26 @@ default to 1,000 and are capped at 10,000; time limits default to 15 seconds and
 capped at 60 seconds. `operation="select"` selects read mode; the other operation
 labels select write mode. They do not classify SQL.
 
+`POST /meta-tables/execute-transaction/` accepts the same fields with `statements`,
+a list of 1 to 32 statements, in place of `statement`, and a write operation
+(`insert`, `update`, `delete` or `upsert`). Each statement may add `expect_rows`
+(an exact count or `"at_least_one"`) and a `label`. The API runs them in order in
+one write transaction, commits after the last and rolls back on any error. It
+returns the last statement's rows in the `execute-operation` shape; the limits cover
+the whole list. Its errors:
+
+| Status | Code | When |
+| --- | --- | --- |
+| 400 | `compiled_sql_database_error` | A statement failed in the database; the body adds `statement_index` and `label`. |
+| 400 | `compiled_sql_transaction_ended` | Caller SQL ended or controlled the API's transaction (PostgreSQL). |
+| 400 | `sql_deadline_exceeded` | The list ran past its time limit. |
+| 409 | `compiled_sql_guard_failed` | A statement missed `expect_rows`; the body adds `statement_index`, `label`, `expect_rows` and `row_count`. |
+| 422 | `compiled_sql_statement_list_unsupported` | The DataSource is MySQL or SQL Server. |
+| 422 | `compiled_sql_dialect_mismatch` | A statement's dialect or paramstyle differs from the DataSource's. |
+| 422 | (request validation) | A read operation, an empty or longer list, or an invalid `expect_rows`. |
+
+See [ADR 0026](../adr/api/0026-atomic-statement-lists.md).
+
 `POST /meta-tables/run-query/` accepts `{"data_source_uid": "…", "sql": "…"}` and
 optional `limits`. It uses the same restricted execution path in read mode and
 returns the `ok/results/truncated/max_rows/row_count/error` success envelope. Errors

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/client/query-and-mutate.md

@@ -63,10 +63,80 @@ version tables. Sharing, schema changes and table deletion remain API operations
 
 Bind values instead of interpolating user input. Requests have row and time limits.
 A full page indicates that more rows may exist. PostgreSQL, SQLite and MySQL reject
-multiple statements. SQL Server accepts a batch under the same restricted identity;
-an explicit commit inside a write batch can persist writes before a later error.
-Use the supported table operations when an operation needs their transaction and
-journal guarantees. See [database access](../security/index.md#sql-and-schema-boundary).
+multiple statements in one SQL string. SQL Server accepts a batch under the same
+restricted identity; an explicit commit inside a write batch can persist writes
+before a later error. To write several statements atomically, send a
+[statement list](#several-statements-in-one-transaction). Use the supported table
+operations when an operation needs their journal guarantees. See
+[database access](../security/index.md#sql-and-schema-boundary).
+
+Only PostgreSQL runs `INSERT`, `UPDATE` or `DELETE` inside `WITH`. For SQLite, MySQL
+and SQL Server, `compile_sqlalchemy_statement` raises `ValueError` when a CTE wraps
+one, instead of returning SQL the database rejects when it runs.
+
+## Several statements in one transaction
+
+A write that changes several tables together, such as a snapshot header and its
+rows, can be one PostgreSQL statement with data-modifying CTEs. SQLite cannot run
+that. Send the steps as a statement list instead: the API runs them in order in one
+transaction it owns, commits after the last one and rolls back all of them on any
+error ([ADR 0026](../adr/api/0026-atomic-statement-lists.md)).
+
+```python
+from sqlalchemy import delete, insert, select
+
+from metatables import MetaTable, MetaTableTransactionGuardError
+from metatables.compiled_sql.v1 import (
+    GuardedStatement,
+    compile_sqlalchemy_statements,
+    dialect_upsert,
+)
+
+transaction = compile_sqlalchemy_statements(
+    [
+        GuardedStatement(
+            select(portfolio.c.uid).where(
+                portfolio.c.uid.in_(portfolio_uids), portfolio.c.retired_at.is_(None)
+            ),
+            expect_rows=len(portfolio_uids),
+            label="live_portfolios",
+        ),
+        dialect_upsert(snapshot, header, key_columns=["account_uid", "as_of"]),
+        delete(holding).where(holding.c.account_uid == account_uid),
+        insert(holding).values(rows).returning(holding.c.symbol),
+    ],
+    operation="upsert",
+)
+try:
+    result = MetaTable.execute_transaction(transaction)
+except MetaTableTransactionGuardError as error:
+    raise PortfolioRetired(error.label) from error  # Nothing was written.
+```
+
+- **Statements.** Each item is a SQLAlchemy statement, or a `GuardedStatement` with
+  `expect_rows` and a `label`. A list has 1 to 32 statements. Statements do not
+  pass values to each other: a later one finds an earlier one's rows by key.
+- **Guards.** `expect_rows` is an exact count or `"at_least_one"`. The count is the
+  statement's result rows, or the rows it changed when it returns none. A miss
+  rolls everything back and raises `MetaTableTransactionGuardError`, a subclass of
+  the SDK's `ConflictError` (HTTP 409, code `compiled_sql_guard_failed`) with
+  `statement_index` (from 0), `label`, `expect_rows` and `row_count`.
+- **Result.** The last statement's rows, in the `execute_operation` response shape.
+  `limits` cover the whole list: one time limit for every statement, and `max_rows`
+  for the last statement's rows.
+- **Writes only.** `operation` is `insert`, `update`, `delete` or `upsert`; it
+  selects the write identity, as in `execute_operation`.
+- **Engines.** PostgreSQL and SQLite, including the local runtime. MySQL and SQL
+  Server refuse a list: the compiler raises `ValueError`, and the API answers 422
+  with `compiled_sql_statement_list_unsupported`.
+- **Transaction control.** The API owns the transaction. SQLite refuses `COMMIT`,
+  `ROLLBACK` and savepoints as unauthorized. On PostgreSQL, a statement that ends or
+  controls the transaction stops the list with HTTP 400 and
+  `compiled_sql_transaction_ended`; statements before it may already be committed.
+
+Other errors keep their `execute_operation` codes. A database error is HTTP 400
+`compiled_sql_database_error`, raised as the SDK's `BadRequestError`; for a list,
+its `payload["detail"]` also names `statement_index` and `label`.
 
 ## Read another registered source
 

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/reference/capabilities.md

@@ -43,6 +43,7 @@ This inventory records the support status of public resource methods and CLI com
 | `MetaTable.delete_with_cascade_by_uid` | tested | `POST /meta-tables/{table_uid}/delete-with-cascade/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_cascade_and_inherited_crud` |
 | `MetaTable.destroy_by_uid` | tested | `DELETE /meta-tables/{table_uid}/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_delete_client_api.py::test_public_delete_requires_edit_and_journals_physical_drop` |
 | `MetaTable.execute_operation` | tested | `POST /meta-tables/execute-operation/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_sql_and_migration_connection_check_local_scope` |
+| `MetaTable.execute_transaction` | tested | `POST /meta-tables/execute-transaction/` | Writes several compiled statements in one API-owned transaction with optional row expectations (ADR 0026). SQLite tested through the local API and on its own connection; PostgreSQL not yet run; MySQL and SQL Server refuse. Tests: `tests/e2e/test_statement_lists.py::test_snapshot_writes_commit_together_or_not_at_all`, `tests/integrations/test_sqlite_statement_lists.py::test_a_failing_later_statement_rolls_back_every_earlier_write` |
 | `MetaTable.explain` | tested | `GET /meta-tables/{uid}/access/explain/` | Roles on namespaces and tables (ADR 0024) through the access API; changes need set_access or a workload's manager, with revision conflict checks. Tests: `tests/permissions/test_security_api.py::test_public_client_role_roundtrip` |
 | `MetaTable.filter` | implemented | `GET /meta-tables/` | Generic resource operation with a mounted API route. Check route constraints; method-specific evidence is not claimed. |
 | `MetaTable.filter_by_body` | tested | `POST /meta-tables/filter/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_filter_client_api.py::test_public_body_filter_hydrates_visible_tables_and_counts_before_page` |
@@ -110,6 +111,7 @@ This inventory records the support status of public resource methods and CLI com
 | `TimeIndexMetaTable.delete_with_cascade_by_uid` | tested | `POST /time-index-meta-tables/{table_uid}/delete-with-cascade/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_cascade_and_inherited_crud` |
 | `TimeIndexMetaTable.destroy_by_uid` | tested | `DELETE /time-index-meta-tables/{table_uid}/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_delete_client_api.py::test_public_delete_requires_edit_and_journals_physical_drop` |
 | `TimeIndexMetaTable.execute_operation` | tested | `POST /time-index-meta-tables/execute-operation/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_remaining_client_routes.py::test_public_sql_and_migration_connection_check_local_scope` |
+| `TimeIndexMetaTable.execute_transaction` | tested | `POST /time-index-meta-tables/execute-transaction/` | Writes several compiled statements in one API-owned transaction with optional row expectations (ADR 0026). SQLite tested through the local API and on its own connection; PostgreSQL not yet run; MySQL and SQL Server refuse. Tests: `tests/e2e/test_statement_lists.py::test_snapshot_writes_commit_together_or_not_at_all`, `tests/integrations/test_sqlite_statement_lists.py::test_a_failing_later_statement_rolls_back_every_earlier_write` |
 | `TimeIndexMetaTable.explain` | tested | `GET /meta-tables/{uid}/access/explain/` | Roles on namespaces and tables (ADR 0024) through the access API; changes need set_access or a workload's manager, with revision conflict checks. Tests: `tests/permissions/test_security_api.py::test_public_client_role_roundtrip` |
 | `TimeIndexMetaTable.filter` | implemented | `GET /time-index-meta-tables/` | Generic resource operation with a mounted API route. Check route constraints; method-specific evidence is not claimed. |
 | `TimeIndexMetaTable.filter_by_body` | tested | `POST /time-index-meta-tables/filter/` | Client/API behavior covered with isolated catalog and adapters; live storage checks are separate. Tests: `tests/e2e/test_table_filter_client_api.py::test_public_body_filter_hydrates_visible_tables_and_counts_before_page` |

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/docs/reference/python.md

@@ -43,6 +43,7 @@ Import application APIs from `metatables`. This list is generated from `metatabl
 | `MetaTableCompiledSQLDialect` | `typing` | constant |
 | `MetaTableCompiledSQLOperation` | `metatables.models` | class |
 | `MetaTableCompiledSQLParamstyle` | `typing` | constant |
+| `MetaTableCompiledSQLTransaction` | `metatables.models` | class |
 | `MetaTableCompiledSQLVersion` | `typing` | constant |
 | `MetaTableContract` | `metatables.models` | class |
 | `MetaTableForeignKeyPayload` | `metatables.models` | class |
@@ -61,7 +62,10 @@ Import application APIs from `metatables`. This list is generated from `metatabl
 | `MetaTableRequestFields` | `metatables.models` | class |
 | `MetaTableSchemaManagementMode` | `typing` | constant |
 | `MetaTableStatementPayload` | `metatables.models` | class |
+| `MetaTableTransactionGuardError` | `metatables.models` | class |
+| `MetaTableTransactionStatement` | `metatables.models` | class |
 | `MetaTableValidateContractRequest` | `metatables.models` | class |
+| `MetaTableWriteOperation` | `typing` | constant |
 | `Namespace` | `metatables.models` | class |
 | `POSTGRES_IDENTIFIER_MAX_LENGTH` | `metatables` | constant |
 | `PlatformManagedMetaTable` | `metatables.sqlalchemy_contracts` | class |

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/mkdocs.yml

@@ -89,6 +89,7 @@ nav:
           - "0022: Concurrent requests and connection reuse": adr/api/0022-concurrent-requests-and-connection-reuse.md
           - "0023: Daily security check": adr/api/0023-daily-security-check.md
           - "0024: Namespace and table access roles": adr/api/0024-namespace-and-table-access-roles.md
+          - "0026: Atomic statement lists": adr/api/0026-atomic-statement-lists.md
       - Agents:
           - "0019: MetaTables Analyst agent": adr/agent/0019-metatables-analyst-agent.md
           - "0020: The Analyst reads as its requester": adr/agent/0020-analyst-reads-as-its-requester.md

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91}/pyproject.toml

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

{mainsequence_metatable-0.1.59 → mainsequence_metatable-0.1.60.dev91/src/mainsequence_metatable.egg-info}/PKG-INFO

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