mainsequence-metatable 0.1.27.dev46__tar.gz → 0.1.28__tar.gz

{mainsequence_metatable-0.1.27.dev46 → mainsequence_metatable-0.1.28}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -178,3 +178,7 @@ for restart recovery. On an uncertain outcome, inspect `upload_receipt()` before
 resubmitting; do not assign a fresh key to bypass uncertainty. Administrator
 reconciliation requires verified physical evidence. This workflow uses the Main
 Sequence API and has no Artifact or temporary-URL dependency.
+
+A 429 `transfer_capacity_exceeded` or 503 `database_connections_busy` means the
+API was at capacity and nothing ran. Retry after `Retry-After`, including SQL and
+writes; it is not an uncertain outcome.

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

@@ -1,6 +1,6 @@
 ---
 name: metatables-migrations
-description: "Create and evolve managed application tables through Alembic migration providers with the installed MetaTables Python client. Covers provider scope and placement, scaffolding, revision authoring, local execution, the deployment-workflow migration Job for hosted runtimes, and reservation or finalization failures. Excludes API catalog migrations, client-library implementation, API/server changes and repository tooling."
+description: "Create and evolve managed application tables through Alembic migration providers with the installed MetaTables Python client. Covers provider scope and placement, scaffolding, revision authoring, local execution, the deployment-workflow migration Job for hosted runtimes, the Team that owns an application's tables in each Environment, and reservation or finalization failures. Excludes API catalog migrations, client-library implementation, API/server changes and repository tooling."
 ---
 
 # MetaTables client application migrations
@@ -50,11 +50,24 @@ migrations. Read `docs/client/deploy-application-migrations.md`.
 1. **Develop locally.** Author the revision and apply it to verified local SQLite
    with the [local development skill](../metatables-local-development/SKILL.md).
 2. **Commit the revision with the code that needs it.**
-3. **Deploy.** The application's `.mainsequence/workflows/` file declares a
+3. **Give a Team the tables.** Before the first hosted migration in each
+   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, 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. Every deployed resource that reads
-   or writes the tables (FastAPI, `harness_agent` and others) has a deploy step
-   with `needs: [migrate]`. A failed migration blocks the rollout.
+   dependency order, from the candidate image. The Job and every resource that
+   uses MetaTables declare `access.branches: [{repository: MetaTables, level: view}]`.
+   Every deployed resource that reads or writes the tables (FastAPI,
+   `harness_agent` and others) has a deploy step with `needs: [migrate]`. A failed
+   migration blocks the rollout.
 
 Rules:
 
@@ -69,6 +82,13 @@ Rules:
   during and after a failed rollout. Add first; drop or rename in a later release.
 - Redeploying an older image does not roll back the schema. Downgrade is never a
   deployment step.
+- Tables belong to the Team, never to one workload User. Workload Users change
+  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.
+- 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
 
@@ -205,14 +225,25 @@ Read `docs/operations/recovery-and-observability.md`.
   another install overwrote it. Move the provider as the
   [legacy upgrade skill](../metatables-upgrade-legacy-app/SKILL.md) describes;
   do not edit files in `site-packages`.
-- If reservation fails, compare provider scope and physical identities before
-  changing code. Do not create a second catalog row for the same table.
+- If reservation fails with `namespace_not_writable` or `table_not_editable`
+  (403), the caller lacks Writer through the owning Team. Add the
+  `caller_user_uid` from the error to the Team with Writer on the namespace, or,
+  when the namespace or Team is missing, set them up as in step 3. A table
+  registered before the Team existed may have only a retired workload User as
+  Writer; an Organization admin grants the Team Writer on its namespace. Do not
+  change code or physical names to get around it.
+- If reservation fails otherwise, compare provider scope and physical identities
+  before changing code. Do not create a second catalog row for the same table.
 - If Alembic succeeds but finalization fails, physical DDL may already be
   committed. Inspect every per-table result and the actual schema before
   retrying.
 - Inspect partial DDL before retrying, especially on engines without transactional
   DDL. A finalization-only failure can be retried without reapplying committed
   revisions. Client DDL has no API executor journal.
+- Finalization sends at most 10 tables per request, the version table first, and
+  reports `Finalizing MetaTables 11-20 of 62.` for larger providers (client 0.1.28
+  and later). A run that stops partway leaves earlier batches active; rerun the
+  same upgrade to finalize the rest.
 - Destructive catalog deletion is not migration recovery and never bypasses
   schema-management protection.
 
