[tae898]

What this prepares

The deprecation path for the old PyPI project arcadedb-embedded, ready for the day the bindings move to ArcadeData/arcadedb-python. Decided 2026-10-25: arcadedb-embedded (the old JVM package) points to arcadedb, which is the NATIVE build; arcadedb-jvm is the JVM build and the warning names it for people who need it; arcadedb-embedded-native is archived: no further releases, no shim (its PyPI project has no files today), install arcadedb instead, whose import name is arcadedb, not arcadedb_native; arcadedb-native is reserved with no files and nothing to publish. This changes the runtime for pip users of arcadedb-embedded (it was the JVM build, arcadedb is the native build), and the warning, the README and MIGRATION.md say so plainly. Both arcadedb and arcadedb-jvm import as arcadedb. Nothing is published or archived by this PR, and the real package in bindings/python/src is untouched (no warning there: the benchmark harness and the mini stages keep importing arcadedb_embedded from the real package until the split).

This shim publishes only after the native arcadedb 26.11.1 FINAL exists. It pins arcadedb==26.11.1, and a 26.11.1.devN release does not satisfy that pin. This PR is parked: keep it a draft until then.

• bindings/python/deprecation/arcadedb-embedded/: a pure-Python shim distribution, version 26.11.1 (the final release of the name). It depends on exactly arcadedb==26.11.1 and forwards only extras that the native arcadedb wheel defines (numpy, arrow, pandas, polars; source: ArcadeData/arcadedb-python, branch native-two-dist, native/wheel/pyproject.toml): arrow, pandas and polars keep their names, the old vector extra (numpy) maps to numpy, and the old test, dev and examples extras are not forwarded because arcadedb does not have them. Its PyPI README says: deprecated, the package is now arcadedb (the native build, no JVM), for the JVM build install arcadedb-jvm, and links the Which package? page. import arcadedb_embedded emits one FutureWarning (visible by default, attributed to the importing line) in plain words: the package is now arcadedb, which is the native build and runs without a JVM; for the JVM build install arcadedb-jvm; the Which package? link; import arcadedb; the new repo and docs. The description, the README and the warning say that the runtime changes (this package was the JVM build). It then re-exports the new module: the names from arcadedb import * would bind, a module __getattr__ for everything else, and submodule aliasing through sys.modules plus a small meta-path finder so arcadedb_embedded.x.y is the same module object as arcadedb.x.y, also for submodules the new package has not imported yet (never a second copy loaded from disk).
• bindings/python/deprecation/build_shims.py: uv build of the shim (wheel and sdist, with the repo LICENSE in both), version checked with scripts/check_version.py first, --check-pypi for the live next-version check. It never uploads. TARGETS is the one table of where the old name points, EXTRAS the old-to-new extras mapping, NATIVE_EXTRAS the set of extras the native arcadedb wheel defines (with the source named in a comment), and IMPORT_NAME the one assumption behind them; check_target() runs before every build and refuses a shim whose pyproject.toml (name, description, dependencies, extras, Replaced by URL) or _NEW_DIST / _NEW_MODULE constants disagree with the table, one that forwards to an extra outside NATIVE_EXTRAS (or no longer covers it), and a warning that stops naming pip install arcadedb-jvm.
• bindings/python/tests/test_deprecation_shims.py (14 tests, about 1 s): builds the shim and checks the wheel is py3-none-any with only its import module, the pin on arcadedb and not arcadedb-jvm, the extras mapping and that the forwarded extras equal the native set, the Replaced by URL, the PyPI README (native build, arcadedb-jvm named, Which package? linked), the warning text (including the sentence that the runtime changes), that the migration texts say arcadedb-embedded-native is archived, that no native shim or arcadedb_native module comes back, that TARGETS holds the decided mapping and refuses a shim pointed at arcadedb-jvm, another module name, or an extra the native wheel lacks (or a native wheel that gains one), the version against the counting rule, and, against a stub arcadedb package, exactly one FutureWarning per process and on stderr under the default filters, attribute access, private names, already-imported, not-yet-imported and nested submodules, __spec__ of the shared module intact, ModuleNotFoundError and AttributeError for missing names. conftest.py leaves the file uncollected where deprecation/ is absent. A last test asserts the real package carries no warning.
• Deprecation notices at the top of the repo README.md and bindings/python/docs/index.md, and bindings/python/deprecation/MIGRATION.md (old to new install and import for the native and the JVM build, version mapping, what stays the same, what changes).
• Doc rows: testing.md, release.md (never push a 26.11.1 tag here, because release-python-packages.yml would build and publish the real wheels under arcadedb-embedded), bindings/python/AGENTS.md. The cutover order, the publish options and a ready workflow are in bindings/python/deprecation/README.md.

Merge timing

The notices say the bindings have moved, which is true only from the cutover day. Merge this PR once the native arcadedb 26.11.1 final is on PyPI (and arcadedb-jvm 26.11.1, which the warning names; step 1 below), not before: merging earlier announces the move ahead of ArcadeData.

Import name: what is assumed

arcadedb is assumed to provide the import name arcadedb (ArcadeData/arcadedb-python .notes/MIGRATION.md, packaging layout v3; both new packages share the module, and the native wheel's pyproject.toml packages src/arcadedb). It has no real release on PyPI yet (arcadedb and arcadedb-jvm are 0.0.1 placeholders), so this cannot be checked today. The assumption is in one place, IMPORT_NAME in build_shims.py, plus the _NEW_MODULE constant of the shim __init__.py; check_target() fails until the two agree. The Which package? URL in the warning (https://docs.arcadedb.com/arcadedb-python/which-package.html) follows from the Antora layout of ArcadeData/arcadedb-python and is not live until that site is published.

Verified locally

• pre-commit clean on the touched files. uv run --no-project --with pytest pytest --noconftest bindings/python/tests/test_deprecation_shims.py: 14 passed on Python 3.11, 3.12, 3.13 and 3.14. Two mutations of the shim's pyproject.toml (dependencies pointed at arcadedb-jvm; an extra the native wheel lacks) each turn the suite red; the file was restored afterwards.
• build_shims.py --check-pypi: 26.11.1 is the correct next version for arcadedb-embedded (12 published versions read, latest 26.10.2.post1). twine check passes on the wheel and the sdist.
• bandit==1.9.4 -c pyproject.toml -r bindings/python/deprecation --severity-level low --confidence-level low reports only the existing assert spec.loader is not None (B101) in build_shims.py.

Cutover checklist (do not run before the day)

• 1. Release the native arcadedb 26.11.1 FINAL (and arcadedb-jvm 26.11.1) from ArcadeData/arcadedb-python first (release-native.yml and release-jvm.yml, trusted publishing). Confirm pip download --no-deps arcadedb==26.11.1 works: the shim pins this exact version. If the first final arcadedb is only a 26.11.1.devN, do not publish the shim.
• 2. Merge this PR, then build and check from the merge commit: python3 bindings/python/deprecation/build_shims.py --out dist --check-pypi && uvx twine check dist/*. Do not push any 26.11.1 tag in this repository.
• 3. Publish the shim from this repository. Option A (trusted publishing): register a trusted publisher on the PyPI project arcadedb-embedded (repository humemai/arcadedb-embedded-python, workflow publish-deprecation-shims.yml, environment pypi), add the workflow given in bindings/python/deprecation/README.md to .github/workflows/ (and to FORK_GITHUB_ALLOWLIST in sync-upstream.sh if another sync still runs), dispatch it once with publish off to see the build and checks, then with publish on. Option B: uvx twine upload dist/* from a laptop with a project-scoped API token.
• 4. In a clean environment: pip install arcadedb-embedded==26.11.1 (it must install arcadedb, the native build, not arcadedb-jvm), then python -W default -c "import arcadedb_embedded" shows one FutureWarning that names arcadedb-jvm, and arcadedb_embedded.__version__ reads 26.11.1.
• 5. Update docs: redirect docs.humem.ai/arcadedb to https://docs.arcadedb.com/arcadedb-python/ and change the humem.ai software page and news post (handover note .notes/bench/HANDOVER-26111-HUMEMAI-SITE.md). Edit the "Planned changes" paragraph of the root AGENTS.md, which still says the move is not public.
• 6. After the benchmarks split to humemai/dbbench (DECISIONS benchmarks: land_stage.py's commit trailer names the model and session that run it #190, mid-November): archive humemai/arcadedb-embedded-python with a pointer to ArcadeData/arcadedb-python. Do nothing here before that split: the harness still imports the real package.
• 7. Archive the PyPI project arcadedb-embedded-native (it has no files today; there is no shim and no further release). arcadedb-native stays reserved with no files: no alias, nothing to publish.

Check before the cutover

• MIGRATION.md and the shim README say the API is unchanged by the move and that a few features differ between the native and the JVM build (Which package? lists them). Confirm against ArcadeData/arcadedb-python once it has the code, and fix those places if the new repo renames anything (the extras numpy, arrow, pandas, polars of arcadedb: NATIVE_EXTRAS in build_shims.py must match the wheel that is released).
• PyPI has arcadedb 0.0.1 and arcadedb-jvm 0.0.1 (placeholders that depend on an unpinned arcadedb-embedded). The new releases supersede both, so no yank is needed.
• The shim's FutureWarning is the only warning; the earlier releases of arcadedb-embedded stay on PyPI untouched.

🤖 Generated with Claude Code

[tae898]

Fixes finding F1 of the migration runbook (commit d5392c1): the old arcadedb-embedded-native wheel contains only the package arcadedb_native (checked on 26.10.2.dev1 from PyPI), but the shim shipped only arcadedb_embedded, so import arcadedb_native after an upgrade raised a bare ModuleNotFoundError. The native shim now ships arcadedb_native as well (and keeps arcadedb_embedded), with the same shared body, so it warns once and re-exports arcadedb. The warning now names the module that was imported. The alias finder is keyed on (new module, old name) so both old names work in one process.

Checks run locally: tests/test_deprecation_shims.py (16 tests) passes on Python 3.11 and 3.14 and the six new or changed tests fail on the previous shims with ModuleNotFoundError: No module named 'arcadedb_native'; build_shims.py builds both wheels (the native wheel lists both modules, the other lists only arcadedb_embedded); pre-commit (black, isort) and bandit on the changed files are clean. Not run: an install against the real arcadedb-native 26.11.1, which is not on PyPI yet (the tests use a stub arcadedb).

This PR stays parked.

[tae898]

Pushed 2d6bbaf: the shims now follow the final package names. PyPI arcadedb is the native package and arcadedb-jvm the JVM package, so arcadedb-embedded (old JVM) points to arcadedb-jvm and arcadedb-embedded-native (old native) points to arcadedb.

• Dependencies and metadata: arcadedb-embedded requires arcadedb-jvm==26.11.1 (extras forwarded to arcadedb-jvm), arcadedb-embedded-native requires arcadedb==26.11.1; descriptions, the Replaced by URLs, both PyPI READMEs, MIGRATION.md, deprecation/README.md (cutover steps) and the notices in README.md, docs/index.md, release.md and testing.md say the same. The JVM shim's warning reads pip install arcadedb-jvm, says it is the same JVM build and that arcadedb is the native build.
• Import-name assumption, in one place (IMPORT_NAME in build_shims.py, plus _NEW_MODULE in the shim __init__.py files): both arcadedb and arcadedb-jvm import as arcadedb. This follows "Packaging layout v2" in ArcadeData/arcadedb-python .notes/MIGRATION.md; neither has a real release yet, so it cannot be checked. check_target() fails the build when the table and the shim files disagree.
• Tests: 22 passed (16 before), including the JVM shim requires arcadedb-jvm and not arcadedb, the native shim requires arcadedb, and build_shims.py refuses a shim pointed at the other package. pre-commit clean, build_shims.py --check-pypi and twine check pass.
• Found while checking PyPI: arcadedb-embedded-native and arcadedb-native answer 404 today (the notes list arcadedb-embedded-native 26.10.2.dev0/dev1 as published). If they were deleted, the native shim README line about the previews staying on PyPI is wrong; flagged in the PR body, not changed.

The PR stays open and not merged, draft state unchanged.

[tae898]

Superseded: the earlier layout-v2 comment above (arcadedb-embedded to arcadedb-jvm, arcadedb-embedded-native to arcadedb) no longer applies. Layout v3 is pushed (f038171, f759969) and the PR body is rewritten for it: arcadedb-embedded is the only shim and requires arcadedb==26.11.1 (the native build; arcadedb-jvm is named for JVM users), arcadedb-embedded-native is archived with no shim, and the shim forwards only the extras the native wheel defines (numpy, arrow, pandas, polars; checked by build_shims.py). Both packages import as arcadedb. The PR publishes only after the native arcadedb 26.11.1 final exists.