mainsequence-metatable 0.1.27.dev47__tar.gz → 0.1.28.dev48__tar.gz

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/.agents/skills/client/metatables-migrations/SKILL.md

@@ -54,10 +54,13 @@ migrations. Read `docs/client/deploy-application-migrations.md`.
    Environment, the application's tables need an owning Team: one platform Team
    per Environment (for example `ledger-development`), whose members are the
    migration Job's workload User and the workload User of every resource that
-   reads or writes the tables. An Organization admin creates the application's
-   namespace in that Environment and grants the Team Writer on it. Tell the user
-   these steps; they are made in the platform and in MetaTables Security, not in
-   the repository.
+   reads or writes the tables. An Organization admin creates, in that
+   Environment, each namespace the provider registers tables in, and grants the
+   Team Writer on it. Recommend one namespace per application, owned by its Team;
+   it is not required (see "Namespaces and applications" in
+   `docs/security/ownership-and-sharing.md`).
+   Tell the user these steps; they are made in the platform and in MetaTables
+   Security, not in the repository.
 4. **Deploy.** The application's `.mainsequence/workflows/` file declares a
    migration Job that calls `upgrade_application` for each provider, in
    dependency order, from the candidate image. The Job and every resource that
@@ -83,8 +86,9 @@ Rules:
   with each Environment and each recreated Job; a new one needs Team membership
   only. Do not ask for direct table grants to a workload User, and do not run the
   Job as an Organization admin to get around a refusal.
-- Every table a provider registers goes in the Team's namespace. A table
-  registered in a namespace the caller already writes gets no grant of its own.
+- A table registered in a namespace the caller already writes gets no grant of
+  its own; the namespace's Writers own it. The Team needs Writer on every
+  namespace the provider uses.
 
 ## Source and runtime context
 

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/.agents/skills/ms_tau_sdk/PINNED_FROM.txt

@@ -1,7 +1,7 @@
 schema=1
 library_name=ms-tau-sdk
 namespace=ms_tau_sdk
-pinned_version=2.0.8
+pinned_version=2.0.9
 skills_path=src/ms_tau_sdk/agent_skills
 skills=tau_a2a_runtime_adapter,tau_local_development,tau_project_customization,tau_repository_integration,tau_security_and_access
 command=ms-tau skills sync --path .

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/.agents/skills/ms_tau_sdk/tau_project_customization/SKILL.md

@@ -81,6 +81,16 @@ in the system prompt because a tool named `read` exists. Extensions must not reg
 this mode.
 Excluding coding tools does not sandbox extension Python code.
 
+## Application tool time limits
+
+A declared application's tool sets how long it may run, in seconds, in its MCP `_meta` under
+`mainsequence.ai/timeout-seconds/v1`; with the MCP Python SDK that is
+`@mcp.tool(meta={"mainsequence.ai/timeout-seconds/v1": 300})` in the application. Set the limit on
+the application's tool, not in the Agent. A tool that declares nothing gets
+`TAU_MCP_TOOL_TIMEOUT_SECONDS` (default `60`); set it like the tool composition settings above, in
+`harness_agent.spec.env_vars`, the process environment, or
+`TauSDKSettings(mcp_tool_timeout_seconds=...)`. No call outlives its turn.
+
 ## Invariants extensions must not replace
 
 Extensions may change effective agent capabilities, but they must not replace or bypass:

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/.mainsequence/workflows/metatables-api.yaml

@@ -9,7 +9,18 @@ resources:
       automatic_redeployment:
         enabled: true
         tag_regex: null
-      min_scale: 1
+      # One Uvicorn process uses one core; configuration.yaml sizes its threads and
+      # connections as serving.concurrency (ADR 0022).
+      cpu_request: "1"
+      memory_request: 2Gi
+      min_scale: 2
+      # A pod runs serving.concurrency (20) requests at once, so the platform sends it no
+      # more and queues the rest while it adds pods. Ten pods keep 3 × 20 × 10 connections
+      # within the database budget (ADR 0022). The request timeout bounds deep_search,
+      # whose declared limit is 300 s.
+      container_concurrency: 20
+      max_scale: 10
+      timeout_seconds: 300
       revision_retention_count: 3
       # The Analyst's read tools, served at /mcp (ADR 0021).
       mcp_enabled: true

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.27.dev47
+Version: 0.1.28.dev48
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -51,7 +51,7 @@ Requires-Dist: twine<7,>=6; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
 Provides-Extra: agent