@@ -220,5 +251,6 @@ Read `docs/operations/recovery-and-observability.md`.
 
 Verify provider scope and placement, revision content, the selected environment
 connection, repeat execution, and final active bindings. Check that the deployment
-workflow runs the migration Job before every resource that uses the tables. Report
+workflow runs the migration Job before every resource that uses the tables, and
+that each Environment has its owning Team with the Job's workload User. Report
 separately what was checked offline and what was exercised against a configured API.

{mainsequence_metatable-0.1.27.dev46 → mainsequence_metatable-0.1.28}/.agents/skills/client/metatables-time-index-table-updates/SKILL.md

@@ -124,3 +124,7 @@ for restart recovery. On an uncertain outcome, inspect `upload_receipt()` before
 resubmitting; do not assign a fresh key to bypass uncertainty. Administrator
 reconciliation requires verified physical evidence. This workflow uses the Main
 Sequence API and has no Artifact or temporary-URL dependency.
+
+A 429 `transfer_capacity_exceeded` or 503 `database_connections_busy` means the
+API was at capacity and nothing ran. Retry after `Retry-After`, an upload with the
+same operation UUID; it is not an uncertain outcome.

{mainsequence_metatable-0.1.27.dev46 → mainsequence_metatable-0.1.28}/.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.dev46 → mainsequence_metatable-0.1.28}/.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.dev46 → mainsequence_metatable-0.1.28}/.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.dev46 → mainsequence_metatable-0.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.27.dev46
+Version: 0.1.28
 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.dev46 → mainsequence_metatable-0.1.28}/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.dev46 → mainsequence_metatable-0.1.28}/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.dev46 → mainsequence_metatable-0.1.28}/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.dev46 → mainsequence_metatable-0.1.28}/docs/adr/api/0002-application-administration-and-table-ownership.md

@@ -344,6 +344,46 @@ their own workload Users, which need to be granted like people.
   `reads_as_caller()`, the User `search` filter, `managed_by_caller`,
   `workload_name` and Team members that may be workload Users.
 
+### Amendment: Teams own application tables (2026-10-09)
+
+Since platform ADR-0048 every Job, release and Agent runs as its own workload
+User. Each Environment, and each recreated Job, has a new one. A table's creator
+grant tied the table to the workload User that first registered it, so the next
+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 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.
+- **No creator grant under a namespace Writer.** Registering a new table into a
+  namespace where the caller is already a Writer, directly or through a Team, adds
+  no creator grant: the namespace's Writers control the table. Otherwise the
+  creator still receives Writer, including an admin registering into a namespace
+  where they have no grant, so no table starts without a Writer.
+- **Creator attribution is a column.** `meta_table.created_by_user_uid` records
+  who registered each table and grants nothing. System migration
+  `0012_table_creator` adds it and fills it from each table's first self-granted
+  Writer in the grant history.
+- **Refusals say how to recover.** Registration refusals are 403s with a `code`:
+  `table_not_editable` for an existing table the caller cannot edit,
+  `namespace_not_writable` for a namespace that is missing or that the caller
+  cannot write. Both name the caller's User UID and the recovery: add it to the
+  Team with Writer on the namespace, or ask an Organization admin. The table's
+  namespace is named when the caller requested it or can read the table; its
+  Writers are listed only when the caller can read the table.
+
+Tables whose only Writer is a replaced identity are recovered the same way: an
+admin grants the application's Team Writer on their namespace. There is no admin
+bypass and no automatic adoption.
+
 ## Superseded behavior and preserved boundaries
 
 This decision supersedes ADR 0001's pending-runtime configurator/existing-source
@@ -397,6 +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 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.27.dev46 → mainsequence_metatable-0.1.28}/docs/adr/api/0007-database-enforced-table-access.md

@@ -32,6 +32,29 @@
 > Reconciliation still records each table's cascade targets, but only so the
 > [impact pre-flight](0016-impact-preflight.md) can show their effects.
 
