Skip to content

chore: #1630 and #919 follow-ups (staging failure test, admin retired-type location, removed-import scan) - #1658

Open
Oaklight wants to merge 3 commits into
masterfrom
chore/1630-919-followups
Open

Oaklight wants to merge 3 commits into
masterfrom
chore/1630-919-followups

Conversation

@Oaklight

@Oaklight Oaklight commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Follow-ups for #1630 (non-blocking items) and #919 (open items), in one PR. It does not touch the files of the parallel refactor/contracts-home PR (#1657 C1–C6), and it changes no llm_rosetta import line.

#1630, staging_registry failure path (test only). New tests/test_staging_registry_failure.py. The existing failure test stayed green when the restore skipped the clear() (an entry the staged block added leaked into the live model-list table) and when only Exception was caught (a KeyboardInterrupt left the staged view in place). The new tests compare the whole table and registry with their state before the block, raise a test-only exception class and assert the caller receives that same object, and cover a BaseException. Mutation check on shims/provider_shim.py (restored with cp from a saved copy): 5 mutations, each one fails at least one new test; 2 of them (skip the clear, except Exception) do not fail the old test.

#1630, merge_connection docstring: skipped. The function is defined in shims/providers/_manifest.py and re-exported from api.py; both belong to the parallel PR.

#919, admin declared_model_type without a location. admin/routes/config/payload.py passes models.<name> to declared_model_type, and get_config turns a RetiredConfigName into a 500 whose error reads Failed to read config: <file>: <json path>: <message>, with path and where as separate fields (the shape the loader reports). Before, a models entry edited by hand after startup to embedding / decision failed the request with no location. Tests: tests/gateway/test_admin_retired_model_type.py.

#919, removed import paths name their replacement. Core retired_names gains RETIRED_MODULES, a data table next to RETIRED_NAMES: the module paths #919 removed (compat converter packages, converters.base.helpers / .tools facades, provider_names, shims.transforms) and the #1657 moves (transforms → contracts.transform, shims.auth_exchange → contracts.auth, shims.quota_probe → contracts.quota, routing → contracts.routing, observability.usage → contracts.usage, capabilities with no public replacement). llm-rosetta-migrate --scan reads the import statements of .py files (with ast, including from pkg import submodule) and reports an import of a listed path as an import item naming the replacement; it counts toward exit code 1. A row is reported only when its path does not resolve in the installed core (find_spec is None), so the six #1657 paths, which still exist on master, are silent today and start being reported once the parallel PR deletes them. A scan rule rather than a sys.meta_path finder: a finder that raises from find_spec turns importlib.util.find_spec(<removed>) from None into an exception, which repo tests (and the gateway boundary test) rely on; a finder returning a spec with a raising loader makes find_spec non-None, which is worse. Details in the commit message. Tests: tests/test_retired_modules.py, tests/gateway/test_migrate_scan_imports.py (removed path, still-present path both synthetic and over the real table).

#919, fix_orphaned_tool_calls in the docs. Fixed on the docs branches (guide/converters.md and guide/compatibility.md, en and zh): the direct-use example now uses normalize_tool_pairing and a converter round trip (the example was run against this tree), and the placeholder text matches UNANSWERED_TOOL_CALL.

Changelog. Every PR merged on 2026-11-20 already has an [Unreleased] entry except #1635, which moved a private module and says it needs none. Entries for this PR are added on both docs branches.

Verification: make lint passes. Full pytest tests/ --ignore=tests/integration -p no:cacheprovider --no-cov, run locally (conda env llm-rosetta, PYTHONPATH set to this worktree's two src roots): 11293 passed, 82 skipped, 0 failed. /home/pding/bin/rtest was not used: it did not sync design/ and failed at collection.

AI assistance (Claude) was used to prepare this change.

… table exactly (#1630)

The existing failure test checks that a kept model-list transform is back
after the block raises. It stays green when the restore skips the clear (so
an entry the block added leaks into the live table) and when only Exception
is caught (so a KeyboardInterrupt leaves the staged view in place). The new
tests compare the whole table and registry with their state before the
block, raise a test-only exception class and assert it is the one the caller
receives, and cover a BaseException.
… and JSON path (#919)

The panel reads the config file again on each open. A models entry edited
by hand after startup to a retired type (`embedding`, `decision`) reached
declared_model_type without a location, so the request failed with no file
and no JSON path. The payload now passes `models.<name>` to
declared_model_type and turns the RetiredConfigName into a 500 whose error
reads `Failed to read config: <file>: <json path>: <message>`, with `path`
and `where` as separate fields, the same shape the loader reports.
…919)

Core retired_names gains RETIRED_MODULES, a sibling of RETIRED_NAMES: one
row per removed module path with the module to import instead (or none,
with a note). It holds the paths #919 removed (the compat converter
packages, the base.helpers / base.tools facades, provider_names,
shims.transforms) and the #1657 moves (transforms, capabilities,
shims.auth_exchange, shims.quota_probe, routing, observability.usage).
`llm-rosetta-migrate --scan` reads the import statements of .py files and
reports an import of a listed path as an `import` item whose detail names
the replacement; it counts toward exit code 1.