-Requires-Dist: ms-tau-sdk==2.0.8; extra == "agent"
+Requires-Dist: ms-tau-sdk==2.0.9; extra == "agent"
 Provides-Extra: mysql
 Requires-Dist: PyMySQL[rsa]<1.2,>=1.1.1; extra == "mysql"
 Provides-Extra: mssql

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/adr/agent/0019-metatables-analyst-agent.md

@@ -39,7 +39,7 @@ Status: Accepted.
 Implementation status: implemented on `development`; not yet deployed. Tests cover the
 tools against a stand-in catalog, `deep_search`, `describe_table` and `list_namespaces`
 through the client against the API, and the extension, card, workflow and vendored skills with
-ms-tau-sdk 2.0.8. A local `ms-tau` session and the hosted deployment have not run.
+ms-tau-sdk 2.0.9. A local `ms-tau` session and the hosted deployment have not run.
 
 Owner: this repository deploys the agent. The MetaTables API is unchanged; the agent
 is one more API client.
@@ -70,7 +70,7 @@ refuses anything else.
 
 | Part | Rule |
 | --- | --- |
-| Runtime | `ms-tau-sdk` 2.0.8, `openai-codex` / `gpt-5.6-luna`, thinking `medium`. |
+| Runtime | `ms-tau-sdk` 2.0.9, `openai-codex` / `gpt-5.6-luna`, thinking `medium`. |
 | Identity | The person each turn serves (ADR 0020); the agent's own identity holds no grants. |
 | Tools | The six tools below, served by the API over MCP when hosted (ADR 0021), and the SDK's skill-scoped `read`. No shell, file writes or Main Sequence MCP. |
 | Instructions | `.tau/SYSTEM.md` covers MetaTables; vendored `pg-aiguide` skills cover PostgreSQL and TimescaleDB. |
