mainsequence-metatable 0.1.8.dev12__tar.gz → 0.1.8.dev14__tar.gz

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/.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.dev12 → mainsequence_metatable-0.1.8.dev14}/.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.dev12/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.8.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.8.dev12
+Version: 0.1.8.dev14
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -14,7 +14,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mainsequence[server]<10,>=9.0.1
+Requires-Dist: mainsequence[server]<10,>=9.0.4
 Requires-Dist: alembic<2,>=1.18
 Requires-Dist: cachetools
 Requires-Dist: cryptography<51,>=46

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/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.dev12 → mainsequence_metatable-0.1.8.dev14}/docs/client/installation-and-connection.md

@@ -11,7 +11,7 @@ require running another service locally.
 Install in your application's Python environment on macOS or Linux:
 
 ```bash
-python -m pip install "mainsequence-metatable==0.1.5" "mainsequence[server]==9.0.1"
+python -m pip install "mainsequence-metatable==0.1.8" "mainsequence[server]==9.0.4"
 mainsequence login
 metatables init --local
 metatables serve --local --admin
@@ -19,11 +19,11 @@ metatables serve --local --admin
 
 Run from an application Git checkout with a commit and an `origin` remote. Python
 3.13+ is required. Admin also needs Node.js 22.12+ (or 20.19+) and npm. The package
-requires published `mainsequence[server]>=9.0.1,<10`; no SDK checkout is needed.
-The next stable release is MetaTables 0.1.5, paired with published SDK 9.0.1.
+requires published `mainsequence[server]>=9.0.4,<10`; no SDK checkout is needed.
+The next stable release is MetaTables 0.1.8, paired with published SDK 9.0.4.
 The pinned command above applies after that stable release is published; before
-then, install the exact `0.1.5.devN` artifact produced by the development publishing
-workflow alongside `mainsequence[server]==9.0.1`. SDK 8 is outside this release's
+then, install the exact `0.1.8.devN` artifact produced by the development publishing
+workflow alongside `mainsequence[server]==9.0.4`. SDK 8 is outside this release's
 dependency range.
 `python -m metatables.sdk_compat` checks the required SDK interfaces without network
 requests. Local SQLite uses the standard library driver.

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/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.dev12 → mainsequence_metatable-0.1.8.dev14}/docs/contributing/releasing.md

@@ -42,10 +42,13 @@ substitute for the published SDK in a release. The selected SDK artifact must
 provide ordinary `Secret.get_by_uid`, independent Git source context, and
 `CallerAssertionVerifier.from_environment` through its `server` extra.
 
-The next MetaTables stable release is `0.1.5`; its supported SDK range is
-`mainsequence[server]>=9.0.1,<10`. Development builds use `0.1.5.devN`.
-The minimum and lockfile now select published SDK `9.0.1`, which supplies those
-interfaces. Runtime compatibility is verified manually with the published artifact;
+The next MetaTables stable release is `0.1.8`; its supported SDK range is
+`mainsequence[server]>=9.0.4,<10`. Development builds use `0.1.8.devN`.
+The minimum and lockfile now select published SDK `9.0.4`, which supplies those
+interfaces and is the first SDK whose caller-assertion verifier accepts the
+platform's EdDSA (Ed25519) caller assertions. Earlier SDKs verify only RS256, so a
+hosted API built with them cannot authenticate platform callers.
+Runtime compatibility is verified manually with the published artifact;
 package/static CI does not establish runtime compatibility. When changing the SDK
 minimum, update it in `pyproject.toml`, then run:
 

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/docs/contributing/testing.md

@@ -104,7 +104,7 @@ The distribution check requires exactly one wheel and one sdist in `dist/` and
 compares packaged Python modules with current source. Also test importing the
 wheel in a fresh environment with the compatible published SDK installed, and verify
 both catalog migrations and application revision templates are packaged.
-The package requires published SDK 9.0.1 or newer within its declared major version.
+The package requires published SDK 9.0.4 or newer within its declared major version.
 
 Run the installed-wheel smoke tests manually from outside the checkout, using a
 fresh virtual environment with the compatible SDK and built MetaTables wheel:

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.8.dev12"
+version = "0.1.8.dev14"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -18,7 +18,7 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 dependencies = [
-  "mainsequence[server]>=9.0.1,<10",
+  "mainsequence[server]>=9.0.4,<10",
   "alembic>=1.18,<2",
   "cachetools",
   "cryptography>=46,<51",

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.8.dev12
+Version: 0.1.8.dev14
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -14,7 +14,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mainsequence[server]<10,>=9.0.1
+Requires-Dist: mainsequence[server]<10,>=9.0.4
 Requires-Dist: alembic<2,>=1.18
 Requires-Dist: cachetools
 Requires-Dist: cryptography<51,>=46

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/src/mainsequence_metatable.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mainsequence[server]<10,>=9.0.1
+mainsequence[server]<10,>=9.0.4
 alembic<2,>=1.18
 cachetools
 cryptography<51,>=46

{mainsequence_metatable-0.1.8.dev12 → mainsequence_metatable-0.1.8.dev14}/uv.lock

@@ -599,7 +599,7 @@ wheels = [
 
 [[package]]
 name = "mainsequence"
-version = "9.0.1"
+version = "9.0.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cachetools" },
@@ -620,9 +620,9 @@ dependencies = [
     { name = "typer" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/8a/73/612ace9e27a13bab3ef85bec4759da8c4b7098bc9fa7c358964925f74e45/mainsequence-9.0.1.tar.gz", hash = "sha256:8d29962d277564dc254038923e968ec586eee96a8496efbc66e39f51b1189305", size = 352217, upload-time = "2026-10-01T08:49:58.803Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7f/e4/22e6207f49aa3d770a7f8b9fbc5b2cbedeb5ad456226190dfa31360350b3/mainsequence-9.0.4.tar.gz", hash = "sha256:e79595f04984ccd59813474f0c42d6be78cd2c498569efa7bfffb5afe93f34de", size = 361627, upload-time = "2026-10-02T14:10:13.982Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ea/93/d9348e412adb4c9b6f1cf541b6a93bfa7d23e8af3892a56b0800f2a92ee9/mainsequence-9.0.1-py3-none-any.whl", hash = "sha256:8f584055df38083a953b6434b1f7fe34c31ff8db731c6146949dcc711e3d9ef1", size = 247586, upload-time = "2026-10-01T08:49:57.244Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/8f/53ebebe3549d1750cd9b29d73793080f7951ca152ce3ca71e8e61c8ac56d/mainsequence-9.0.4-py3-none-any.whl", hash = "sha256:405ae7ccd683a1e760bdad701b44a6da0a8f904f7a2f93fd57158a2336aaade4", size = 255273, upload-time = "2026-10-02T14:10:12.605Z" },
 ]
 
 [package.optional-dependencies]
@@ -687,7 +687,7 @@ requires-dist = [
     { name = "fastapi", specifier = ">=0.110,<1" },
     { name = "httpx", specifier = ">=0.28,<1" },
     { name = "keyring", specifier = ">=25,<26" },
-    { name = "mainsequence", extras = ["server"], specifier = ">=9.0.1,<10" },
+    { name = "mainsequence", extras = ["server"], specifier = ">=9.0.4,<10" },
     { name = "mkdocs", marker = "extra == 'docs'", specifier = ">=1.6,<2" },
     { name = "numpy" },
     { name = "opentelemetry-api" },