Why a --scan rule and not a sys.meta_path finder: a finder that raises from
find_spec turns `importlib.util.find_spec(<removed path>)` from None into
an exception, and the repo itself relies on that None (test_retired_names,
test_converter_registry and the gateway boundary test probe removed paths
that way). A finder that returns a spec with a raising loader makes
find_spec non-None, which is worse. The scan has neither side effect and
already is the command every retired-name error points to.

Until the #1657 move lands, its six old paths still exist. The scan
therefore reports a row only when its path does not resolve in the
installed core (find_spec is None), so an existing module is never
reported, and a moved path starts being reported as soon as it is gone.

@milo-oaklight milo-oaklight Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified at 89e34182. Where the body makes a claim I could reproduce, I reproduced it; the one place I'd change something is the last section.

(A) The mutation evidence holds. I ran the two mutations the body says the old test survives:

  • dropping _model_list_transforms.clear() from the failure branch: 1 failed, 34 passed — the failure is test_a_raising_block_restores_the_conversion_table_and_the_registry, and test_staging_registry_failure_keeps_registry_and_transforms stays green;
  • except BaseException narrowed to except Exception: 1 failed, 34 passed — the failure is test_a_base_exception_in_the_block_also_restores_the_state, the old test again green.

Both restored. So the new tests do carry weight the old one did not.

(C) The location reaches the response. RetiredConfigName(detail, *, where=None, path=None); located(path=...) renders /srv/gateway/config.jsonc: models.m.type: 'embedding' was renamed to 'embeddings', with .path and .where as separate attributes, and the route returns them as separate keys next to the 500 message. The helper names models.d.capabilities[0] for an index, so the JSON path goes down into arrays. The four new test files pass here: 104 passed.

(E) The scan is a scan, not a finder. No meta_path mention anywhere in the diff, and find_spec on a removed path still returns None. RETIRED_MODULES has 28 rows; 22 name paths that are already gone, six are silent because their path still resolves (llm_rosetta.transforms, .capabilities, shims.auth_exchange, shims.quota_probe, routing, observability.usage). On a tree containing one bad import the tool exits 1 and prints a.py:1: imports removed module ... import 'llm_rosetta.ir.tools.batch' instead; see the migration guide; on a clean tree it exits 0 with 0 removed import(s). All four shapes are caught: import x.y.z, from x.y import z where z is the removed submodule, a parenthesised multi-name from x.y import (a, b) (two messages, same line), and from llm_rosetta import provider_names.

The _CONTRACTS prefix exemption in the test is narrower than it looks: I changed one contract home to llm_rosetta.contracts.typo_does_not_exist and test_the_contract_moves_name_their_new_homes failed, so the literal table pins the values and a typo cannot ride the exemption.

The gap is exactly one row, and it is live now. llm_rosetta.shims.transforms is the only row where the old path is already gone and the replacement does not resolve: find_spec('llm_rosetta.contracts.transform') raises ModuleNotFoundError rather than returning None, because llm_rosetta.contracts does not exist at all on this branch. So the scan tells a user

... import 'llm_rosetta.contracts.transform' instead

and that import fails. The six rows that point into contracts.* are harmless today only because their old paths still resolve and stay silent; this one is not, because the old path is gone. If #1658 can land before #1657, I'd hold this single row back (or word it as "lands with the contracts split") rather than ship an instruction that cannot be followed. Everything else can go as is.

Not verified: a live gateway round-trip of the admin route (the tests drive get_config directly), and the docs commits (d98d35705b, 81f65c7052), which are on the docs branches.

Comment only — not approving or merging.

@Oaklight

Copy link
Copy Markdown
Owner Author

Thanks — the one open point (the llm_rosetta.shims.transforms row names llm_rosetta.contracts.transform, which does not exist yet) is handled by merge order: #1659 (which creates llm_rosetta.contracts.transform) merges before this PR, so the row never ships pointing at a missing module. No change to this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant