diff --git a/laya/router.py b/laya/router.py index 36a0ec6d5..48440676e 100644 --- a/laya/router.py +++ b/laya/router.py @@ -255,12 +255,14 @@ def _digests_from_env(models: Dict[str, Any]) -> Dict[str, Optional[Dict[str, st the bundled repository ships a separate `model.safetensors` per checkpoint, so one flat map can only ever match one of them and refuses the rest at startup. - A checkpoint the nested map does not name is returned as `{}`, meaning deliberately - unpinned: `Agent` falls back to the environment when given `None`, and reading a - model-keyed map as an artifact map fails with `cannot verify 'english': no such file`. + A checkpoint the nested map does not name is returned as `{}`, meaning "not covered by this + variable, and do not let `verify_digests` read this nested map as an artifact map either" -- it + would fail with `cannot verify 'english': no such file` on a checkpoint the variable never + named. It needs no distinguishing from a `{}` somebody wrote: both name no files, and + `_merge_expected_digests` merges them identically. Keys are normalised exactly as `Router(sha256_digests=...)` normalises them, so `en` names `english` and a name core does not know raises here rather than quietly leaving - that checkpoint unverified. Unset, empty or unparseable input returns `{}`: + that checkpoint unverified. Unset, empty or unparseable input names nothing: `laya.revisions` reports a malformed value in its own words. """ raw = os.environ.get("LAYA_SHA256_DIGESTS", "").strip() @@ -279,12 +281,83 @@ def _digests_from_env(models: Dict[str, Any]) -> Dict[str, Optional[Dict[str, st raise ValueError("LAYA_SHA256_DIGESTS must be either {artifact: digest} for every " "checkpoint or {model: {artifact: digest}} per checkpoint; %s mixes " "the two or holds a value that is neither" % sorted(data)) - per_model = {normalise_name(k): v for k, v in data.items()} + per_model = {normalise_name(k): dict(v) for k, v in data.items()} for name in models: per_model.setdefault(normalise_name(name), {}) return per_model +def _revision_pin(value: Optional[str]) -> Optional[str]: + """The revision `value` asks for, or None when it asks for nothing. + + Unset and blank are the same answer, because both are what a configuration line that did not + get filled in leaves behind, and neither is a commit anything can be pinned to. + """ + return value if value is not None and str(value).strip() else None + + +def _digest_entry( + digests: Dict[str, Optional[Dict[str, str]]], + key: str, +) -> Optional[Dict[str, str]]: + """One checkpoint's own digest entry, as `Router.sha256_digests` holds it right now. + + None when the checkpoint has no entry at all, which is what leaves `verify_digests` its own + environment fallback; `{}` for an entry that names no files, whether that is the placeholder a + nested `LAYA_SHA256_DIGESTS` left or a `None` a caller wrote. + + Read here rather than decided once at construction, because `sha256_digests` is a public mutable + attribute: a per-checkpoint pin assigned to it -- or added to an existing entry in place -- after + `Router(...)` has to count, and deciding from a key set frozen at construction dropped exactly + that. + """ + if key not in digests: + return None + entry = digests[key] + return {} if entry is None else entry + + +def _merge_expected_digests( + shared: Optional[Dict[str, str]], + per_model: Optional[Dict[str, str]], +) -> Optional[Dict[str, str]]: + """The `expected_sha256` one checkpoint is built with, out of the two channels that pin it. + + `shared` is `agent_kwargs["expected_sha256"]`, which the class docstring advertises and which + reaches every checkpoint the Router builds. `per_model` is this checkpoint's own entry: None when + it has none at all, and `{}` for the placeholder a nested `LAYA_SHA256_DIGESTS` leaves for a + checkpoint it does not name. + + None -- both channels silent -- means "pass no `expected_sha256`", which leaves `verify_digests` + its own `LAYA_SHA256_DIGESTS` fallback and keeps an unconfigured load byte for byte what it was. + An empty `{}` is **not** the same thing and must still reach `Agent`: it masks that fallback, + which for a *nested* variable would otherwise be read as an artifact map and raise + `cannot verify 'english': no such file` on a checkpoint the variable never named. + + A value that is not a mapping is handed on untouched, so `verify_digests` keeps ownership of the + "expected_sha256 must be a mapping" message rather than this layer growing a second copy. + + The two channels are merged file by file, because each names files and a digest is a claim about + one file -- dropping either half would verify less than the caller asked for. **For a file both + name, the per-checkpoint entry wins.** They are not equally specific: `shared` reaches every + checkpoint, and `model.safetensors` is the one name every checkpoint uses for a *different* file, + so a shared entry for it cannot be a correct claim about all of them at once. Refusing that + overlap as a contradiction broke the ordinary shape it appears in -- a shared pin plus a + per-checkpoint override, which loaded correctly before this function existed. + + An empty placeholder therefore needs no special case: merging it changes nothing. + """ + if per_model is not None and not isinstance(per_model, dict): + return per_model + if shared is not None and not isinstance(shared, dict): + return shared + if shared is None and per_model is None: + return None + merged = dict(shared or {}) + merged.update(per_model or {}) + return merged + + class Router(HookRegistry): """Lazily loads Laya checkpoints and sends each request to the right one. @@ -318,6 +391,23 @@ class Router(HookRegistry): which is useful when standalone repositories were reviewed at different commits. Without either, huggingface_hub's normal default and existing offline cache are used. + A `revisions` entry that is `None` or blank is "no override for this model", so the model + inherits `revision` -- the shape `{"english": os.environ.get("EN_SHA")}` writes when the + variable is unset, which must not cost the caller the pin it did ask for. Nothing in + `revisions` can unpin one model while `revision` pins the rest; leave `revision` unset and + name the models you want pinned instead. + + A blank `revision` is read the same way, which is a deliberate change in what the Router + passes on: `Router(revision=" ")` used to reach `resolve_revision`, where a truthy but blank + string suppressed the `LAYA_REVISION` fallback and left huggingface_hub's default, and is now + dropped before it gets there, so a Router configured with whitespace behaves like one + configured with nothing and `$LAYA_REVISION` applies. That is what "this configuration line was + never filled in" has to mean if `revision` and a `revisions` entry are to be read the same way. + + It is one of two places a weaker source ends up ahead of an explicit argument. The other is a + per-checkpoint digest entry from `LAYA_SHA256_DIGESTS`, which wins over an `expected_sha256` + passed through `agent_kwargs`; see the class docstring. + Anything else `laya.Agent` accepts is reachable through `agent_kwargs`, which is merged into every checkpoint the Router builds: @@ -325,6 +415,44 @@ class Router(HookRegistry): Router(agent_kwargs={"expected_sha256": {"model.safetensors": "a3f1..."}}) Router(agent_kwargs={"fast": True}) + `expected_sha256` there pins the same files on every checkpoint, which is what a single + resident checkpoint or a shared `tokenizer.json` wants. It is never discarded wholesale by a + checkpoint's own digests: where one also has an entry, from `sha256_digests` or from a + **per-checkpoint** `LAYA_SHA256_DIGESTS`, the two maps are merged **file by file**, so a file + only one of them names is still verified. + + Two exceptions, both deliberate and both tested, because "merged file by file" is not the whole + story and the difference is a supply-chain control: + + * A **flat** `LAYA_SHA256_DIGESTS` -- `{artifact: digest}` rather than `{model: {...}}` -- is + not a layer here at all. `verify_digests` applies it itself, but only when nothing else pins + (`if expected is None`), so ANY `expected_sha256` reaching `Agent`, from here or from a + checkpoint entry, means the flat variable is not consulted for that load. Verified on real + files: a flat variable pinning `model.safetensors` plus an `agent_kwargs` map pinning + `tokenizer.json` loads a tampered `model.safetensors`. Use the per-checkpoint shape, or name + every file you care about in one map, if you need both. This is unchanged from `main`. + * An explicit `{}` or `None` entry MASKS what would otherwise apply -- that is what "load this + one unverified" has to mean, and `test_an_explicit_none_entry_masks_a_flat_environment_map` + pins it. + + And the precedence is per-checkpoint over shared regardless of where each came from, so a + per-checkpoint entry synthesised from `LAYA_SHA256_DIGESTS` wins over an `expected_sha256` + passed here in code. An environment variable beating an explicit argument is worth stating + plainly on a control like this; `test_an_environment_pin_overrides_the_shared_one_per_checkpoint` + is where that is pinned. + + For a file both name, the per-checkpoint entry wins. The two are not equally specific: the + `agent_kwargs` map reaches every checkpoint the Router builds, and `model.safetensors` is the one + name every checkpoint uses for a *different* file, so a shared entry for it cannot be a correct + claim about all of them at once. **Nothing raises over that overlap** -- refusing it would reject + a shared pin plus a per-checkpoint override, which is the ordinary shape and which loaded + correctly before any of this existed. If you need to know which digest a checkpoint was verified + against, read it back: the map handed to each `Agent` is the merge described above. + + Both `agent_kwargs` and `sha256_digests` are public and mutable, and a checkpoint's entry is read + on the load rather than at construction, so a pin assigned in afterwards -- or added to an + existing entry in place -- counts. + The names the Router sets for itself -- `model_id_or_path`, `device`, `token`, `subfolder`, `revision` and the hook arguments -- are refused here rather than silently shadowed, and the remaining names are checked against `Agent.__init__` at construction, so a misspelled option @@ -336,7 +464,9 @@ class Router(HookRegistry): is no Router-wide equivalent of `revision` because digests, unlike a commit SHA, are not shareable: the bundled repository ships a separate `model.safetensors` for each of `english`, `multilingual` and `typed-decisions`, so one flat map can only ever match one - of them. A model listed with `None` or `{}` is loaded unverified. + of them. A model listed with `None` or `{}` adds no files of its own, which loads it + unverified unless `agent_kwargs["expected_sha256"]` pins it; it still masks a flat + `LAYA_SHA256_DIGESTS`, which is what listing it that way is for. The same split is available to a process configured only by environment: when `LAYA_SHA256_DIGESTS` holds a model-keyed map (`{"english": {...}, "multilingual": {...}}`) @@ -344,7 +474,10 @@ class Router(HookRegistry): own digests instead of refusing to start on the second one. A flat `LAYA_SHA256_DIGESTS` keeps its existing meaning, applied by `laya.revisions` to every checkpoint the process loads, which is right for a single-checkpoint one. An argument entry wins over the - environment for the model it names. + environment for the model it names. A nested variable that names some checkpoints and not + others says nothing about the others: they keep whatever `agent_kwargs["expected_sha256"]` + pins them with, because pinning one checkpoint from the environment is not a request to stop + verifying the rest. Hooks are opt-in and run at the Router level: `on_route` sees the routing decision, `on_load` / `on_evict` see model lifecycle, and `on_predict_start` / `on_predict_end` @@ -409,9 +542,8 @@ def __init__( # `revisions`, so a misspelled model name fails here rather than leaving that checkpoint # unverified. self.sha256_digests: Dict[str, Optional[Dict[str, str]]] = _digests_from_env(self.models) - self.sha256_digests.update({ - normalise_name(k): v for k, v in (sha256_digests or {}).items() - }) + argument = {normalise_name(k): v for k, v in (sha256_digests or {}).items()} + self.sha256_digests.update(argument) self.max_loaded = max(1, int(max_loaded)) self.default = normalise_name(default) self.auto_task_detection = bool(auto_task_detection) @@ -444,15 +576,21 @@ def load(self, name: str): from .agent import Agent repo, sub = _split(self.models[key]) kwargs = {"device": self.device, "token": self.token, "subfolder": sub} - model_revision = self.revisions.get(key, self.revision) + # A None or blank entry in `revisions` is "no pin of its own", so the checkpoint + # inherits `revision`. Reading it as a pin of nothing dropped the caller's `revision` + # and handed that one checkpoint to `$LAYA_REVISION` instead, which is the opposite of + # what asking for a pin means. + model_revision = _revision_pin(self.revisions.get(key)) or _revision_pin(self.revision) if model_revision is not None: kwargs["revision"] = model_revision - # Safe to merge last: the names this method just set are refused in `agent_kwargs`. + # Safe to merge last for the names above, which `agent_kwargs` refuses -- but not for + # `expected_sha256`, which is deliberately reachable through `agent_kwargs` and is + # therefore merged with this checkpoint's entry rather than replaced by it. kwargs.update(self.agent_kwargs) - if key in self.sha256_digests: - # `or {}` is deliberate: an explicit None still has to reach Agent as a map, or - # `verify_digests` would fall back to the environment default it is masking. - kwargs["expected_sha256"] = self.sha256_digests[key] or {} + expected = _merge_expected_digests(kwargs.pop("expected_sha256", None), + _digest_entry(self.sha256_digests, key)) + if expected is not None: + kwargs["expected_sha256"] = expected agent = Agent(repo, **kwargs) self._agents[key] = agent self._order.append(key) diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py index ccd59572d..348f78c09 100644 --- a/tests/test_hooks_api.py +++ b/tests/test_hooks_api.py @@ -83,6 +83,20 @@ def check_param(name, fn, param, default, kind=None): # ...and the per-checkpoint digests that `revisions` has always had a sibling need for check_param("Router.__init__", Router.__init__, "sha256_digests", None) +# What the constructor does NOT raise over is part of its contract too: a shared +# `agent_kwargs["expected_sha256"]` overlapping a per-checkpoint `sha256_digests` entry on one file +# name is the ordinary shape, not a contradiction -- `model.safetensors` is the one name every +# checkpoint uses for a different file. Refusing it here would reject a shared pin plus a +# per-checkpoint override, and `laya.serve` maps a ValueError out of a load to a 422 about a +# misconfiguration no request caused. +_OVERLAP = "Router.__init__/a shared pin overlapping a per-checkpoint one constructs" +try: + Router(sha256_digests={"english": {"model.safetensors": "b" * 64}}, + agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}}) + check_true(_OVERLAP, True, "constructed") +except ValueError as exc: + check_true(_OVERLAP, False, "raised instead of constructing: %s" % exc) + # load() forwards Agent's own construction options, so none of them is reachable only # through the class; tests/test_download.py asserts that against both signatures. check_param("load", load, "compile", False) diff --git a/tests/test_revision_pinning.py b/tests/test_revision_pinning.py index ef8eafdc1..31e9c8164 100644 --- a/tests/test_revision_pinning.py +++ b/tests/test_revision_pinning.py @@ -23,7 +23,7 @@ snapshot_revision, verify_digests, ) -from laya.router import Router # noqa: E402 +from laya.router import Router, _digests_from_env, _merge_expected_digests # noqa: E402 class _StopLoad(Exception): @@ -463,6 +463,30 @@ def test_nested_environment_leaves_an_unnamed_checkpoint_unpinned(self): def _env(self, per_model): return patch.dict(os.environ, {"LAYA_SHA256_DIGESTS": json.dumps(per_model)}) + # An `agent_kwargs` map is the third channel, and neither of the other two may cancel it: + # `expected_sha256` is reachable there on purpose, and a caller that pins a file is asking + # for it to be verified on every checkpoint this Router builds. + WRONG = {"model.safetensors": "0" * 64} + + def test_agent_kwargs_still_refuses_a_checkpoint_the_environment_map_skips(self): + with self._env({"english": {"model.safetensors": self.digests["english"]}}): + router = self._router({}, agent_kwargs={"expected_sha256": self.WRONG}) + with self.assertRaises(ValueError) as cm: + router.load("multilingual") + self.assertIn("SHA-256 mismatch", str(cm.exception)) + + def test_agent_kwargs_still_refuses_a_checkpoint_listed_as_none(self): + router = self._router({"multilingual": None}, agent_kwargs={"expected_sha256": self.WRONG}) + with self.assertRaises(ValueError) as cm: + router.load("multilingual") + self.assertIn("SHA-256 mismatch", str(cm.exception)) + + def test_a_correct_agent_kwargs_digest_loads_under_the_same_configuration(self): + with self._env({"english": {"model.safetensors": self.digests["english"]}}): + router = self._router({}, agent_kwargs={ + "expected_sha256": {"model.safetensors": self.digests["multilingual"]}}) + self._assert_past_the_digest_gate(router, "multilingual") + class RouterEnvDigestTests(unittest.TestCase): """How `Router` reads the two shapes of `LAYA_SHA256_DIGESTS`. @@ -544,5 +568,356 @@ def test_unparseable_environment_is_not_this_layers_error(self): self.assertEqual(Router().sha256_digests, {}, value) +class RouterDigestPrecedenceTests(unittest.TestCase): + """What reaches `Agent` when more than one channel pins the same checkpoint. + + `expected_sha256` is deliberately *not* router-owned -- `test_accepted_names_are_read_from_ + agent_rather_than_copied_here` asserts that, and the class docstring advertises + `Router(agent_kwargs={"expected_sha256": ...})` -- so a Router can hold digests from three + places at once: that argument, `sha256_digests`, and a nested `LAYA_SHA256_DIGESTS`. These + pin down that none of them silently turns another one off. + """ + + SHARED = {"tokenizer.json": "a" * 64} + PER_MODEL = {"model.safetensors": "b" * 64} + + def setUp(self): + """Start every test from an unset `LAYA_SHA256_DIGESTS`. + + Several checks here assert that *no* `expected_sha256` reaches `Agent`, which is only true of + an unconfigured process. A developer machine or CI runner that exports a **nested** variable -- + the shape this feature exists to support -- seeds a `{}` placeholder for every model, so + `expected_sha256={}` is passed and those assertions fail with no code change. Tests that want + the variable set use `_env`. + """ + patcher = patch.dict(os.environ, {}, clear=False) + patcher.start() + os.environ.pop("LAYA_SHA256_DIGESTS", None) + self.addCleanup(patcher.stop) + + def _capture(self): + """Agent stand-in carrying the real signature, so `check_agent_kwargs` still applies.""" + import inspect + + import laya.agent + + captured: list = [] + + class FakeAgent: + def __init__(self, repo, **kwargs): + captured.append(kwargs) + + __init__.__signature__ = inspect.signature(Agent.__init__) + + return patch.object(laya.agent, "Agent", FakeAgent), captured + + def _env(self, per_model): + return patch.dict(os.environ, {"LAYA_SHA256_DIGESTS": json.dumps(per_model)}) + + def _load(self, name, **router_kwargs): + capture, captured = self._capture() + with capture: + Router(**router_kwargs).load(name) + return captured[0] + + def test_a_nested_environment_pin_does_not_unverify_the_other_checkpoints(self): + # The variable names `english` only. `multilingual` is not mentioned by it, which is not + # the same as being asked for unverified: the caller's own map still has to apply. + with self._env({"english": {"model.safetensors": "e" * 64}}): + kwargs = self._load("multilingual", agent_kwargs={"expected_sha256": self.SHARED}) + self.assertEqual(kwargs["expected_sha256"], self.SHARED) + + def test_a_none_entry_does_not_discard_the_agent_kwargs_map(self): + kwargs = self._load("english", sha256_digests={"english": None}, + agent_kwargs={"expected_sha256": self.SHARED}) + self.assertEqual(kwargs["expected_sha256"], self.SHARED) + + def test_the_two_maps_are_merged_file_by_file(self): + kwargs = self._load("english", sha256_digests={"english": self.PER_MODEL}, + agent_kwargs={"expected_sha256": self.SHARED}) + self.assertEqual(kwargs["expected_sha256"], dict(self.SHARED, **self.PER_MODEL)) + + def test_a_per_checkpoint_pin_wins_over_a_shared_one_for_the_same_file(self): + """The two channels are not equally specific, so the narrower one decides. + + `agent_kwargs["expected_sha256"]` reaches every checkpoint, and `model.safetensors` is the + one name every checkpoint uses for a *different* file -- so a shared entry for it cannot be + a correct claim about all of them at once. An earlier version of this fix refused the + overlap as a contradiction, which broke the ordinary shape it appears in: a shared pin plus + a per-checkpoint override, which loaded correctly before any of this existed. + """ + capture, captured = self._capture() + with capture: + router = Router(agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}}, + sha256_digests={"multilingual": {"model.safetensors": "b" * 64}}) + router.load("english") + router.load("multilingual") + self.assertEqual(captured[0]["expected_sha256"], {"model.safetensors": "c" * 64}, + "the shared pin applies where nothing overrides it") + self.assertEqual(captured[1]["expected_sha256"], {"model.safetensors": "b" * 64}, + "the per-checkpoint pin wins for the file both name") + + def test_an_environment_pin_overrides_the_shared_one_per_checkpoint(self): + """Same precedence, reached through the variable, and every checkpoint stays loadable. + + This is the shape that matters in a deployment: the variable pins each checkpoint's own + weight file and the caller passes one shared map. Refusing it would have stopped the server + from serving the checkpoint the two configurations do not actually disagree about. + """ + capture, captured = self._capture() + shared = {"model.safetensors": "c" * 64} + with self._env({"english": {"model.safetensors": "b" * 64}}), capture: + router = Router(agent_kwargs={"expected_sha256": shared}) + router.load("multilingual") + router.load("english") + self.assertEqual(captured[0]["expected_sha256"], shared, + "the checkpoint the variable does not name keeps the shared pin") + self.assertEqual(captured[1]["expected_sha256"], {"model.safetensors": "b" * 64}, + "the checkpoint the variable names uses its own digest") + + def test_files_only_one_channel_names_are_still_merged(self): + """Precedence applies per file, not per map: a file only one channel names still counts. + + This is the half of the merge that is worth having -- the caller pins the tokenizer, the + deployment pins the weights, and the load verifies both. Ranking whole maps against each + other, as the code did before this fix, verified only one of them. + """ + capture, captured = self._capture() + with self._env({"english": {"model.safetensors": "b" * 64}}), capture: + router = Router(agent_kwargs={"expected_sha256": {"tokenizer.json": "d" * 64}}) + router.load("english") + self.assertEqual(captured[0]["expected_sha256"], + {"tokenizer.json": "d" * 64, "model.safetensors": "b" * 64}, + "both channels' files must reach verify_digests") + + def test_digests_added_into_an_environment_placeholder_in_place_are_verified(self): + """Filling in the placeholder the variable left is a pin, and has to be honoured. + + `_digests_from_env` leaves an empty entry for every checkpoint a nested + `LAYA_SHA256_DIGESTS` does not name, tagged as "not something anyone asked for" so it cannot + cancel an `agent_kwargs` map. But `sha256_digests` is public: an operator may add digests to + that entry in place. Treating it as unpinned for ever dropped them silently -- and only when + an `agent_kwargs` map happened to be present, so the behaviour was config-dependent. + """ + capture, captured = self._capture() + with self._env({"english": {"model.safetensors": "b" * 64}}), capture: + router = Router(agent_kwargs={"expected_sha256": {"tokenizer.json": "d" * 64}}) + router.sha256_digests["multilingual"]["model.safetensors"] = "e" * 64 + router.load("multilingual") + self.assertEqual(captured[0]["expected_sha256"], + {"tokenizer.json": "d" * 64, "model.safetensors": "e" * 64}, + "a digest added into the placeholder must reach verify_digests") + + def test_an_untouched_environment_placeholder_still_reaches_agent_as_an_empty_map(self): + """A placeholder must arrive as `{}`, NOT be omitted -- omitting it is a refusal. + + This looks backwards until you run it: with a *nested* `LAYA_SHA256_DIGESTS` and no + `expected_sha256` kwarg at all, `verify_digests` reads that nested map as an artifact map and + raises `cannot verify 'english': no such file` -- on a checkpoint the variable never named. + The empty map is what masks that fallback. Passing nothing is only correct when no channel + said anything. + """ + capture, captured = self._capture() + with self._env({"english": {"model.safetensors": "b" * 64}}), capture: + Router().load("multilingual") + self.assertEqual(captured[0].get("expected_sha256"), {}, + "the placeholder must mask the nested-variable fallback") + + # And with nothing configured anywhere, no kwarg is passed at all (#332). + capture2, captured2 = self._capture() + with capture2: + Router().load("multilingual") + self.assertNotIn("expected_sha256", captured2[0]) + + def test_an_explicit_none_entry_masks_a_flat_environment_map(self): + """`sha256_digests={"english": None}` means "load this one unverified", and has to hold. + + A *flat* `LAYA_SHA256_DIGESTS` is applied by `verify_digests` itself, for every checkpoint. + Saying "not this one" therefore cannot be expressed by passing nothing -- that is exactly + what lets the flat map through. It has to arrive as an empty map. + """ + flat = {"model.safetensors": "f" * 64} + for entry in (None, {}): + capture, captured = self._capture() + with self._env(flat), capture: + Router(sha256_digests={"english": entry}).load("english") + self.assertEqual(captured[0].get("expected_sha256"), {}, + "an explicit %r entry must mask the flat variable" % (entry,)) + # And with no entry at all the flat map is left to apply. + capture, captured = self._capture() + with self._env(flat), capture: + Router().load("english") + self.assertNotIn("expected_sha256", captured[0]) + + def test_a_pin_assigned_after_construction_wins_for_its_own_file(self): + """`sha256_digests` is public and mutable, so a pin assigned later has to take effect.""" + capture, captured = self._capture() + with capture: + router = Router(agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}}) + router.sha256_digests["english"] = {"model.safetensors": "b" * 64} + router.load("english") + self.assertEqual(captured[0]["expected_sha256"], {"model.safetensors": "b" * 64}) + + def test_a_pin_added_after_construction_is_verified(self): + # `sha256_digests` is public and mutable, so what it holds at load time is what has to be + # verified. Deciding "somebody asked for this checkpoint" from a key set frozen in + # `__init__` dropped a later per-checkpoint pin -- and only when `agent_kwargs` happened + # to carry a map, which is the one configuration where the drop mattered. + capture, captured = self._capture() + with capture: + router = Router(agent_kwargs={"expected_sha256": self.SHARED}) + router.sha256_digests["english"] = self.PER_MODEL + router.load("english") + self.assertEqual(captured[0]["expected_sha256"], dict(self.SHARED, **self.PER_MODEL)) + + def test_an_empty_map_assigned_after_construction_replaces_the_environment_entry(self): + """Assigning `{}` over an environment entry drops that entry's files. + + What this pins is the *assignment*, not a placeholder/explicit distinction: `_digest_entry` + collapses a caller's `{}`, a caller's `None` and the placeholder to the same `{}` on purpose, + so there is nothing here that could tell them apart. The behaviour worth pinning is that the + entry the variable had put there is gone, which is why the shared map alone is the answer. + """ + capture, captured = self._capture() + with self._env({"english": dict(self.PER_MODEL)}), capture: + router = Router(agent_kwargs={"expected_sha256": dict(self.SHARED)}) + router.sha256_digests["english"] = {} + router.load("english") + self.assertEqual(captured[0]["expected_sha256"], self.SHARED, + "the assigned empty map must replace the variable's entry") + + def test_the_environment_entries_still_read_as_plain_maps(self): + # How the placeholder is marked is this module's business: `sha256_digests` is public, and + # `RouterEnvDigestTests` reads it as plain dicts. + with self._env({"english": {"model.safetensors": "e" * 64}}): + digests = Router().sha256_digests + self.assertEqual(digests, {"english": {"model.safetensors": "e" * 64}, + "multilingual": {}, "typed-decisions": {}}) + + def test_the_same_digest_from_both_channels_is_not_a_conflict(self): + both = {"model.safetensors": "b" * 64} + kwargs = self._load("english", sha256_digests={"english": both}, + agent_kwargs={"expected_sha256": {"model.safetensors": "B" * 64}}) + self.assertEqual({k: v.lower() for k, v in kwargs["expected_sha256"].items()}, both) + + def test_nothing_configured_still_passes_no_map_at_all(self): + # #332's opt-in guarantee: an unconfigured Router must leave `verify_digests` its own + # `LAYA_SHA256_DIGESTS` fallback, so an existing HF_HUB_OFFLINE=1 cache loads as before. + self.assertNotIn("expected_sha256", self._load("english")) + + +class RouterRevisionFallbackTests(unittest.TestCase): + """A `revisions` entry that names no commit must not cost the caller the pin it did ask for. + + `revisions` is typed `Optional[Dict[str, Optional[str]]]`, so `None` values are legal, and + `{"english": os.environ.get("EN_SHA")}` produces one whenever that variable is unset. + """ + + def _capture(self): + import inspect + + import laya.agent + + captured: list = [] + + class FakeAgent: + def __init__(self, repo, **kwargs): + captured.append(kwargs) + + __init__.__signature__ = inspect.signature(Agent.__init__) + + return patch.object(laya.agent, "Agent", FakeAgent), captured + + def _load(self, name="english", env="", **router_kwargs): + capture, captured = self._capture() + with patch.dict(os.environ, {"LAYA_REVISION": env}), capture: + Router(**router_kwargs).load(name) + return captured[0] + + def _effective(self, kwargs, env=""): + """What `Agent` would download: `resolve_revision` applied to the kwarg it was handed.""" + with patch.dict(os.environ, {"LAYA_REVISION": env}): + return resolve_revision("convaiinnovations/laya", kwargs.get("revision")) + + def test_a_none_entry_inherits_the_router_wide_revision(self): + kwargs = self._load(revision="aaa", revisions={"english": None}) + self.assertEqual(kwargs["revision"], "aaa") + + def test_a_none_entry_does_not_hand_the_checkpoint_to_the_environment(self): + kwargs = self._load(revision="aaa", revisions={"english": None}, env="bbb") + self.assertEqual(self._effective(kwargs, env="bbb"), "aaa") + + def test_a_blank_entry_is_read_the_same_way(self): + for blank in ("", " "): + kwargs = self._load(revision="aaa", revisions={"english": blank}, env="bbb") + self.assertEqual(self._effective(kwargs, env="bbb"), "aaa", blank) + + def test_a_blank_router_wide_revision_is_not_a_pin(self): + self.assertNotIn("revision", self._load(revision=" ")) + + def test_an_explicit_per_model_revision_still_wins(self): + kwargs = self._load("multilingual", revision="aaa", + revisions={"multilingual": "ccc", "english": None}, env="bbb") + self.assertEqual(kwargs["revision"], "ccc") + + def test_an_unconfigured_router_still_leaves_the_revision_to_the_environment(self): + # The other half of #332: nothing asked for means the deployment's `LAYA_REVISION` (or + # huggingface_hub's default) applies, exactly as it does for a hand-built `Agent`. + kwargs = self._load(env="bbb") + self.assertNotIn("revision", kwargs) + self.assertEqual(self._effective(kwargs, env="bbb"), "bbb") + + +class ReviewGapTests(unittest.TestCase): + """Guards an adversarial review found unpinned: each mutant below survived every lane.""" + + def test_a_non_dict_per_checkpoint_entry_is_handed_on_untouched(self): + """`_merge_expected_digests` hands a non-dict on so `verify_digests` owns the message. + + Dropping the guard let a list of pairs be `dict.update`-ed into a map and silently accepted + as digests. Both shapes still fail closed, but only one of them fails in the right words. + """ + self.assertEqual(_merge_expected_digests({"a": "1" * 64}, "nope"), "nope") + self.assertEqual(_merge_expected_digests({"a": "1" * 64}, [("a", "1" * 64)]), + [("a", "1" * 64)]) + + def test_a_non_dict_shared_map_is_handed_on_untouched(self): + """The same for the shared half, which had the same missing coverage.""" + self.assertEqual(_merge_expected_digests("nope", None), "nope") + self.assertEqual(_merge_expected_digests(["a"], None), ["a"]) + + def test_a_blank_revision_suppresses_the_environment_through_agent(self): + """`(revision or env).strip()`: a truthy-but-blank argument wins the `or`, then strips away. + + The Router drops a blank before it reaches here, and that is tested. `Agent`/`laya.load` do + not, so a config line that ends up whitespace silently loses the deployment's pin and gets + huggingface_hub's default. Undocumented and untested before: the mutant that makes a blank + behave like an absent value survived every lane. Pinned as the behaviour that exists, so a + change to it is a decision rather than an accident. + """ + with patch.dict(os.environ, {"LAYA_REVISION": "deadbeef"}, clear=False): + self.assertEqual(resolve_revision("some/repo", None), "deadbeef") + self.assertEqual(resolve_revision("some/repo", ""), "deadbeef") + self.assertIsNone(resolve_revision("some/repo", " ")) + self.assertIsNone(resolve_revision("some/repo", "\t")) + self.assertEqual(resolve_revision("some/repo", " aaa "), "aaa") + + def test_a_flat_environment_map_is_masked_by_any_other_pin(self): + """The documented exception, asserted so the class docstring cannot drift from it again. + + `verify_digests` reads a flat `LAYA_SHA256_DIGESTS` only `if expected is None`, so anything + reaching `Agent` as `expected_sha256` means the flat variable is not consulted. An earlier + revision of the class docstring said the two were "merged file by file", which is true of + the per-checkpoint shape and false of this one. + """ + with patch.dict(os.environ, + {"LAYA_SHA256_DIGESTS": json.dumps({"model.safetensors": "a" * 64})}, + clear=False): + self.assertEqual(_digests_from_env(["english"]), {}) # flat: not a layer here + merged = _merge_expected_digests({"tokenizer.json": "b" * 64}, None) + self.assertEqual(merged, {"tokenizer.json": "b" * 64}) + self.assertNotIn("model.safetensors", merged) + + if __name__ == "__main__": unittest.main()