+> Amendment (2026-10-09): On PostgreSQL and TimescaleDB, a catalog change applies
+> only what it changed. Reconciliation used to rebuild every role, re-inspect every
+> table and re-secure every routine on each change, all under the catalog lock, so
+> one registration could hold the lock for minutes and stop every other request.
+> Now a change:
+>
+> - re-inspects the policies of the tables it changed, plus the tables whose
+>   recorded cascade targets they affect;
+> - rebuilds only roles that are new or whose definition changed, and grants or
+>   revokes only the memberships and privileges that differ from the applied
+>   manifest;
+> - re-secures routines only when the owned schemas, routines or `PUBLIC` grants
+>   changed since the last sweep.
+>
+> The full sweep still runs when the runtime DataSource changes, at initialization
+> (the migration Job of every deployment) and from the admin repair action. Those
+> are when grants changed outside MetaTables are repaired, not on every catalog
+> change. MySQL and SQL Server keep the full sweep on every change.
+
+> Amendment (2026-10-09): [ADR 0022](0022-concurrent-requests-and-connection-reuse.md)
+> reuses login-role connections within a pod, only by the login role that opened them
+> and never through `SET ROLE`; no session state carries over from one use to the next.
+
 
 Date: 2026-09-29
 
@@ -299,8 +322,12 @@ and [MySQL implicit commits](https://dev.mysql.com/doc/refman/8.4/en/implicit-co
 - Physical table names become visible to explorer users.
 - Cascading foreign keys are allowed. Tables that reference a table never change
   who may write it.
-- Team membership reaches the database at the pace of the existing one-hour
-  platform-fact cache.
+- Team membership reaches the database on the caller's next query. Each SQL
+  admission compares the caller's current Teams with the ones its role was last
+  given and reconciles the roles first when they differ. A hosted caller's Teams
+  come from its signed assertion on every request
+  ([ADR 0017](0017-hosted-request-identity.md), 2026-10-05 amendment); only the
+  developer's own facts in Local and developer mode are cached for up to an hour.
 
 ## Implementation
 

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

@@ -0,0 +1,131 @@
+# ADR 0022: Concurrent requests per pod and reused database connections
+
+Status: Accepted.
+
+Implementation status: implemented on development. Unit tests pass; deployment
+verification, the MySQL and SQL Server container suites 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.dev46 → mainsequence_metatable-0.1.28}/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) | 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. |
 
 ## Agents
 

{mainsequence_metatable-0.1.27.dev46 → mainsequence_metatable-0.1.28}/docs/api/authentication-and-errors.md

@@ -73,7 +73,7 @@ DataSource and bootstrap state and returns `Cache-Control: no-store`.
 | 404 | Resource missing or not visible to the current actor. |
 | 409 | Lifecycle, capability, protection, reference, or physical-state conflict. |
 | 422 | Request/schema validation failure. |
-| 503 | Catalog, SDK verification/source access, physical connection, or an uncertain operation outcome is unavailable. |
+| 503 | Catalog, SDK verification/source access, physical connection, or an uncertain operation outcome is unavailable; or every database connection the API may hold stayed busy (`database_connections_busy`, `Retry-After: 1`). |
 
 Most framework errors use a `detail` field. Some domain operations provide a
 structured code and field information. Raw-query validation errors can be returned
@@ -87,4 +87,4 @@ An unknown physical commit outcome requires reconciliation, not a blind retry.
 
 ## Transfer errors
 
-Data routes return 413 for request/row/response byte limits, 408 for the overall transfer deadline, and 429 with `Retry-After: 1` when per-process admission capacity is exhausted. Existing SQL/driver errors can retain their engine-specific deadline codes and status. Upload conflicts use 409 and uncertainty can use 503. A limit enforced by schema validation can return 422. See [typed client exceptions and recovery](../client/bounded-transfers.md).
+Data routes return 413 for request/row/response byte limits, 408 for the overall transfer deadline, and 429 `transfer_capacity_exceeded` with `Retry-After: 1` when no data-request slot freed up within the request deadline (each API process runs `serving.concurrency` data requests at once). A 503 `database_connections_busy` with `Retry-After: 1` means every database connection stayed busy until the deadline. In both cases no statement ran, so any request, including SQL and writes, is safe to retry. Existing SQL/driver errors can retain their engine-specific deadline codes and status. Upload conflicts use 409 and uncertainty can use 503. A limit enforced by schema validation can return 422. See [typed client exceptions and recovery](../client/bounded-transfers.md).

{mainsequence_metatable-0.1.27.dev46 → mainsequence_metatable-0.1.28}/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.dev46 → mainsequence_metatable-0.1.28}/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.dev46 → mainsequence_metatable-0.1.28}/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