mainsequence-metatable 0.1.8.dev11__tar.gz → 0.1.8.dev13__tar.gz

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/.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, scaffolding, revision authoring, client-side execution, 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, client-side execution, and reservation or finalization failures. Excludes API catalog migrations, client-library implementation, API/server changes and repository tooling."
 ---
 
 # MetaTables client application migrations
@@ -55,9 +55,11 @@ are not application-provider revisions.
 1. Define the SQLAlchemy models with stable, application-prefixed physical names.
 2. Identify one provider module, migration namespace, target `MetaData`, model
    registry, and prefixed Alembic version-table binding.
-3. Keep provider scope explicit. Do not scan all imported models or installed
+3. Choose a provider module name that no other installed package uses (see
+   [Provider placement](#provider-placement)).
+4. Keep provider scope explicit. Do not scan all imported models or installed
    packages.
-4. Scaffold only when the application has no provider yet:
+5. Scaffold only when the application has no provider yet:
 
    ```bash
    metatables migrations scaffold \
@@ -65,13 +67,17 @@ are not application-provider revisions.
      --module ledger.migrations \
      --namespace ledger \
      --base ledger.tables:Base \
-     --metadata ledger.tables:Base.metadata
+     --metadata ledger.tables:Base.metadata \
+     --alembic-version-table-name ledger__alembic_version
    ```
 
-5. Edit the generated `registry.py` so it returns exactly the models owned by
+   Always pass `--module` and `--alembic-version-table-name`. Without them the
+   scaffold creates a top-level `migrations` module and the shared
+   `public.alembic_version` table.
+6. Edit the generated `registry.py` so it returns exactly the models owned by
    that migration stream. Scaffolding alone selects no models and creates no
    tables.
-6. Create and review an Alembic revision (defaults to autogeneration):
+7. Create and review an Alembic revision (defaults to autogeneration):
 
    ```bash
    metatables migrations revision \
@@ -83,6 +89,27 @@ Use `--source-root` and `--code-repository-root` when the application does not
 use the default `src/` layout. Keep applied revisions immutable; add a new
 revision for every later schema change.
 
+## Provider placement
+
+The application decides where its provider lives. The module name, however,
+must not collide with any other package installed in the same environment. A
+library's provider ships in its wheel and runs inside its consumers'
+environments, next to providers from other libraries. When two packages install
+the same top-level module, such as `migrations`, the later install overwrites
+the earlier one's files. Imports then load the wrong provider, and Alembic reads
+the wrong revisions.
+
+- Place the provider under an import package the application owns, for example
+  `ledger.migrations`, or give it a name specific to the application, for example
+  `ledger_migrations`.
+- Point `script_location` and `version_location_prefix` at that module. The
+  scaffold derives both from `--module`. A hand-written
+  `build_metatable_migration_provider` call must pass both, because the builder
+  defaults to `migrations:`.
+- Before releasing a package that others install, list the built wheel with
+  `python -m zipfile -l <wheel>`. Its top-level entries must be packages the
+  application owns.
+
 ## Execute with the environment connection
 
 After verifying the intended runtime, use the application's provider reference:
@@ -132,6 +159,13 @@ Read `docs/operations/recovery-and-observability.md`.
 
 - If provider loading fails, verify the import path, model registry, metadata,
   version-table binding, and installed `metatables` version.
+- If the provider loads another package's code or revisions, find the file that
+  its module resolves to with
+  `python -c "import importlib.util as u; print(u.find_spec('migrations').origin)"`,
+  replacing `migrations` with the provider module. A shared module name means
+  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 Alembic succeeds but finalization fails, physical DDL may already be
@@ -145,6 +179,6 @@ Read `docs/operations/recovery-and-observability.md`.
 
 ## Validation
 
-Verify provider scope, revision content, the selected environment connection,
-repeat execution, and final active bindings. Report separately what was checked
+Verify provider scope and placement, revision content, the selected environment
+connection, repeat execution, and final active bindings. Report separately what was checked
 offline and what was exercised against a configured API.

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/.agents/skills/client/metatables-upgrade-legacy-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metatables-upgrade-legacy-app
-description: "Upgrade consuming applications from MainSequence 8.x MetaTables or older extracted clients to the installed metatables package. Use for legacy imports, removed SQL scopes, repository compilers and application migration-provider integration. Excludes MetaTables client/API implementation and ordinary schema revision authoring."
+description: "Upgrade consuming applications from MainSequence 8.x MetaTables or older extracted clients to the installed metatables package. Use for legacy imports, removed SQL scopes, repository compilers, application migration-provider integration and provider modules that collide with other installed packages. Excludes MetaTables client/API implementation and ordinary schema revision authoring."
 ---
 
 # Upgrade a legacy MetaTables application
@@ -58,11 +58,33 @@ Read `docs/client/query-and-mutate.md` for current query behavior and
 
 ## Upgrade application migration integration
 
-Keep the existing provider package, namespace, model registry, version-table
-binding and applied revision history. Update bootstrap/import wiring to the
-installed client's public migration interfaces. Do not scaffold a replacement
+Keep the existing provider `package=` value, namespace, model registry,
+version-table binding and applied revision history. Update bootstrap/import wiring
+to the installed client's public migration interfaces. Do not scaffold a replacement
 provider, rewrite applied history or stamp the database to bypass an upgrade issue.
 
+### Move a provider whose module name collides
+
+A provider installed under a generic top-level module, such as `migrations`,
+shares files and imports with every other installed package that chose the same
+name. Move it under a module the application owns, for example `ledger.migrations`
+or `ledger_migrations`:
+
+- Move the provider package with its `env.py`, `script.py.mako` and `versions/`
+  tree.
+- Update `script_location`, `version_location_prefix`, the `env.py` import,
+  imports inside the provider, packaging configuration, and every provider
+  reference in code, scripts and jobs.
+- Keep `package=`, `migration_namespace`, the version-table binding and the
+  revision files unchanged. The catalog binds provider tables to
+  `package:namespace` and rejects a reservation from a different key. Alembic
+  stores only revision IDs, so the module path can change.
+- Do not ship a module under the old name. A forwarding module would keep the
+  file collision.
+
+Then confirm that `migrations current` reports the same revision as before the
+move, and that the built wheel no longer installs the old top-level name.
+
 Providers load in the application process from Python references such as
 `ledger.migrations:migration`. The client executes Alembic with the environment
 connection; the API handles authorization, reservations and finalization. The

{mainsequence_metatable-0.1.8.dev11/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.8.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.8.dev11
+Version: 0.1.8.dev13
 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.8.dev11 → mainsequence_metatable-0.1.8.dev13}/docs/adr/api/0014-main-sequence-release-jobs-and-production-migrations.md

@@ -40,7 +40,11 @@ The Job, `jobs/migrate_system.py`, runs `metatables runtime upgrade`:
    verification. A runtime already at the current revision is left untouched.
 
 The command acts only on an active runtime. With no API deployment or no active
-runtime yet, it succeeds without DDL. A non-admin identity or an unreadable
+runtime yet, it succeeds without DDL. The Environment's DataSource is set
+through the deployed API, so if it is set the command migrates when necessary;
+if it is not, it skips migrations and the API deploys. An API release that the
+workflow created but has never deployed counts as no API deployment, so the
+first run deploys the API. A non-admin identity or an unreadable
 context fails before DDL. When it registers the runtime DataSource, it records
 the Job identity's user UID as the creator.
 

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/docs/client/define-and-migrate-tables.md

@@ -34,7 +34,8 @@ metatables migrations scaffold \
   --module ledger.migrations \
   --namespace ledger \
   --base ledger.tables:Base \
-  --metadata ledger.tables:Base.metadata
+  --metadata ledger.tables:Base.metadata \
+  --alembic-version-table-name ledger__alembic_version
 ```
 
 The scaffold creates a provider, model registry, Alembic environment, revision
@@ -43,6 +44,24 @@ template, and versions directory under the chosen source root. Edit its
 creation alone does not select all imported models or migrate a database.
 Use `--source-root` and `--code-repository-root` if your layout differs from `src/`.
 
+### Provider placement
+
+Where the provider lives is the application's choice. Its module name, however,
+must be unique in every environment that installs the package. A library's
+provider ships in its wheel and runs next to providers from other libraries. If
+two packages install the same top-level module, such as `migrations`, the later
+install overwrites the earlier one's files and imports load the wrong provider.
+Pass `--module` with a module the application owns, such as `ledger.migrations`
+or `ledger_migrations`. Without it, the scaffold creates a top-level `migrations`
+module. A hand-written `build_metatable_migration_provider` call must set
+`script_location` and `version_location_prefix` to that module, because both
+default to `migrations:`. Before releasing, list the built wheel with
+`python -m zipfile -l <wheel>` and check that every top-level entry belongs to the
+application.
+
+Pass `--alembic-version-table-name` as well. The default `public.alembic_version`
+would be shared by every provider on the same DataSource that keeps the default.
+
 ## Author and execute in the application
 
 Use the same Python provider reference for authoring and execution:

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/docs/client/upgrade-legacy-app.md

@@ -135,9 +135,20 @@ See [query and mutate](query-and-mutate.md) for engine-specific behavior.
 
 Application providers and Alembic execution belong to the application. Update
 provider/bootstrap imports to the target client's public migration interfaces,
-and retain the existing provider package, namespace, model registry, version-table
-binding, revision IDs and applied history. Do not scaffold a replacement provider
-or stamp an existing database merely to make the upgrade pass.
+and retain the existing provider `package=` value, namespace, model registry,
+version-table binding, revision IDs and applied history. Do not scaffold a
+replacement provider or stamp an existing database merely to make the upgrade pass.
+
+If the provider is installed under a generic top-level module such as
+`migrations`, move it under a module the application owns. Other installed
+packages that use the same name overwrite its files. Move the package with its
+`env.py`, `script.py.mako` and `versions/` tree. Update `script_location`,
+`version_location_prefix`, the imports, the packaging configuration and every
+provider reference. Keep `package=`, `migration_namespace`, the version-table
+binding and the revision files unchanged. The catalog binds provider tables to
+`package:namespace` and rejects a reservation from a different key. Alembic
+stores only revision IDs, so the module path can change. Do not ship a
+forwarding module under the old name, because it would keep the file collision.
 
 The application loads its provider locally. The API handles authorization,
 reservations, connection resolution and finalization. The client runs Alembic

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/pyproject.toml

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

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.8.dev11
+Version: 0.1.8.dev13
 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.8.dev11 → mainsequence_metatable-0.1.8.dev13}/src/metatables/endpoint.py

@@ -153,6 +153,13 @@ def _release_access(release, *, timeout: float = 30.0):
             _validate_url(access["rpc_url"])
             return access
         if admission.state != "waking":
+            if result.routing.active_revision_uid is None:
+                # The deployment workflow creates the release before its first
+                # rollout. The runtime DataSource is set through a deployed
+                # API's Settings, so a release that never served has none yet.
+                raise ApiNotDeployedError(
+                    "The MetaTables API has not been deployed in this Environment yet, "
+                    "so no runtime DataSource has been set.")
             raise ApiResolutionError("MetaTables deployment is unavailable; check its deployment status.")
         delay = max(0.05, (admission.retry_after_ms or 250) / 1000)
         time.sleep(min(delay, max(0, deadline - time.monotonic())))

{mainsequence_metatable-0.1.8.dev11 → mainsequence_metatable-0.1.8.dev13}/tests/e2e/test_api_endpoint.py

@@ -45,7 +45,7 @@ def platform(monkeypatch):
     branches = {"api-branch": "development"}
     access = SimpleNamespace(
         resource_release_uid=release.uid, release_kind="fastapi",
-        routing=SimpleNamespace(state="routable"),
+        routing=SimpleNamespace(state="routable", active_revision_uid="revision-uid"),
         runtime_access=SimpleNamespace(state="ready", can_request=True, retry_after_ms=None),
         access={"rpc_url": "https://release.test/api/", "mode": "token", "token": "release-credential"},
     )
@@ -303,6 +303,27 @@ def test_unavailable_and_mismatched_release_are_not_cached(platform):
         endpoint.get_api_url()
 
 
+def test_release_that_never_served_is_not_deployed(platform):
+    # The deployment workflow creates the release before its first rollout.
+    platform.access.runtime_access.state = "unavailable"
+    platform.access.routing = SimpleNamespace(state="unavailable", active_revision_uid=None)
+    with pytest.raises(endpoint.ApiNotDeployedError, match="no runtime DataSource has been set"):
+        endpoint.get_api_url()
+
+
+def test_upgrade_skips_without_ddl_before_the_first_rollout(platform, monkeypatch):
+    import metatables.api.app.bootstrap as bootstrap
+    from metatables.cli import app as cli
+
+    platform.access.runtime_access.state = "unavailable"
+    platform.access.routing = SimpleNamespace(state="unavailable", active_revision_uid=None)
+    monkeypatch.setattr(bootstrap, "upgrade_selected_runtime",
+                        lambda *_: pytest.fail("the upgrade must not touch the database"))
+    result = cli._upgrade_runtime()
+    assert result["status"] == "skipped"
+    assert "no runtime DataSource has been set" in result["reason"]
+
+
 def test_waking_respects_retry_hint_and_does_not_repeat_name_lookup(platform, monkeypatch):
     platform.access.runtime_access.state = 'waking'
     platform.access.runtime_access.retry_after_ms = 500