@@ -129,7 +129,7 @@ The agent card's two skills, `discover-tables` and `analyze-with-sql` in
 The skills of [timescale/pg-aiguide](https://github.com/timescale/pg-aiguide)
 (Apache-2.0) are vendored at commit `b236d35` with its license and notice, one
 directory per skill under `.tau/skills/`, because Tau discovers skills one level deep.
-The agent opens them through the skill-scoped `read`, which ms-tau-sdk 2.0.8 registers
+The agent opens them through the skill-scoped `read`, which ms-tau-sdk 2.0.9 registers
 when `TAU_EXCLUDE_BASE_TOOLS=true`. The directive takes precedence over them:
 
 - Discover tables through the MetaTables tools, not `pg_catalog`, which also lists

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/adr/agent/0020-analyst-reads-as-its-requester.md

@@ -3,7 +3,7 @@
 Status: Accepted.
 
 Implementation status: implemented on `development`; not deployed. It builds on platform
-ADR-0051 (requester-bound access, implemented 2026-10-06), ms-tau-sdk 2.0.8 for the
+ADR-0051 (requester-bound access, implemented 2026-10-06), ms-tau-sdk 2.0.9 for the
 Analyst and mainsequence 9.0.19, whose `User.get_requester()` the API reads. Tests cover
 admission through real signed assertions; a hosted turn has not run.
 

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/adr/agent/0021-api-serves-the-analyst-tools-over-mcp.md

@@ -34,6 +34,7 @@ The hosted API serves the read tools at `/mcp`, and the hosted Analyst uses them
 | Authorization | A tool's calls run through the API's own routes, in process, with the caller assertion of the `/mcp` request. The SDK verifies the same caller, or the person it works for, and each route authorizes exactly as over REST, including ADR 0020's read-only rule. |
 | Analyst | The agent declares `mcp_applications: [{resource: metatables}]` and gets `metatables__list_tools` and `metatables__call_tool`. Its extension registers the tools only in a local `ms-tau` session, where they call the local API as the developer. |
 | Key | The API's workflow key is `metatables`, because MCP keys become tool prefixes and must match `^[a-z][a-z0-9_]{0,39}$`. |
+| Time limits | Each tool declares how long an Agent should wait in its MCP `_meta` under `mainsequence.ai/timeout-seconds/v1` (ms-tau-sdk 2.0.9): 120 s, the bound of one in-process API call, and 300 s for `deep_search`, which the release's 300 s request timeout bounds. An undeclared tool would get the Agent's default of 60 s. |
 
 ## Consequences
 

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/adr/api/0002-application-administration-and-table-ownership.md

@@ -353,9 +353,13 @@ identity of the same application could not re-register its own tables
 ([#43](https://github.com/mainsequence-projects/MetaTables/issues/43)).
 
 - **A Team owns an application's tables.** Before an application's first
-  migration in an Environment, an Organization admin creates its namespace and
-  grants Writer on it to a platform Team. The application's migration Job and
-  every workload User that reads or writes its tables are members of that Team.
+  migration in an Environment, an Organization admin grants a platform Team Writer
+  on each namespace the application's tables are registered in, creating any that
+  don't exist. The application's migration Job and every workload User that reads
+  or writes its tables are members of that Team. One namespace per application is
+  recommended, not enforced: MetaTables authorizes identities and has no trusted
+  fact about which project a caller runs, so any Writer of a namespace may
+  register tables in it from any project.
   Use one Team per Environment, so that one Environment's workloads are not
   Writers in another. A new workload User needs Team membership only; the tables
   keep their owner.
@@ -433,9 +437,9 @@ schema baseline/recreation policy remains governed by ADR 0001.
   resources through counts, search, lineage, or error details.
 - A Writer can grant/revoke Reader and Writer access only on tables they control.
   Re-registering an existing table never grants the caller ownership.
-- A new member of the Team with Writer on an application's namespace registers and
-  migrates that application's existing tables; a caller outside it is refused with
-  a recovery path that reveals nothing it cannot read.
+- A new member of a Team with Writer on a table's namespace registers and migrates
+  that existing table; a caller outside it is refused with a recovery path that
+  reveals nothing it cannot read.
 - Team changes and namespace revocation/moves change effective access under the
   documented freshness rules; independent grants remain visible and effective.
 - Non-admins cannot manage DataSources, runtime selection, system migrations,

mainsequence_metatable-0.1.28.dev48/docs/adr/api/0022-concurrent-requests-and-connection-reuse.md

@@ -0,0 +1,130 @@
+# ADR 0022: Concurrent requests per pod and reused database connections
+
+Status: Proposed.
+
+Implementation status: implemented on development; not deployed. Unit tests pass;
+the container suite and the load test against the development deployment are pending.
+
+Owner: this repository.
+
+Related decisions: [ADR 0007](0007-database-enforced-table-access.md) (each User
+queries as their own login roles), [ADR 0012](0012-bounded-data-transfer-and-safe-retries.md)
+(deadlines, cancellation and the shared SQL security guard),
+[ADR 0001](0001-unified-api-storage-and-local-sqlite.md) (`configuration.yaml`),
+[ADR 0008](0008-mysql-mssql-table-workflows.md) (MySQL and SQL Server) and
+[ADR 0021](../agent/0021-api-serves-the-analyst-tools-over-mcp.md) (MCP tools call the
+API's own routes).
+
+## Context
+
+The hosted API must serve tens to hundreds of clients at the same time. Main Sequence
+runs it as identical pods, each running one Uvicorn process, and adds pods under load
+up to a maximum. A Python process runs Python code on one core at a time, so a pod's
+capacity comes from threads that wait on the database, and the API's capacity from the
+number of pods.
+
+Today:
+
+- Nearly every route is a plain `def`, so each request runs on one of the process's 40
+  worker threads, AnyIO's fixed default.
+- The catalog engine uses SQLAlchemy's default pool: 5 connections plus 10 overflow,
+  with a 30 s wait.
+- Each SQL request opens a new connection as the caller's login role and closes it
+  afterwards: a TCP and TLS handshake, a password check and a new database backend for
+  every request. MySQL and SQL Server build a whole engine per request, and physical
+  data-source operations build and dispose of one per call.
+- A SQL request holds two connections at once: its catalog transaction keeps the shared
+  SQL security guard (ADR 0012) while the login-role query runs.
+- ADR 0012's admission runs at most 8 data requests per process (`run-query`, `read`,
+  inserts and the other data actions) and answers 429 after a 1 s wait for a slot,
+  whatever the thread count.
+- Nothing relates the connections all pods may open to what the database allows.
+
+A burst therefore opens connections as fast as requests arrive, spends latency and
+database CPU on connecting, and can exhaust the database's connection limit.
+
+## Decision
+
+One number, **T**, sizes a pod: the requests it runs at once and the connections it may
+hold.
+
+| Part | Rule |
+| --- | --- |
+| Threads | Route handlers run on T threads per process. |
+| Catalog | The catalog pool holds at most T connections, with no overflow, and closes each at the maximum age. |
+| Data requests | ADR 0012's admission runs T data requests at once per process, not 8, and a request waits for a slot within its deadline instead of 1 s. `/runtime-context/` publishes the effective T as `transfer_limits.concurrent_requests`. |
+| Login-role connections | A pod holds at most T login-role connections per database server, idle or in use. A connection is reused only by the login role that opened it, never by another role and never through `SET ROLE` (ADR 0007). |
+| Data-source operations | Physical data-source operations reuse connections per (DataSource, login), through one kept engine on MySQL and SQL Server, instead of connecting per call; they count against the same cap. |
+| Budget | Maximum pods × 3T ≤ the database's `max_connections`, minus a reserve for migrations, the Admin and other clients: per pod, T catalog connections, T capped connections, and about T per-call connections (see below). Each server the API connects to has its own budget. |
+| Setting | `configuration.yaml` declares T as `serving.concurrency`. Local runtimes use the default. |
+
+Rules for reused connections:
+
+- Each use sets its own statement timeout, read-only or write mode, and search path.
+  Nothing carries over from a previous use: on PostgreSQL, `DISCARD ALL` returns the
+  session to its defaults before the connection is reused.
+- On MySQL and SQL Server, a login-role connection closes after each use. Neither
+  driver can reset a session, and SQL Server may keep a session's role memberships.
+  These connections still count against the cap; the DataSource's own login is reused.
+- A connection that errored, was cancelled, or stopped before its result was read is
+  closed, not reused. ADR 0012 already forbids draining a read to return a connection.
+- Idle connections close after a timeout, and every connection closes at a maximum age.
+  The maximum age bounds how long a connection outlives a password change or a disabled
+  login. Grant changes apply at once, because the database checks privileges on every
+  statement.
+- When the cap is full, the least recently used idle connection closes to make room. If
+  none is idle, the request waits within its deadline (ADR 0012) and then fails with 503,
+  `database_connections_busy` and `Retry-After: 1`. No statement ran, so a retry is safe.
+- MCP tool calls keep their own threads. The route calls a tool makes count against T
+  like any request. Sharing T would let tool calls hold every thread while their own
+  route calls wait.
+- Connection probes that bring their own host or timeout (DataSource validation and
+  maintenance), relation discovery and reads, and MySQL's administrative connections
+  (grant changes and `KILL QUERY`) connect per call, outside the cap. A pod's T threads
+  bound them to about T, the third T in the budget. A relation read holds its reader
+  while it runs the caller's login-role query; counting both against one cap could
+  leave every thread waiting for a second connection.
+
+### Suggested values
+
+These are starting values, not measurements. A load test against the development
+deployment replaces them.
+
+| Setting | Suggested | Why |
+| --- | --- | --- |
+| Pod CPU | 1 vCPU | One process uses one core. |
+| Pod memory | 2 GiB | About 160 MiB at idle, plus results in flight. |
+| Minimum pods | 2 | A burst lands on two pods while more start, and one survives a restart. |
+| T | 20 | At the current maximum of 10 pods: 3 × 20 × 10 = 600 connections. |
+| Idle timeout | 60 s | Long enough to reuse a role's connection across a session of requests. |
+| Maximum age | 30 min | Bounds a connection's life after a credential change. |
+
+The workflow declares CPU, memory and minimum pods for the `metatables` resource;
+`configuration.yaml` declares T. T is raised only when the budget allows it.
+
+The workflow also declares the platform's per-replica request policy
+(platform issues 921 and 922): `container_concurrency` equal to T, so the platform sends a pod
+no more requests than it has threads and queues the rest while it adds pods, and
+`max_scale` equal to the budget's maximum pods (10). Changing T changes both files.
+
+## Consequences
+
+- On PostgreSQL most requests reuse a connection; a role's first request on a pod still
+  connects. On MySQL and SQL Server, caller SQL and caller table operations still connect
+  per request, though their engines are kept.
+- Connections are bounded by configuration, not by traffic.
+- A pod runs at most T requests at once; further requests wait for a thread. Capacity
+  grows by adding pods.
+- Many Users share one cap per pod, so a pod serving many Users reconnects more often
+  than one serving few.
+- A reused connection stays logged in as its role until its idle timeout or maximum age.
+- SQLite has no login roles; only the thread count applies locally.
+- Changing T is a configuration change and a deployment.
+
+Verification: unit tests (`tests/integrations/test_connection_reuse.py`) cover role
+isolation, per-use settings and the session reset, closing broken connections, the cap
+and eviction, waiting within the deadline, the idle timeout and maximum age, T applied
+to the route threads, the catalog pool and data-request admission, and the kept engines. The hosted engines,
+including the MySQL and SQL Server behavior above, are verified through the container
+suite on request, and a load test against the development deployment sets the values
+above.

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/adr/index.md

@@ -39,6 +39,7 @@ decisions belong in the SDK repository and are linked as dependencies.
 | [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 whether the caller may write each table, from the planner the confirmed delete runs; cascade effects never block. Projects render it in their own UIs. |
 | [0017: Hosted caller identity through the SDK request identity](api/0017-hosted-request-identity.md) | Accepted; implemented for 0.1.21; hosted rollout verification pending | The hosted API installs the SDK request identity that the platform launcher requires; the SDK verifies each caller assertion once and admission reads `User.get_logged_user()`, including the caller's signed Teams and admin flag. Local keeps its loopback token admission. |
 | [0018: Table search by meaning and columns](api/0018-table-search.md) | Accepted; implemented; container engine verification pending | One route ranks visible tables by BM25 keywords and a local English embedding model over a per-table document that includes columns, merges the rankings and returns `matched_columns`; the index refreshes on every metadata write. |
+| [0022: Concurrent requests per pod and reused database connections](api/0022-concurrent-requests-and-connection-reuse.md) | Proposed; implemented on development; not deployed; container 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. |
 
 ## Agents
 

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/api/openapi.json

@@ -4439,7 +4439,7 @@
             "type": "integer"
           },
           "concurrent_requests": {
-            "default": 8,
+            "default": 20,
             "title": "Concurrent Requests",
             "type": "integer"
           },
@@ -4499,7 +4499,7 @@
             "type": "integer"
           },
           "queue_seconds": {
-            "default": 1,
+            "default": 60,
             "title": "Queue Seconds",
             "type": "integer"
           },
@@ -4918,6 +4918,26 @@
         "summary": "Hello"
       }
     },
