ms-markets 2.2.6.dev17__tar.gz → 2.2.6.dev18__tar.gz

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/.agents/skills/ms_markets/platform/metatable_migrations/SKILL.md

@@ -69,6 +69,15 @@ ms-markets schema is migrated only by the ms-markets deployment's
 `migrate-markets` Job. A project that installs ms-markets to read or write its
 tables does not apply `msm_migrations:migration`; its own migration Job applies
 only its own providers. Do not migrate at application startup.
+
+Required in every Environment: the `migrate-markets` Job and the `markets-api`
+release run as their own workload Users, which have no MetaTables grants until an
+Organization admin runs `scripts/bootstrap_metatables_access.py` from a checkout
+of the branch deployed there. Without it the Job fails, for example with
+`422 MetaTable is not editable`, and the API is not deployed. Do not work around a
+failed migration by changing revisions or table definitions. Check the Job run
+logs, then have an admin run the bootstrap. `docs/releasing.md` ("MetaTables access
+in each Environment") has the steps.
 The MetaTables API needs no provider code, allowlist, or
 `application_migration_providers` alias. Keep the provider package, namespace,
 model registry, version-table binding, revision IDs, and applied revision

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project follows versioned releases.
 
 ## [Unreleased]
 
+### Added
+
+- `scripts/bootstrap_metatables_access.py` gives the deployment's workload Users
+  Writer on the `mainsequence.markets` MetaTables namespace in one Environment, for
+  an Organization admin to run once from a checkout of `development` or `main`.
+  It creates the Team `ms-markets-<environment>` from the checkout's Environment
+  name, adds the migration Job's and FastAPI release's workload Users from the
+  deployment workflow, creates the namespace if it is missing and grants the Team
+  Writer on it. Every other grant is kept, and `--dry-run` only reports. Without
+  this grant the migration Job could not register tables. In `development` it got
+  `422 MetaTable is not editable` on `msm.alembic_version`, which a previous runtime
+  identity had registered. See [MetaTables#43](https://github.com/mainsequence-projects/MetaTables/issues/43)
+  and "MetaTables access in each Environment" in `docs/releasing.md`.
+
 ### Changed
 
 - Requires `mainsequence>=9.0.19,<10` and `mainsequence-metatable>=0.1.26,<0.2`;

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/PKG-INFO

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

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/docs/fast_api/v1/index.md

@@ -155,6 +155,12 @@ image, and `deploy_api` deploys the API with `needs: [migrate]`. A failed
 migration blocks the rollout and the previous release keeps serving; see
 [Hosted Deployments](../../knowledge/msm/migrations/index.md#hosted-deployments).
 
+!!! warning "Required before deploying to an Environment"
+    The Job and the API run as their own workload Users. They can't migrate or
+    use the ms-markets tables until an Organization admin runs
+    `scripts/bootstrap_metatables_access.py` for that Environment; see
+    [MetaTables access in each Environment](../../releasing.md#metatables-access-in-each-environment).
+
 Publish repository changes with a plain `git push` of the tracked branch; the
 workflow files decide what deploys. The tracked `main` branch changes only through
 release pull requests from `development`; see [Releasing](../../releasing.md). Since Main Sequence SDK 9.0.5,

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/docs/knowledge/msm/migrations/index.md

@@ -60,6 +60,13 @@ This repository's `.mainsequence/workflows/ms-markets-api.yaml` builds the image
 at head is left unchanged, and a failure blocks the API rollout while the
 previous release keeps serving.
 
+!!! warning "Required: MetaTables access for the deployment"
+    The migration Job runs as its own workload User, which has no MetaTables
+    grants until an Organization admin runs `scripts/bootstrap_metatables_access.py`
+    for that Environment. Until then every hosted migration fails and the API is not
+    deployed; see
+    [MetaTables access in each Environment](../../../releasing.md#metatables-access-in-each-environment).
+
 The ms-markets schema is owned and migrated only by this repository's
 deployment. An application that installs ms-markets to read or write its tables
 does not apply `msm_migrations:migration`; its own migration Job, if it has one,

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/docs/releasing.md

@@ -129,6 +129,60 @@ rebuilds the image, runs the `migrate-markets` Job and redeploys the API. Pushes
 `main` happen only through release merges, so the `main` deployment follows
 stable releases.
 
+### MetaTables access in each Environment
+
+!!! warning "Required in every Environment"
+    An Organization admin must run `scripts/bootstrap_metatables_access.py` for an
+    Environment before ms-markets can be deployed there. Without it:
+
+    - the `migrate-markets` Job fails, for example with
+      `422 MetaTable is not editable` or
+      `Writer access to the destination namespace is required`;
+    - the API rollout is blocked and no release becomes active.
+
+    Run it before the first deployment to a new Environment, and again whenever
+    the platform recreates the Job or the release.
+
+The `migrate-markets` Job and the `markets-api` release run as their own workload
+Users, which start with no grants. The workflow gives both `view` on the MetaTables
+repository (`access.branches`), so they can find the Environment's MetaTables API.
+A workflow cannot grant MetaTables table access, so an Organization admin runs
+`scripts/bootstrap_metatables_access.py` once per Environment. Run it from a
+checkout of the branch deployed there: `development` for the development
+Environment, `main` for Production.
+
+```bash
+uv run --frozen --all-extras python -m scripts.bootstrap_metatables_access --dry-run
+uv run --frozen --all-extras python -m scripts.bootstrap_metatables_access
+```
+
+The script names the Team after the checkout's Environment (`ms-markets-development`,
+`ms-markets-production`). It:
+
+- creates the Team if it doesn't exist;
+- adds the workload Users of the Job and release declared in the workflow;
+- creates the `mainsequence.markets` namespace if it is missing;
+- grants the Team Writer on the namespace.
+
+Tables in that namespace inherit the grant, including the ones the migration
+registers later. Once `msm.alembic_version` is registered, the script checks each
+workload User's effective access to it.
+
+Re-running the script changes only what is missing. Run it again whenever the
+platform recreates the Job or the release, because the new workload User is not
+in the Team.
+
+A workload User exists only after the workload's first deployment. In an
+Environment where the Job has not run yet:
+
+1. Run the script, then push. The Job's first run fails, because its workload User
+   is not in the Team yet.
+2. Run the script again.
+3. Run the Job with `mainsequence code-repository jobs run <JOB_UID>`.
+
+The API rolls out on the next push to the branch, because the CLI cannot retry a
+blocked deployment.
+
 ## Failure recovery
 
 Before upload, failed checks publish nothing. Correct the problem on

{ms_markets-2.2.6.dev17 → ms_markets-2.2.6.dev18}/pyproject.toml

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

ms_markets-2.2.6.dev18/tests/msm/maintenance/test_bootstrap_metatables_access.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import pytest
+
+from scripts.bootstrap_metatables_access import (
+    DeploymentWorkloads,
+    deployment_workloads,
+    team_name,
+    with_team_writer,
+)
+
+TEAM = "4d2b8f6e-1c3a-4e5f-9b7d-0a2c4e6f8b19"
+OTHER_TEAM = "7a9c1e3f-5b2d-4f6a-8c0e-2d4f6a8c0e31"
+USER = "2e4a6c8e-0b1d-4f3a-9c5e-7d9f1b3d5f42"
+
+
+@pytest.mark.parametrize(
+    ("environment", "expected"),
+    [
+        ("development", "ms-markets-development"),
+        ("Production", "ms-markets-production"),
+        (" Staging EU ", "ms-markets-staging-eu"),
+    ],
+)
+def test_team_name_is_derived_from_the_environment(environment: str, expected: str) -> None:
+    assert team_name(environment) == expected
+
+
+def test_team_name_rejects_an_environment_without_letters_or_digits() -> None:
+    with pytest.raises(ValueError, match="empty Team name"):
+        team_name(" - ")
+
+
+def test_deployment_workloads_come_from_the_deployment_workflow() -> None:
+    assert deployment_workloads() == DeploymentWorkloads(
+        job_name="ms-markets migrations",
+        release_name="api",
+    )
+
+
+def test_with_team_writer_adds_the_team_and_keeps_other_grants() -> None:
+    assignments = {
+        "view": {"users": [USER], "teams": [OTHER_TEAM]},
+        "edit": {"users": [USER], "teams": []},
+    }
+
+    assert with_team_writer(assignments, TEAM) == {
+        "view": {"users": [USER], "teams": sorted([OTHER_TEAM, TEAM])},
+        "edit": {"users": [USER], "teams": [TEAM]},
+    }
+
+
+def test_with_team_writer_promotes_a_reader_team() -> None:
+    assignments = {"view": {"users": [], "teams": [TEAM]}, "edit": {"users": [], "teams": []}}
+
+    assert with_team_writer(assignments, TEAM) == {
+        "view": {"users": [], "teams": [TEAM]},
+        "edit": {"users": [], "teams": [TEAM]},
+    }
+
+
+def test_with_team_writer_changes_nothing_when_the_team_is_already_writer() -> None:
+    assignments = {"view": {"users": [], "teams": [TEAM]}, "edit": {"users": [], "teams": [TEAM]}}
+
+    assert with_team_writer(assignments, TEAM) is None