+    "/caller/": {
+      "get": {
+        "description": "Who this request runs as: the User, Teams and admin flag the API admitted, named\nthrough the platform directory as that User sees it.\n\nHosted, the identity comes from the platform-signed caller assertion (ADR 0017);\nLocal and developer runtimes admit the developer's own SDK session.",
+        "operationId": "admitted_caller_caller__get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Admitted Caller",
+        "tags": [
+          "Runtime"
+        ]
+      }
+    },
     "/data-sources/": {
       "get": {
         "operationId": "list_sources_data_sources__get",
@@ -7124,6 +7144,58 @@
         ]
       }
     },
+    "/namespaces/{namespace_uid}/access-map/": {
+      "get": {
+        "description": "Principals, Teams, grants and tables of one namespace, as the caller may see them.",
+        "operationId": "namespace_access_map_namespaces__namespace_uid__access_map__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "namespace_uid",
+            "required": true,
+            "schema": {
+              "format": "uuid",
+              "title": "Namespace Uid",
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "relationships",
+            "required": false,
+            "schema": {
+              "default": false,
+              "title": "Relationships",
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Namespace Access Map",
+        "tags": [
+          "Namespaces"
+        ]
+      }
+    },
     "/namespaces/{namespace_uid}/tables/": {
       "get": {
         "operationId": "namespace_tables_namespaces__namespace_uid__tables__get",

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/api/reference.md

@@ -7,6 +7,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | Method | Path | Operation | Success responses |
 | --- | --- | --- | --- |
 | GET | `/` | Hello | 200 |
+| GET | `/caller/` | Admitted Caller | 200 |
 | GET | `/data-sources/` | List Sources | 200 |
 | POST | `/data-sources/` | Create Source | 201 |
 | POST | `/data-sources/test-connection/` | Test Source Connection | 200 |
@@ -51,6 +52,7 @@ These methods and paths are mounted by the current application. See the [OpenAPI
 | GET | `/namespaces/` | List Namespaces | 200 |
 | GET | `/namespaces/{namespace_uid}/` | Retrieve Namespace | 200 |
 | PATCH | `/namespaces/{namespace_uid}/` | Patch Namespace | 200 |
+| GET | `/namespaces/{namespace_uid}/access-map/` | Namespace Access Map | 200 |
 | GET | `/namespaces/{namespace_uid}/tables/` | Namespace Tables | 200 |
 | GET | `/namespaces/{uid}/permissions` | Namespace Permissions | 200 |
 | PUT | `/namespaces/{uid}/permissions` | Set Namespace Permissions | 200 |

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/api/tables-and-migrations.md

@@ -183,6 +183,9 @@ but does not expire the configured database login.
 After execution, the client closes its database connection and calls
 `finalize-managed` with actual revision IDs (or explicit null at base). Finalization
 reconciles physical contracts, dropped provider tables and SQL permission projections.
+The client finalizes at most 10 tables per request, the Alembic version table first,
+so each request holds the catalog lock briefly and finishes within the hosted request
+limit. If a run stops partway, rerunning it finalizes the tables still reserved.
 The former `/application-migrations/upgrade/` endpoint and provider allowlist are
 removed. MetaTables system migrations run in the hosted deployment's migration Job,
 or through Settings in Local mode. See

mainsequence_metatable-0.1.28.dev48/docs/assets/diagrams/namespace-access.svg

@@ -0,0 +1,115 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="740" viewBox="0 0 1240 740" role="img" aria-labelledby="ns-title ns-desc">
+  <title id="ns-title">Namespaces are access groups, not application boundaries</title>
+  <desc id="ns-desc">In one Environment, the workload Users of the prices application are members of the Team prices-development, which is Writer on namespace prices. The workload Users of the trading application are members of trading-development, which is Writer on namespace trading and Reader on namespace prices. Registering a table in a namespace requires Writer on it or admin. Reading or writing a table requires a grant on the table or its namespace, checked by the API and by the database. Which project's tables go in which namespace is not checked.</desc>
+  <style>
+    .sans { font-family: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; }
+    .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .title { font-size: 22px; font-weight: 700; fill: #0f172a; }
+    .sub { font-size: 14px; fill: #475569; }
+    .col { font-size: 11.5px; font-weight: 700; fill: #64748b; letter-spacing: 0.08em; }
+    .name { font-size: 14px; font-weight: 700; fill: #0f172a; }
+    .small { font-size: 12px; fill: #64748b; }
+    .table { font-size: 12.5px; fill: #1e293b; }
+    .note { font-size: 13px; fill: #334155; }
+    .head { font-size: 15px; font-weight: 700; fill: #0f172a; }
+    .tag { font-size: 11.5px; font-weight: 700; letter-spacing: 0.08em; }
+    .label { font-size: 12.5px; font-weight: 700; }
+    .box { fill: #ffffff; stroke: #cbd5e1; stroke-width: 1.5; }
+    .team { fill: #f1f5f9; stroke: #64748b; stroke-width: 1.5; }
+    .ns { fill: #ffffff; stroke: #94a3b8; stroke-width: 1.5; }
+    .pill { fill: #f8fafc; stroke: #e2e8f0; stroke-width: 1; }
+    .member { fill: none; stroke: #64748b; stroke-width: 1.6; marker-end: url(#ns-arrow-member); }
+    .writer { fill: none; stroke: #c2410c; stroke-width: 2.4; marker-end: url(#ns-arrow-writer); }
+    .reader { fill: none; stroke: #1d4ed8; stroke-width: 2.4; stroke-dasharray: 7 5; marker-end: url(#ns-arrow-reader); }
+  </style>
+  <defs>
+    <marker id="ns-arrow-member" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#64748b"/></marker>
+    <marker id="ns-arrow-writer" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#c2410c"/></marker>
+    <marker id="ns-arrow-reader" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#1d4ed8"/></marker>
+  </defs>
+  <rect width="1240" height="740" rx="16" fill="#f8fafc"/>
+  <text x="40" y="48" class="sans title">Namespaces are access groups, not application boundaries</text>
+  <text x="40" y="74" class="sans sub">One Environment · Teams own namespaces · every check is on the caller's identity, never on its project</text>
+
+  <text x="40" y="114" class="sans col">WORKLOAD USERS</text>
+  <text x="380" y="114" class="sans col">PLATFORM TEAMS</text>
+  <text x="760" y="114" class="sans col">METATABLES NAMESPACES AND TABLES</text>
+
+  <!-- prices application -->
+  <rect x="40" y="135" width="260" height="44" rx="8" class="box"/>
+  <text x="56" y="162" class="sans name">prices migration Job</text>
+  <rect x="40" y="195" width="260" height="44" rx="8" class="box"/>
+  <text x="56" y="222" class="sans name">prices API</text>
+  <path d="M 300 157 L 378 179" class="member"/>
+  <path d="M 300 217 L 378 196" class="member"/>
+  <rect x="380" y="159" width="230" height="56" rx="10" class="team"/>
+  <text x="396" y="184" class="mono name">prices-development</text>
+  <text x="396" y="203" class="sans small">Team</text>
+
+  <path d="M 610 187 L 758 187" class="writer"/>
+  <text x="684" y="178" class="sans label" fill="#c2410c" text-anchor="middle">Writer</text>
+
+  <rect x="760" y="128" width="440" height="128" rx="12" class="ns"/>
+  <text x="780" y="153" class="sans small">namespace</text>
+  <text x="852" y="153" class="mono name">prices</text>
+  <rect x="780" y="166" width="400" height="24" rx="6" class="pill"/>
+  <text x="792" y="183" class="mono table">prices.alembic_version</text>
+  <rect x="780" y="196" width="400" height="24" rx="6" class="pill"/>
+  <text x="792" y="213" class="mono table">prices.daily_close</text>
+  <rect x="780" y="226" width="400" height="24" rx="6" class="pill"/>
+  <text x="792" y="243" class="mono table">prices.intraday</text>
+
+  <!-- trading application -->
+  <rect x="40" y="365" width="260" height="44" rx="8" class="box"/>
+  <text x="56" y="392" class="sans name">trading migration Job</text>
+  <rect x="40" y="425" width="260" height="44" rx="8" class="box"/>
+  <text x="56" y="452" class="sans name">trading API</text>
+  <path d="M 300 387 L 378 409" class="member"/>
+  <path d="M 300 447 L 378 426" class="member"/>
+  <rect x="380" y="389" width="230" height="56" rx="10" class="team"/>
+  <text x="396" y="414" class="mono name">trading-development</text>
+  <text x="396" y="433" class="sans small">Team</text>
+
+  <path d="M 610 425 L 758 425" class="writer"/>
+  <text x="684" y="448" class="sans label" fill="#c2410c" text-anchor="middle">Writer</text>
+
+  <path d="M 610 403 C 680 403, 690 262, 758 248" class="reader"/>
+  <text x="702" y="318" class="sans label" fill="#1d4ed8">Reader</text>
+  <text x="702" y="334" class="sans small">every current and</text>
+  <text x="702" y="349" class="sans small">future prices table</text>
+
+  <rect x="760" y="380" width="440" height="98" rx="12" class="ns"/>
+  <text x="780" y="405" class="sans small">namespace</text>
+  <text x="852" y="405" class="mono name">trading</text>
+  <rect x="780" y="418" width="400" height="24" rx="6" class="pill"/>
+  <text x="792" y="435" class="mono table">trading.alembic_version</text>
+  <rect x="780" y="448" width="400" height="24" rx="6" class="pill"/>
+  <text x="792" y="465" class="mono table">trading.orders</text>
+
+  <text x="40" y="510" class="sans small">A new workload User, after a new Environment or a recreated Job, only needs Team membership. The namespaces and their tables keep their owner.</text>
+
+  <!-- checks -->
+  <rect x="40" y="540" width="373" height="170" rx="12" class="box"/>
+  <text x="58" y="570" class="sans tag" fill="#15803d">ENFORCED</text>
+  <text x="58" y="596" class="sans head">Registering a table in a namespace</text>
+  <text x="58" y="622" class="sans note">The caller must be a Writer of the namespace,</text>
+  <text x="58" y="642" class="sans note">directly or through a Team, or an admin.</text>
+  <text x="58" y="662" class="sans note">Otherwise: 403 namespace_not_writable.</text>
+  <text x="58" y="682" class="sans note">A Writer's new table gets no grant of its own.</text>
+
+  <rect x="433" y="540" width="373" height="170" rx="12" class="box"/>
+  <text x="451" y="570" class="sans tag" fill="#15803d">ENFORCED</text>
+  <text x="451" y="596" class="sans head">Reading or writing a table</text>
+  <text x="451" y="622" class="sans note">A grant on the table or on its namespace,</text>
+  <text x="451" y="642" class="sans note">to the caller or one of its Teams. Checked</text>
+  <text x="451" y="662" class="sans note">by the API and by the caller's own role in</text>
+  <text x="451" y="682" class="sans note">the database.</text>
+
+  <rect x="826" y="540" width="374" height="170" rx="12" class="box"/>
+  <text x="844" y="570" class="sans tag" fill="#b91c1c">NOT ENFORCED</text>
+  <text x="844" y="596" class="sans head">Which project uses which namespace</text>
+  <text x="844" y="622" class="sans note">Any Writer of prices can register tables there</text>
+  <text x="844" y="642" class="sans note">from any project. A project may use several</text>
+  <text x="844" y="662" class="sans note">namespaces or share one. One namespace per</text>
+  <text x="844" y="682" class="sans note">application is a recommendation.</text>
+</svg>

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/client/deploy-application-migrations.md

@@ -93,11 +93,14 @@ application's tables belong to a platform Team instead:
 2. **Add the workload Users.** Add the migration Job's workload User, and the
    workload User of every resource that reads or writes the tables (FastAPI
    release, Agent, other Jobs). Each resource's `workload_user_uid` names it.
-3. **Grant the Team the namespace.** An Organization admin creates the
-   application's namespace in that Environment's MetaTables, under
-   **Security**, or with `POST /security/namespaces/`, and grants the Team Writer
-   on it (`PUT /namespaces/{uid}/permissions`). Every table registered in the
-   namespace inherits the grant.
+3. **Grant the Team its namespaces.** For each namespace the tables are
+   registered in, an Organization admin creates it in that Environment's
+   MetaTables if it doesn't exist yet, under **Security** or with
+   `POST /security/namespaces/`, and grants the Team Writer on it
+   (`PUT /namespaces/{uid}/permissions`). Every table registered in the namespace
+   inherits the grant. One namespace per application is the recommended layout,
+   not a rule; see
+   [Namespaces and applications](../security/ownership-and-sharing.md#namespaces-and-applications).
 
 The Job also needs platform `view` on the Environment's `metatables` release and
 its branch to discover the API; declare it on the Job:
@@ -142,8 +145,8 @@ writes gets no grant of its own, so the Team stays its only owner.
 - The Job finds the Environment's MetaTables API the same way any client does
   ([installation and connection](installation-and-connection.md)). That API must
   be deployed with its system migrations applied; otherwise the Job fails. Its
-  workload User needs Writer on the application's namespace through the Team
-  above.
+  workload User needs Writer, through the Team above, on every namespace the
+  provider registers tables in.
 
 ## Keep each release compatible with the previous one
 

{mainsequence_metatable-0.1.27.dev47 → mainsequence_metatable-0.1.28.dev48}/docs/concepts/permissions-namespaces-labels.md

@@ -20,6 +20,11 @@ removes that contribution; independent direct or Team grants remain effective.
 Moving a table requires its Writer and destination namespace Writer, or admin
 authority for the destination. Table Writer alone cannot change global grants.
 
+A namespace is not tied to a project. Registering a table in it needs Writer on
+the namespace, whatever project the caller runs. One namespace per application,
+owned by a Team per Environment, is the recommended layout; see
+[Namespaces and applications](../security/ownership-and-sharing.md#namespaces-and-applications).
+
 ## Labels
 
 Labels classify resources and never authorize an operation. The catalog owns