Enterprise agent platform for building, deploying, and operating AI teammates.
"""Unit tests for core/execution_scope.py.
Covers the value type, the contextvar helpers, the resolver hook, and the
per-turn activation contract (including restart/resume re-resolution). The
resolver is authoritative over a persisted snapshot rather than always
losing to it. The resolver fixtures below register through
``acknowledges_snapshot_candidate_contract=True`` -- see
``TestSnapshotCandidateAuthority`` for the full resolver/snapshot precedence
matrix and ``tests/web/test_execution_scope_delegation.py`` for the
web-layer snapshot loader wiring. The resolver/loader globals themselves are
reset by the root-level ``isolate_execution_scope_hooks`` autouse fixture in
``tests/conftest.py``, not by a fixture in this module.
"""
import asyncio
import contextvars
import dataclasses
import logging
from contextlib import contextmanager
import pytest
from xagent.core.execution_scope import (
EXECUTION_SCOPE_AGENT_CONFIG_KEY,
EXECUTION_SCOPE_SHAPE_VERSION,
DeferToSnapshot,
ExecutionScope,
ExecutionScopeAbstentionMismatchError,
ExecutionScopeAuthorityError,
ExecutionScopeContext,
ExecutionScopeResolverContractError,
InvalidScopeComponentError,
execution_scope_from_agent_config,
execution_scope_resolver_registered,
get_execution_scope,
reset_execution_scope,
resolve_execution_scope,
resolve_execution_scope_off_turn,
scope_fingerprint,
set_execution_scope,
set_execution_scope_resolver,
set_execution_scope_snapshot_loader,
turn_execution_scope,
validate_scope_component,
)
@contextmanager
def scope_log_records(level: int = logging.WARNING):
"""Record what this module logs, without going through logging config.
Asserting on log *content* through ``caplog`` or an attached handler makes
the assertion depend on the level, the global disable threshold, the handler
set and which module instance owns the logger -- none of which the code
under test decides. Swapping the ``logger`` binding in the namespace the
functions actually read it from observes the call itself, so what is
asserted is that the code logs, not that a particular logging setup
delivers it.
``level`` is the enablement the recorder itself reports, so code that asks
``logger.isEnabledFor(...)`` before building a message gets a deterministic
answer from the recorder rather than from whatever the ambient logging
configuration happens to be. Every call that survives that check is
recorded verbatim; the caller filters.
"""
class _Recorder:
def __init__(self, wrapped: logging.Logger) -> None:
self._wrapped = wrapped
self.records: list[str] = []
def isEnabledFor(self, asked: int) -> bool: # noqa: N802 - logging API
return asked >= level
def info(self, msg: str, *args: object, **kwargs: object) -> None:
self.records.append(msg % args if args else msg)
self._wrapped.info(msg, *args, **kwargs)
def warning(self, msg: str, *args: object, **kwargs: object) -> None:
self.records.append(msg % args if args else msg)
self._wrapped.warning(msg, *args, **kwargs)
def error(self, msg: str, *args: object, **kwargs: object) -> None:
self.records.append(msg % args if args else msg)
self._wrapped.error(msg, *args, **kwargs)
# There is deliberately no ``__getattr__`` delegating the rest to the
# wrapped logger. ``isEnabledFor`` must not be delegated -- that would
# put the ambient level and the process-wide disable threshold back in
# charge of what the code under test does, which is the whole reason
# this helper exists -- and modelling exactly the levels the module
# logs at means a newly introduced level surfaces as a loud
# ``AttributeError`` instead of a silently unrecorded call.
# The function's own globals: the binding it resolves `logger` against at
# call time, whichever module instance that turns out to be.
namespace = resolve_execution_scope.__globals__
original = namespace["logger"]
recorder = _Recorder(original)
namespace["logger"] = recorder
try:
yield recorder.records
finally:
namespace["logger"] = original
class TestValidateScopeComponent:
def test_accepts_valid_components(self):
for value in ["a", "A-b_9", "x" * 63, "0", "_", "-"]:
assert validate_scope_component(value) == value
@pytest.mark.parametrize(
"value",
[
"",
"x" * 64,
"a:b",
"a/b",
"..",
"a b",
"a\n",
"café",
"a.b",
None,
123,
["a"],
],
)
def test_rejects_invalid_components(self, value):
with pytest.raises(InvalidScopeComponentError):
validate_scope_component(value)
def test_rejects_without_sanitizing(self):
"""Invalid input raises and logs; it is never rewritten to a valid form."""
with scope_log_records(logging.ERROR) as records:
with pytest.raises(InvalidScopeComponentError):
validate_scope_component("bad:name", field_name="sandbox_key_suffix")
assert any("sandbox_key_suffix" in r for r in records)
class TestExecutionScope:
def test_defaults_are_unscoped_behavior(self):
scope = ExecutionScope()
assert scope.sandbox_key_suffix is None
assert scope.workspace_segments == ()
assert dict(scope.memory_dimensions) == {}
assert scope.strict_memory_isolation is False
assert scope.isolate_external_dirs is False
def test_frozen(self):
scope = ExecutionScope()
with pytest.raises(dataclasses.FrozenInstanceError):
scope.sandbox_key_suffix = "x"
def test_memory_dimensions_are_read_only(self):
scope = ExecutionScope(memory_dimensions={"tenant": "acme"})
with pytest.raises(TypeError):
scope.memory_dimensions["tenant"] = "other"
def test_workspace_segments_normalized_to_tuple(self):
scope = ExecutionScope(workspace_segments=["proj", "env"])
assert scope.workspace_segments == ("proj", "env")
def test_equality(self):
a = ExecutionScope(
sandbox_key_suffix="s",
workspace_segments=("w",),
memory_dimensions={"k": "v"},
)
b = ExecutionScope(
sandbox_key_suffix="s",
workspace_segments=["w"],
memory_dimensions={"k": "v"},
)
assert a == b
assert a != ExecutionScope(sandbox_key_suffix="other")
def test_rejects_invalid_sandbox_key_suffix(self):
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(sandbox_key_suffix="a:b")
def test_rejects_invalid_workspace_segment(self):
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(workspace_segments=("ok", "../escape"))
def test_rejects_invalid_memory_dimension_key(self):
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(memory_dimensions={"bad key": "v"})
@pytest.mark.parametrize("value", ["", None, 3])
def test_rejects_invalid_memory_dimension_value(self, value):
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(memory_dimensions={"k": value})
def test_none_containers_raise_descriptive_value_error(self):
"""None for the collection fields raises a descriptive ValueError
instead of an opaque TypeError from tuple()/dict() conversion."""
with pytest.raises(ValueError, match="workspace_segments cannot be None"):
ExecutionScope(workspace_segments=None)
with pytest.raises(ValueError, match="memory_dimensions cannot be None"):
ExecutionScope(memory_dimensions=None)
def test_boolean_flags_independent_of_other_fields(self):
"""Flags are consumable with an otherwise-empty scope (independent fields)."""
scope = ExecutionScope(strict_memory_isolation=True)
assert scope.strict_memory_isolation is True
assert scope.sandbox_key_suffix is None
assert scope.workspace_segments == ()
class TestSandboxMountSegments:
"""The mount-prefix field (#79-01): decouples the sandbox mount root from
the full workspace_segments so scopes sharing a suffix + prefix share one
container while deeper segments stay in disjoint subtrees."""
def test_default_mount_covers_full_workspace_segments(self):
"""Unset prefix => mount root == workspace root (byte-identical)."""
scope = ExecutionScope(
sandbox_key_suffix="client-3",
workspace_segments=("clients", "3", "end_users", "7"),
)
assert scope.sandbox_mount_segments is None
assert scope.effective_mount_segments == ("clients", "3", "end_users", "7")
def test_unscoped_scope_has_empty_effective_mount(self):
assert ExecutionScope().effective_mount_segments == ()
def test_prefix_mount_shared_across_deeper_segments(self):
"""Two end users of one CA share a mount prefix; only deeper differs."""
a = ExecutionScope(
sandbox_key_suffix="client-3",
workspace_segments=("clients", "3", "end_users", "7"),
sandbox_mount_segments=("clients", "3"),
)
b = ExecutionScope(
sandbox_key_suffix="client-3",
workspace_segments=("clients", "3", "end_users", "8"),
sandbox_mount_segments=("clients", "3"),
)
assert a.effective_mount_segments == ("clients", "3")
assert b.effective_mount_segments == ("clients", "3")
assert a.workspace_segments != b.workspace_segments
def test_mount_segments_normalized_to_tuple(self):
scope = ExecutionScope(
workspace_segments=["clients", "3", "end_users", "7"],
sandbox_mount_segments=["clients", "3"],
)
assert scope.sandbox_mount_segments == ("clients", "3")
def test_empty_prefix_mounts_at_user_root(self):
"""() is a valid prefix of any segments — mount at the user root."""
scope = ExecutionScope(
workspace_segments=("clients", "3"),
sandbox_mount_segments=(),
)
assert scope.effective_mount_segments == ()
def test_rejects_non_prefix_mount_segments(self):
with pytest.raises(InvalidScopeComponentError, match="must be a prefix"):
ExecutionScope(
workspace_segments=("clients", "3", "end_users", "7"),
sandbox_mount_segments=("clients", "4"),
)
def test_rejects_mount_longer_than_workspace_segments(self):
with pytest.raises(InvalidScopeComponentError, match="must be a prefix"):
ExecutionScope(
workspace_segments=("clients", "3"),
sandbox_mount_segments=("clients", "3", "end_users", "7"),
)
def test_rejects_invalid_mount_segment_component(self):
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(
workspace_segments=("clients", "3"),
sandbox_mount_segments=("clients", "../escape"),
)
def test_to_dict_from_dict_round_trips_prefix(self):
scope = ExecutionScope(
sandbox_key_suffix="client-3",
workspace_segments=("clients", "3", "end_users", "7"),
sandbox_mount_segments=("clients", "3"),
)
assert ExecutionScope.from_dict(scope.to_dict()) == scope
assert scope.to_dict()["sandbox_mount_segments"] == ["clients", "3"]
def test_to_dict_preserves_none_vs_empty_distinction(self):
"""None (mount == full segments) must not collapse into () (mount at
user root) across a serialization round-trip."""
default = ExecutionScope(workspace_segments=("clients", "3"))
assert default.to_dict()["sandbox_mount_segments"] is None
restored_default = ExecutionScope.from_dict(default.to_dict())
assert restored_default.sandbox_mount_segments is None
rooted = ExecutionScope(
workspace_segments=("clients", "3"), sandbox_mount_segments=()
)
assert rooted.to_dict()["sandbox_mount_segments"] == []
restored_rooted = ExecutionScope.from_dict(rooted.to_dict())
assert restored_rooted.sandbox_mount_segments == ()
class TestDurableStorageSegments:
"""The durable-storage-handle field (#828): mirrors the filesystem
external-dir allowlist — narrow the object-storage handle to the scope
subtree only under ``isolate_external_dirs``."""
def test_isolated_scope_yields_workspace_segments(self):
scope = ExecutionScope(
workspace_segments=("clients", "3", "end_users", "7"),
isolate_external_dirs=True,
)
assert scope.durable_storage_segments == ("clients", "3", "end_users", "7")
def test_non_isolated_scope_yields_empty(self):
# Segments present but not isolated => owner-root handle (shared reads).
scope = ExecutionScope(
workspace_segments=("clients", "3", "end_users", "7"),
isolate_external_dirs=False,
)
assert scope.durable_storage_segments == ()
def test_unscoped_scope_yields_empty(self):
assert ExecutionScope().durable_storage_segments == ()
def test_isolated_without_segments_yields_empty(self):
assert ExecutionScope(isolate_external_dirs=True).durable_storage_segments == ()
class TestContextvarHelpers:
def test_not_provided_sentinel_is_a_shared_typed_value(self):
from xagent.core.execution_scope import (
EXECUTION_SCOPE_NOT_PROVIDED,
ExecutionScopeNotProvided,
)
assert EXECUTION_SCOPE_NOT_PROVIDED is not None
assert type(EXECUTION_SCOPE_NOT_PROVIDED) is ExecutionScopeNotProvided
def test_default_is_none(self):
assert get_execution_scope() is None
def test_set_and_reset(self):
scope = ExecutionScope(sandbox_key_suffix="s1")
token = set_execution_scope(scope)
try:
assert get_execution_scope() is scope
finally:
reset_execution_scope(token)
assert get_execution_scope() is None
def test_context_manager_restores_previous(self):
outer = ExecutionScope(sandbox_key_suffix="outer")
inner = ExecutionScope(sandbox_key_suffix="inner")
with ExecutionScopeContext(outer):
assert get_execution_scope() is outer
with ExecutionScopeContext(inner):
assert get_execution_scope() is inner
assert get_execution_scope() is outer
assert get_execution_scope() is None
def test_context_manager_restores_on_exception(self):
scope = ExecutionScope(sandbox_key_suffix="s1")
with pytest.raises(RuntimeError):
with ExecutionScopeContext(scope):
raise RuntimeError("boom")
assert get_execution_scope() is None
def test_explicit_none_overrides_outer_scope(self):
"""Setting None is explicitly-unscoped, shadowing any outer scope."""
outer = ExecutionScope(sandbox_key_suffix="outer")
with ExecutionScopeContext(outer):
with ExecutionScopeContext(None):
assert get_execution_scope() is None
assert get_execution_scope() is outer
class TestResolverHook:
def test_no_resolver_resolves_unscoped(self):
assert resolve_execution_scope("42") is None
def test_resolver_receives_task_id_as_str(self):
seen = []
def resolver(task_id):
seen.append(task_id)
return None
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
resolve_execution_scope(42)
assert seen == ["42"]
def test_resolver_result_is_returned(self):
scope = ExecutionScope(sandbox_key_suffix="s1")
set_execution_scope_resolver(
lambda task_id: scope, acknowledges_snapshot_candidate_contract=True
)
assert resolve_execution_scope("42") is scope
def test_resolver_exception_propagates(self):
"""A resolver error fails the turn instead of silently running unscoped."""
def resolver(task_id):
raise RuntimeError("resolver down")
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
with pytest.raises(RuntimeError, match="resolver down"):
resolve_execution_scope("42")
def test_none_task_id_raises_instead_of_resolving_the_string_none(self):
"""str(None) would silently query the resolver for "None"; a caller
with no task identity must treat the execution as unscoped itself."""
seen = []
set_execution_scope_resolver(
lambda task_id: seen.append(task_id),
acknowledges_snapshot_candidate_contract=True,
)
with pytest.raises(ValueError, match="task_id cannot be None"):
resolve_execution_scope(None)
assert seen == []
def test_resolver_can_be_cleared(self):
set_execution_scope_resolver(
lambda task_id: ExecutionScope(),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_resolver(None)
assert resolve_execution_scope("42") is None
class TestTurnExecutionScope:
def test_activates_resolved_scope_for_the_turn(self):
scope = ExecutionScope(workspace_segments=("proj",))
set_execution_scope_resolver(
lambda task_id: scope if task_id == "7" else None,
acknowledges_snapshot_candidate_contract=True,
)
with turn_execution_scope(7) as active:
assert active is scope
assert get_execution_scope() is scope
assert get_execution_scope() is None
def test_unscoped_turn_activates_none(self):
with turn_execution_scope("7") as active:
assert active is None
assert get_execution_scope() is None
def test_resolver_called_once_per_turn(self):
calls = []
def resolver(task_id):
calls.append(task_id)
return ExecutionScope(sandbox_key_suffix=f"t{task_id}")
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
with turn_execution_scope("7"):
pass
with turn_execution_scope("7"):
pass
assert calls == ["7", "7"]
def test_scope_restored_on_exception(self):
set_execution_scope_resolver(
lambda task_id: ExecutionScope(),
acknowledges_snapshot_candidate_contract=True,
)
with pytest.raises(RuntimeError):
with turn_execution_scope("7"):
raise RuntimeError("turn failed")
assert get_execution_scope() is None
def test_resume_after_restart_re_resolves_identical_scope(self):
"""A resumed task re-resolves and re-applies the identical scope.
Simulates a process restart between turns: the contextvar starts
empty in a fresh context and the embedder re-registers its resolver
at startup; the scope is re-derived from the resolver's persistent
mapping keyed by task_id, not from any prior in-process state.
"""
resolver_calls = []
def make_resolver():
# The embedder derives the scope from its own persistent data;
# a fresh resolver instance (new process) yields an equal scope.
def resolver(task_id):
resolver_calls.append(task_id)
return ExecutionScope(
sandbox_key_suffix="tenant-a",
workspace_segments=("tenant-a",),
memory_dimensions={"tenant": "a"},
)
return resolver
def run_turn():
set_execution_scope_resolver(
make_resolver(), acknowledges_snapshot_candidate_contract=True
)
with turn_execution_scope("99") as scope:
return scope, get_execution_scope()
# Turn 1 and turn 2 run in independent contexts (as after a restart).
first_scope, first_active = contextvars.copy_context().run(run_turn)
set_execution_scope_resolver(None)
second_scope, second_active = contextvars.copy_context().run(run_turn)
assert resolver_calls == ["99", "99"]
assert first_active is first_scope
assert second_active is second_scope
assert first_scope == second_scope
def test_scope_visible_inside_async_turn(self):
"""The activated scope propagates into the turn's async execution."""
scope = ExecutionScope(sandbox_key_suffix="s1")
set_execution_scope_resolver(
lambda task_id: scope, acknowledges_snapshot_candidate_contract=True
)
async def fake_agent_execution():
await asyncio.sleep(0)
return get_execution_scope()
async def turn():
with turn_execution_scope("7"):
return await fake_agent_execution()
assert asyncio.run(turn()) is scope
class TestDeferToSnapshot:
"""The carrier for a resolver's explicit abstention."""
def test_requires_an_execution_scope_fallback(self):
with pytest.raises(TypeError):
DeferToSnapshot("not-a-scope")
def test_carrier_is_not_an_execution_scope(self):
carrier = DeferToSnapshot(ExecutionScope())
assert isinstance(carrier, DeferToSnapshot)
assert isinstance(carrier, ExecutionScope) is False
def test_carrier_has_no_public_bare_singleton(self):
"""The fallback-carrying class is the only way to abstain -- a bare
module-level sentinel would let "defer" mean "unscoped on miss"
implicitly instead of requiring an explicit fallback."""
import xagent.core.execution_scope as scope_module
assert not hasattr(scope_module, "DEFER_TO_SNAPSHOT")
def test_no_passthrough_factory_duplicates_the_carrier(self):
"""One concept, one public name. The class holds the abstention
contract and its own construction-time validation, so a module-level
factory wrapping it would be a second spelling resolver authors have
to choose between, and a second place validation could drift to."""
import xagent.core.execution_scope as scope_module
assert not hasattr(scope_module, "defer_to_snapshot")
def test_carrier_exposes_the_fallback(self):
fallback = ExecutionScope(sandbox_key_suffix="fallback")
assert DeferToSnapshot(fallback).fallback == fallback
class TestSetExecutionScopeResolverAckToken:
"""The confirmation-token contract on ``set_execution_scope_resolver``."""
def test_registering_a_resolver_without_ack_raises(self):
with pytest.raises(TypeError, match="acknowledges_snapshot_candidate_contract"):
set_execution_scope_resolver(lambda task_id: None)
def test_clearing_the_resolver_never_needs_ack(self):
# None never triggers the check: the ~20 cleanup call sites across
# the test suite that reset the resolver to None stay unchanged.
set_execution_scope_resolver(None)
assert execution_scope_resolver_registered() is False
def test_ack_true_registers_successfully(self):
set_execution_scope_resolver(
lambda task_id: None, acknowledges_snapshot_candidate_contract=True
)
assert execution_scope_resolver_registered() is True
def test_ack_false_explicitly_still_raises(self):
with pytest.raises(TypeError):
set_execution_scope_resolver(
lambda task_id: None,
acknowledges_snapshot_candidate_contract=False,
)
class TestExecutionScopeAuthorityErrorInheritance:
"""Pin: distinguishable from the two exceptions this module
already raises, so no existing ``except RuntimeError``/``except
ValueError`` clause silently folds an authority conflict into them."""
def test_not_a_runtime_error(self):
assert not issubclass(ExecutionScopeAuthorityError, RuntimeError)
def test_not_a_value_error(self):
assert not issubclass(ExecutionScopeAuthorityError, ValueError)
def test_not_a_type_error(self):
assert not issubclass(ExecutionScopeAuthorityError, TypeError)
def test_not_a_key_error(self):
assert not issubclass(ExecutionScopeAuthorityError, KeyError)
def test_is_a_plain_exception(self):
assert issubclass(ExecutionScopeAuthorityError, Exception)
def test_str_carries_task_id_and_field_names_never_values(self):
"""``str()`` on this exception ends up in ``task.error_message`` and
in the client's terminal error event (see this class's docstring for
the exact surfacing sites), so it must never leak the scope values
-- e.g. ``sandbox_key_suffix``/``workspace_segments``/
``memory_dimensions`` -- which can carry end-user/client
identifiers. Only the task id and the mismatched field *names* are
safe to include."""
resolver_scope = ExecutionScope(
sandbox_key_suffix="resolver-secret-suffix",
workspace_segments=("resolver-secret-segment",),
)
snapshot_scope = ExecutionScope(
sandbox_key_suffix="snapshot-secret-suffix",
workspace_segments=("snapshot-secret-segment",),
)
exc = ExecutionScopeAuthorityError(
"task-123",
resolver_scope=resolver_scope,
snapshot_scope=snapshot_scope,
mismatched_fields={
"sandbox_key_suffix": (
snapshot_scope.sandbox_key_suffix,
resolver_scope.sandbox_key_suffix,
),
"workspace_segments": (
snapshot_scope.workspace_segments,
resolver_scope.workspace_segments,
),
},
resolver_scope_is_authoritative=True,
)
message = str(exc)
assert "task-123" in message
assert "sandbox_key_suffix" in message
assert "workspace_segments" in message
assert "resolver-secret-suffix" not in message
assert "snapshot-secret-suffix" not in message
assert "resolver-secret-segment" not in message
assert "snapshot-secret-segment" not in message
class TestExecutionScopeResolverContractErrorInheritance:
"""Pin: the resolve-boundary "unknown return type" error
must not be catchable by the ``except (ValueError, KeyError, TypeError)``
clauses several websocket handlers wrap around the turn-execution path
-- those fold anything in that tuple into a generic "client message
format error" response, which would misreport a resolver author's bug
as a malformed client message."""
def test_not_a_runtime_error(self):
assert not issubclass(ExecutionScopeResolverContractError, RuntimeError)
def test_not_a_value_error(self):
assert not issubclass(ExecutionScopeResolverContractError, ValueError)
def test_not_a_type_error(self):
assert not issubclass(ExecutionScopeResolverContractError, TypeError)
def test_not_a_key_error(self):
assert not issubclass(ExecutionScopeResolverContractError, KeyError)
def test_is_a_plain_exception(self):
assert issubclass(ExecutionScopeResolverContractError, Exception)
class TestExecutionScopeShapeVersionAlignment:
"""``to_dict``'s key set must track every dataclass field (precedent:
test_runtime_spec.py:315) so a newly added field cannot silently miss
persistence -- which would make a historical snapshot indistinguishable
from a current one that simply left the field at its default."""
def test_to_dict_keys_match_dataclass_fields(self):
field_names = {f.name for f in dataclasses.fields(ExecutionScope)}
assert set(ExecutionScope().to_dict().keys()) == field_names
def test_fresh_scope_is_current_version(self):
assert ExecutionScope().version == EXECUTION_SCOPE_SHAPE_VERSION
def test_from_dict_missing_version_defaults_to_legacy_zero(self):
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
del data["version"]
assert ExecutionScope.from_dict(data).version == 0
def test_from_dict_string_version_is_coerced_to_int(self):
"""A JSON-decoded snapshot carries ``version`` as whatever type the
wire format gave it; ``from_dict`` must coerce it to ``int`` so a
stringly-typed ``"1"`` still compares equal to
``EXECUTION_SCOPE_SHAPE_VERSION`` in ``resolve_execution_scope``
instead of being silently treated as a shape mismatch."""
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
data["version"] = str(EXECUTION_SCOPE_SHAPE_VERSION)
decoded = ExecutionScope.from_dict(data)
assert decoded.version == EXECUTION_SCOPE_SHAPE_VERSION
assert isinstance(decoded.version, int)
def test_version_is_excluded_from_equality(self):
current = ExecutionScope(sandbox_key_suffix="x")
legacy_data = current.to_dict()
legacy_data["version"] = 0
legacy = ExecutionScope.from_dict(legacy_data)
assert legacy.version == 0
assert legacy == current
def test_to_dict_stamps_current_version_even_from_a_stale_scope(self):
"""``to_dict()`` always stamps :data:`EXECUTION_SCOPE_SHAPE_VERSION`,
never ``self.version``: the dict it returns is being built *now*, in
the current shape, regardless of whether ``self`` was itself decoded
from an older snapshot (stale ``.version``). Propagating that stale
value would let a decoded-then-re-persisted scope masquerade as
pre-dating fields it actually has, permanently ignoring it as a
candidate in ``resolve_execution_scope``."""
stale_data = ExecutionScope(sandbox_key_suffix="x").to_dict()
stale_data["version"] = 0
stale_scope = ExecutionScope.from_dict(stale_data)
assert stale_scope.version == 0
assert stale_scope.to_dict()["version"] == EXECUTION_SCOPE_SHAPE_VERSION
def test_shape_version_bump_requires_touching_this_pin(self):
"""Pins the exact field set ``EXECUTION_SCOPE_SHAPE_VERSION`` == 1
was cut for. A namespace-affecting field can be added --
wired into ``to_dict``/``from_dict``/
``_EXECUTION_SCOPE_NAMESPACE_FIELDS``/``scope_fingerprint`` -- and
pass the rest of the suite without bumping the shape version, which
would make every already-persisted snapshot compare against a wider
shape it never had a chance to opt into, and
``resolve_execution_scope`` would fail every turn touching one until
the version is bumped. This test forces the field set to be
re-affirmed (and the version bumped) on the next field addition
instead of drifting unnoticed."""
field_names = {f.name for f in dataclasses.fields(ExecutionScope)}
assert field_names == {
"sandbox_key_suffix",
"workspace_segments",
"sandbox_mount_segments",
"memory_dimensions",
"strict_memory_isolation",
"isolate_external_dirs",
"version",
}
assert EXECUTION_SCOPE_SHAPE_VERSION == 1
class TestFromDictUntrustedFieldCoercion:
"""``from_dict`` decodes a mapping that can originate in a
client-influenceable ``Task.agent_config`` (see
:data:`EXECUTION_SCOPE_AGENT_CONFIG_KEY`), so every field it reads must
be coerced defensively -- never a raw ``int()``/``tuple()``/``dict()``
call that can raise a bare stdlib error (swallowed by generic ``except
(ValueError, KeyError, TypeError)`` handlers elsewhere) or silently
misread/truncate the value.
"""
# --- version: readable, or a malformed-snapshot fault -----------------
#
# ``0`` is the marker for an authentic snapshot written before the field
# existed, and that marker is trusted: the older half of the shape-version
# gate is relaxed on the ``snapshot_defines_namespace=True`` branch, where
# such a snapshot's namespace fields are used verbatim. An unreadable
# value must therefore not decode to it.
@pytest.mark.parametrize(
"raw_version", ["abc", {"a": 1}, [1], object(), 1.5, True, -5]
)
def test_from_dict_unreadable_version_raises_instead_of_claiming_legacy(
self, raw_version
):
"""Every shape that is not a readable version is a malformed persisted
snapshot, not an old one. ``1.5`` and ``True`` are here because a bare
``int()`` turns them into ``1`` -- a claim to be the current shape --
and ``-5`` because "older than every version that ever existed" would
borrow the legacy marker's verbatim-namespace trust for a value no
writer emits (``to_dict`` always stamps the current constant)."""
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
data["version"] = raw_version
with pytest.raises(ExecutionScopeResolverContractError):
ExecutionScope.from_dict(data)
def test_from_dict_unreadable_version_is_not_a_client_message_fault(self):
"""The error stays outside ``(ValueError, KeyError, TypeError)``: the
websocket handlers that catch that tuple around the turn path would
otherwise answer the client with a message-format validation error for
what is a persisted-data fault."""
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
data["version"] = "abc"
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
ExecutionScope.from_dict(data)
assert not isinstance(exc_info.value, _WEBSOCKET_VALIDATION_EXCEPT_TUPLE)
def test_from_dict_unreadable_version_message_names_no_value(self):
"""The raised message reaches the task's error column and a
client-facing event, so it names the offending type only; the value
goes to the server-side log."""
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
data["version"] = "9;DROP"
with scope_log_records(logging.ERROR) as records:
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
ExecutionScope.from_dict(data)
assert "9;DROP" not in str(exc_info.value)
assert "str" in str(exc_info.value)
assert any("9;DROP" in r for r in records), records
def test_from_dict_readable_versions_are_accepted(self):
"""The accepted domain: an absent key or ``None`` is the pre-versioning
marker, a digit string is what a JSON-decoded version can arrive as,
and a non-negative ``int`` passes through. Nothing here may raise --
an old snapshot is a supported input, not a fault."""
for raw, expected in ((None, 0), ("0", 0), ("1", 1), (0, 0), (1, 1), (9, 9)):
data = ExecutionScope(sandbox_key_suffix="x").to_dict()
data["version"] = raw
decoded = ExecutionScope.from_dict(data)
assert decoded.version == expected
assert isinstance(decoded.version, int)
missing = ExecutionScope(sandbox_key_suffix="x").to_dict()
del missing["version"]
assert ExecutionScope.from_dict(missing).version == 0
# --- workspace_segments / sandbox_mount_segments: no silent str/dict
# iteration, no bare TypeError on a non-iterable ----------------------
def test_from_dict_string_workspace_segments_raises_instead_of_splitting_chars(
self,
):
"""``tuple("ab")`` would silently become ``("a", "b")`` -- two valid-
looking single-character segments that pass per-segment validation
with no signal that the input was never a sequence."""
data = ExecutionScope().to_dict()
data["workspace_segments"] = "ab"
with pytest.raises(InvalidScopeComponentError):
ExecutionScope.from_dict(data)
def test_from_dict_non_iterable_workspace_segments_raises_domain_error(self):
"""``tuple(5)`` raises a bare ``TypeError`` outside this module's
error taxonomy; the coercion guard must raise
``InvalidScopeComponentError`` before reaching that call."""
data = ExecutionScope().to_dict()
data["workspace_segments"] = 5
with pytest.raises(InvalidScopeComponentError):
ExecutionScope.from_dict(data)
def test_from_dict_falsy_workspace_segments_still_defaults_to_empty(self):
"""Falsy-but-absent-shaped values (``None``, ``""``, ``0``, ``False``)
keep meaning "no segments supplied" rather than becoming a coercion
error -- only a truthy non-sequence is a real contract violation."""
for raw in (None, "", 0, False, []):
data = ExecutionScope().to_dict()
data["workspace_segments"] = raw
assert ExecutionScope.from_dict(data).workspace_segments == ()
def test_from_dict_string_sandbox_mount_segments_raises(self):
data = ExecutionScope(workspace_segments=("a", "b")).to_dict()
data["sandbox_mount_segments"] = "ab"
with pytest.raises(InvalidScopeComponentError):
ExecutionScope.from_dict(data)
def test_from_dict_none_sandbox_mount_segments_stays_none_not_coerced(self):
"""``None`` is a load-bearing sentinel (mount == full
workspace_segments), distinct from an explicit ``[]`` (rooted
mount) -- the coercion guard must preserve that distinction rather
than routing ``None`` through the same falsy-default path as
``workspace_segments``."""
data = ExecutionScope(workspace_segments=("a", "b")).to_dict()
assert data["sandbox_mount_segments"] is None
assert ExecutionScope.from_dict(data).sandbox_mount_segments is None
# --- memory_dimensions: no silent pair-splitting of a bad iterable ----
def test_from_dict_string_memory_dimensions_raises_instead_of_dict_of_chars(self):
"""``dict(["ab"])`` would silently reinterpret ``"ab"`` as the
key/value pair ``{"a": "b"}``."""
data = ExecutionScope().to_dict()
data["memory_dimensions"] = ["ab"]
with pytest.raises(InvalidScopeComponentError):
ExecutionScope.from_dict(data)
def test_from_dict_non_mapping_memory_dimensions_raises_domain_error(self):
data = ExecutionScope().to_dict()
data["memory_dimensions"] = 5
with pytest.raises(InvalidScopeComponentError):
ExecutionScope.from_dict(data)
def test_from_dict_falsy_memory_dimensions_still_defaults_to_empty(self):
for raw in (None, "", 0, False, {}):
data = ExecutionScope().to_dict()
data["memory_dimensions"] = raw
assert dict(ExecutionScope.from_dict(data).memory_dimensions) == {}
# The tuple several websocket handlers wrap around the turn-execution path,
# including its per-turn ``resolve_execution_scope`` call. Anything in it is
# answered to the client as a message-format validation error, so an exception
# that is *not* about the client's message must fall through it.
_WEBSOCKET_VALIDATION_EXCEPT_TUPLE = (ValueError, KeyError, TypeError)
class TestPersistedSnapshotDecodeIsNotAClientMessageFault:
"""A persisted snapshot that no longer decodes is a persisted-data fault.
``execution_scope_from_agent_config`` is where persisted snapshot data is
read, and the registered snapshot loaders call it from inside
``resolve_execution_scope``. The field coercions it drives raise
``InvalidScopeComponentError``, which is a ``ValueError`` -- so without a
boundary conversion the failure lands in the websocket handlers'
``except (ValueError, KeyError, TypeError)`` clause and the client is told
its own message was malformed, for data it may not have sent and cannot
fix. The ``version`` field reaches the same conclusion one step earlier:
``_coerce_snapshot_version`` raises the contract error itself, so an
unreadable version leaves this boundary as the same class the field
coercions are converted into here.
``InvalidScopeComponentError``'s own bases are deliberately left alone: it
is also raised for live, caller-supplied components (``workspace.py``,
``sandbox_keys.py``), where being a ``ValueError`` is correct and is what
surrounding handlers already expect.
"""
MALFORMED_AGENT_CONFIG = {"execution_scope": {"workspace_segments": 5}}
def _loader(self, task_id):
return execution_scope_from_agent_config(self.MALFORMED_AGENT_CONFIG)
def test_direct_decode_raises_the_contract_error(self):
with pytest.raises(ExecutionScopeResolverContractError):
execution_scope_from_agent_config(self.MALFORMED_AGENT_CONFIG)
def test_decode_failure_chains_the_underlying_validation_error(self):
"""The conversion must not lose the diagnosis: the coercion error is
kept as ``__cause__`` (and its field-level detail is logged where it
was raised), so the boundary type costs nothing in debuggability."""
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
execution_scope_from_agent_config(self.MALFORMED_AGENT_CONFIG)
assert isinstance(exc_info.value.__cause__, InvalidScopeComponentError)
def test_decode_failure_message_names_no_snapshot_value(self):
"""The message travels further than the log does, and a snapshot's
segments can carry end-user identifiers."""
agent_config = {
"execution_scope": {"workspace_segments": "tenant-secret-identifier"}
}
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
execution_scope_from_agent_config(agent_config)
assert "tenant-secret-identifier" not in str(exc_info.value)
def test_not_folded_on_the_no_resolver_path(self):
set_execution_scope_snapshot_loader(self._loader)
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
resolve_execution_scope("1")
assert not isinstance(exc_info.value, _WEBSOCKET_VALIDATION_EXCEPT_TUPLE)
def test_not_folded_on_the_resolver_abstention_path(self):
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(ExecutionScope()),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(self._loader)
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
resolve_execution_scope("1")
assert not isinstance(exc_info.value, _WEBSOCKET_VALIDATION_EXCEPT_TUPLE)
def test_unreadable_version_decode_is_not_folded_either(self):
"""The ``version`` field takes the shorter route -- it raises the
contract error directly rather than being converted here -- so this
pins that the boundary hands out the same class for it, and that an
unreadable version fails the decode instead of being read as a legacy
snapshot."""
agent_config = {"execution_scope": {"version": "not-a-version"}}
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
execution_scope_from_agent_config(agent_config)
assert not isinstance(exc_info.value, _WEBSOCKET_VALIDATION_EXCEPT_TUPLE)
def test_live_component_validation_is_still_a_value_error(self):
"""The counterpart the boundary conversion must not disturb: a
component validated for a caller right now (not read back from
storage) still raises the ``ValueError`` subclass its own callers
catch."""
assert issubclass(InvalidScopeComponentError, ValueError)
with pytest.raises(InvalidScopeComponentError):
ExecutionScope(sandbox_key_suffix="not:valid")
class TestResolverContractErrorMessageIsClientSafe:
"""``ExecutionScopeResolverContractError``'s message reaches a generic
handler and can surface to the client, exactly like
``ExecutionScopeAuthorityError``'s (which is pinned to task id + field
names by ``test_str_carries_task_id_and_field_names_never_values``). A
resolver or loader bug that returns an internal object must therefore not
publish that object's ``repr()``; the message names its *type* and the
value goes only to the server-side log.
"""
class _InternalConfig:
"""Stands in for whatever an embedder's resolver might wrongly return."""
def __repr__(self) -> str:
return "<InternalConfig token='resolver-secret-token'>"
def test_resolver_return_type_error_names_the_type_not_the_value(self):
offender = self._InternalConfig()
set_execution_scope_resolver(
lambda task_id: offender, acknowledges_snapshot_candidate_contract=True
)
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
resolve_execution_scope("1")
message = str(exc_info.value)
assert "resolver-secret-token" not in message
assert "_InternalConfig" in message
def test_snapshot_type_error_names_the_type_not_the_value(self):
offender = self._InternalConfig()
set_execution_scope_resolver(
lambda task_id: ExecutionScope(sandbox_key_suffix="from-resolver"),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: offender)
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
resolve_execution_scope("1")
message = str(exc_info.value)
assert "resolver-secret-token" not in message
assert "_InternalConfig" in message
class TestSnapshotCandidateAuthority:
"""Full resolver x snapshot precedence matrix (#296).
Axes: resolver registered x (ExecutionScope / None / DeferToSnapshot) x
(snapshot equal / namespace-differing / policy-only-differing / absent /
stale-version / loader-broken). Plus the "no resolver registered" golden
(unchanged from the resolver-less contract) and the resolver-exception
short-circuit.
"""
RESOLVER_SCOPE = ExecutionScope(sandbox_key_suffix="from-resolver")
def _register(self, resolver, loader=None):
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
if loader is not None:
set_execution_scope_snapshot_loader(loader)
# --- resolver returns None: authoritative unscoped -------------------
def test_resolver_none_is_authoritative_unscoped_even_with_snapshot(self):
loader_calls = []
def loader(task_id):
loader_calls.append(task_id)
return self.RESOLVER_SCOPE
self._register(lambda task_id: None, loader)
assert resolve_execution_scope("1") is None
assert loader_calls == [] # None short-circuits before the snapshot
def test_resolver_none_logs_that_it_de_scoped_the_task(self):
"""De-scoping a task must leave a trace, like every other branch that
overrides or ignores a candidate. A resolver that does not yet
recognise older tasks returns ``None`` for all of them, and without
this line every one of those turns runs unscoped -- possibly past a
persisted snapshot that named a namespace -- with nothing in the log
to show it happened.
``INFO``, because the resolver is exercising its contract rather than
failing, and the line says the snapshot was bypassed *unread*: this
branch deliberately never calls the loader, which the assertion below
pins so the wording cannot drift into claiming knowledge of whether a
snapshot exists."""
loader_calls = []
def loader(task_id):
loader_calls.append(task_id)
return self.RESOLVER_SCOPE
self._register(lambda task_id: None, loader)
with scope_log_records(logging.INFO) as records:
assert resolve_execution_scope("task-7") is None
assert loader_calls == []
assert any(
"task-7" in r and "None" in r and "snapshot" in r for r in records
), records
# --- resolver returns ExecutionScope -----------------------------------
def test_resolver_scope_with_no_snapshot(self):
self._register(lambda task_id: self.RESOLVER_SCOPE, lambda task_id: None)
assert resolve_execution_scope("1") == self.RESOLVER_SCOPE
def test_resolver_scope_with_equal_snapshot_corroborates_silently(self):
self._register(
lambda task_id: self.RESOLVER_SCOPE, lambda task_id: self.RESOLVER_SCOPE
)
assert resolve_execution_scope("1") == self.RESOLVER_SCOPE
def test_mount_authority_compares_effective_value_not_raw_field(self):
"""A resolver-built scope that leaves the mount at its default
(``None``, meaning the full ``workspace_segments``) and a snapshot
that explicitly repeats those same segments as its mount select the
identical mount -- only the raw ``sandbox_mount_segments`` attribute
differs (``None`` vs. an explicit tuple), not the namespace value.
Comparing the raw attribute here would be a false-positive authority
conflict: a client-supplied snapshot that happens to spell out the
workspace segments as its mount must not fail an otherwise-identical
turn. A snapshot whose mount genuinely covers different segments
must still raise."""
resolver_scope = ExecutionScope(workspace_segments=("a",))
same_effective_mount_snapshot = ExecutionScope(
workspace_segments=("a",), sandbox_mount_segments=("a",)
)
self._register(
lambda task_id: resolver_scope,
lambda task_id: same_effective_mount_snapshot,
)
assert resolve_execution_scope("1") == resolver_scope
different_effective_mount_snapshot = ExecutionScope(
workspace_segments=("a", "b"), sandbox_mount_segments=("a",)
)
self._register(
lambda task_id: ExecutionScope(workspace_segments=("a", "b")),
lambda task_id: different_effective_mount_snapshot,
)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert "sandbox_mount_segments" in exc_info.value.mismatched_fields
@pytest.mark.parametrize(
"field_name,resolver_kwargs,snapshot_kwargs",
[
("sandbox_key_suffix", {}, {"sandbox_key_suffix": "other"}),
# workspace_segments alone would also move the *effective* mount
# (``None`` means "the full segments"), reporting two fields; both
# sides pin the mount at the user root so only the segments vary.
(
"workspace_segments",
{"workspace_segments": ("a",), "sandbox_mount_segments": ()},
{"workspace_segments": ("b",), "sandbox_mount_segments": ()},
),
(
"sandbox_mount_segments",
{
"workspace_segments": ("a", "b"),
"sandbox_mount_segments": ("a", "b"),
},
{
"workspace_segments": ("a", "b"),
"sandbox_mount_segments": ("a",),
},
),
("memory_dimensions", {}, {"memory_dimensions": {"k": "v"}}),
("isolate_external_dirs", {}, {"isolate_external_dirs": True}),
],
)
def test_namespace_field_mismatch_fails_the_turn(
self, field_name, resolver_kwargs, snapshot_kwargs
):
"""Each case varies exactly one namespace field, so the reported
mismatch set pins that field alone rather than merely containing it --
a diff loop that dropped a field would otherwise still pass on a case
whose second, incidentally-varied field kept the set non-empty."""
resolver_scope = ExecutionScope(**resolver_kwargs)
snapshot_scope = ExecutionScope(**snapshot_kwargs)
self._register(lambda task_id: resolver_scope, lambda task_id: snapshot_scope)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert set(exc_info.value.mismatched_fields) == {field_name}
assert exc_info.value.resolver_scope == resolver_scope
assert exc_info.value.snapshot_scope == snapshot_scope
def test_namespace_mismatch_error_omits_a_concurrently_differing_policy_field(
self,
):
"""The raise is gated on the namespace diff alone being non-empty,
but strict_memory_isolation (policy) also differs here. The
exception reaches task.error_message and a client-facing event, so
mismatched_fields must carry only the namespace disagreement --
listing the policy field there would misleadingly present it as
part of the conflict that failed the turn."""
resolver_scope = ExecutionScope(strict_memory_isolation=False)
snapshot_scope = ExecutionScope(
sandbox_key_suffix="other", strict_memory_isolation=True
)
self._register(lambda task_id: resolver_scope, lambda task_id: snapshot_scope)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert set(exc_info.value.mismatched_fields) == {"sandbox_key_suffix"}
assert "strict_memory_isolation" not in exc_info.value.mismatched_fields
def test_policy_only_mismatch_does_not_fail_the_turn(self):
"""strict_memory_isolation is a policy field: a disagreement there
does not change which key/path is touched, so the resolver's value
wins without raising. The disagreement must still be observable --
a silently-won policy mismatch would otherwise be undebuggable."""
resolver_scope = ExecutionScope(strict_memory_isolation=False)
snapshot_scope = ExecutionScope(strict_memory_isolation=True)
self._register(lambda task_id: resolver_scope, lambda task_id: snapshot_scope)
with scope_log_records() as records:
assert resolve_execution_scope("1") == resolver_scope
assert any(
"policy-only mismatch" in r and "strict_memory_isolation" in r
for r in records
)
def test_stale_version_snapshot_is_ignored_even_if_it_would_mismatch(self):
resolver_scope = ExecutionScope()
stale_data = ExecutionScope(sandbox_key_suffix="stale").to_dict()
del stale_data["version"] # predates EXECUTION_SCOPE_SHAPE_VERSION
stale_snapshot = ExecutionScope.from_dict(stale_data)
assert stale_snapshot.version == 0
self._register(lambda task_id: resolver_scope, lambda task_id: stale_snapshot)
with scope_log_records() as records:
assert resolve_execution_scope("1") == resolver_scope
assert any("shape" in r and "sandbox_key_suffix" in r for r in records)
def test_newer_version_snapshot_is_ignored_too(self):
"""A mixed-version rollout can also see a snapshot stamped by a
*newer* process than this one (e.g. during a rolling deploy where
some workers already run the next shape). ``!=`` (not ``<``) covers
this direction too: the snapshot's shape can't be safely compared
field-by-field against a scope built under a different shape,
regardless of which side is newer."""
resolver_scope = ExecutionScope()
newer_data = ExecutionScope(sandbox_key_suffix="from-the-future").to_dict()
newer_data["version"] = EXECUTION_SCOPE_SHAPE_VERSION + 1
newer_snapshot = ExecutionScope.from_dict(newer_data)
self._register(lambda task_id: resolver_scope, lambda task_id: newer_snapshot)
assert resolve_execution_scope("1") == resolver_scope
def test_broken_snapshot_loader_does_not_veto_resolver_scope(self):
def boom(task_id):
raise RuntimeError("db down")
self._register(lambda task_id: self.RESOLVER_SCOPE, boom)
assert resolve_execution_scope("1") == self.RESOLVER_SCOPE
def test_snapshot_wrong_type_raises_contract_error_not_attribute_error(self):
"""A snapshot loader is held to the same return-type discipline as
the resolver. Without the shared validation funnel, a non-scope
candidate would reach the ``.version`` comparison below and raise a
bare, undiagnosable ``AttributeError`` instead."""
self._register(
lambda task_id: self.RESOLVER_SCOPE,
lambda task_id: {"not": "a scope"},
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope("1")
# --- resolver returns DeferToSnapshot -----------------------------------
def test_defer_uses_snapshot_when_present(self):
"""A snapshot that narrows a *scoped* fallback (not an all-default
one -- see TestDeferSnapshotAllDefaultFallback below) is used as-is.
Namespace and policy fields are varied independently elsewhere
(test_defer_snapshot_policy_only_disagreement_fallback_wins) so this
case stays a clean single-variable proof of "narrowing snapshot
wins"."""
fallback = ExecutionScope(workspace_segments=("tenant-a",))
snapshot_scope = ExecutionScope(workspace_segments=("tenant-a", "sub"))
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot_scope,
)
assert resolve_execution_scope("1") == snapshot_scope
def test_defer_snapshot_policy_only_disagreement_fallback_wins(self):
"""On the abstention branch, the namespace fields agree (both
all-default -- no narrowing violation), but
strict_memory_isolation differs. The fallback plays the
authoritative role here, so its policy value must win, logged, the
same way the resolver's policy value wins on the authoritative
branch (test_policy_only_mismatch_does_not_fail_the_turn above)."""
fallback = ExecutionScope(strict_memory_isolation=True)
snapshot_scope = ExecutionScope(strict_memory_isolation=False)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot_scope,
)
with scope_log_records() as records:
result = resolve_execution_scope("1")
assert result.strict_memory_isolation is True
assert result.sandbox_key_suffix is None
assert any(
"policy-only mismatch" in r and "strict_memory_isolation" in r
for r in records
)
def test_defer_policy_overlay_keeps_the_snapshot_narrowed_namespace(self):
"""The policy overlay must be applied *onto the snapshot*, not
satisfied by returning the fallback. Here the snapshot legitimately
narrows the fallback's namespace and also disagrees on policy: both
halves have to survive, so the resolved scope is the snapshot's
namespace carrying the fallback's policy value. Returning
``fallback`` instead would silently throw the narrowing away, which
every all-default-namespace policy test is blind to."""
fallback = ExecutionScope(
workspace_segments=("tenant-a",), strict_memory_isolation=True
)
snapshot_scope = ExecutionScope(
workspace_segments=("tenant-a", "sub"), strict_memory_isolation=False
)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot_scope,
)
result = resolve_execution_scope("1")
assert result.workspace_segments == ("tenant-a", "sub")
assert result.strict_memory_isolation is True
def test_defer_every_policy_field_is_taken_from_the_fallback(self, monkeypatch):
"""Generic over ``_EXECUTION_SCOPE_POLICY_FIELDS``: the abstention
branch must compare and carry over every field the table lists, not a
field it names literally. With one policy field in production those
two implementations are indistinguishable, so this reclassifies a
second real field into the policy bucket for the duration of the test
and checks that it is honoured too.
"""
from xagent.core import execution_scope as scope_module
borrowed = "isolate_external_dirs"
monkeypatch.setattr(
scope_module,
"_EXECUTION_SCOPE_NAMESPACE_FIELDS",
tuple(
name
for name in scope_module._EXECUTION_SCOPE_NAMESPACE_FIELDS
if name != borrowed
),
)
monkeypatch.setattr(
scope_module,
"_EXECUTION_SCOPE_POLICY_FIELDS",
scope_module._EXECUTION_SCOPE_POLICY_FIELDS + (borrowed,),
)
policy_fields = scope_module._EXECUTION_SCOPE_POLICY_FIELDS
assert len(policy_fields) > 1
fallback = ExecutionScope(strict_memory_isolation=True, **{borrowed: True})
snapshot_scope = ExecutionScope(
strict_memory_isolation=False, **{borrowed: False}
)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot_scope,
)
with scope_log_records() as records:
result = resolve_execution_scope("1")
for name in policy_fields:
assert getattr(result, name) == getattr(fallback, name), name
assert any("policy-only mismatch" in r and name in r for r in records), name
def test_defer_current_shape_version_snapshot_is_used_not_shape_gated(self):
"""The positive mirror of
test_defer_stale_version_snapshot_is_ignored_falls_back: a snapshot
carrying the current shape version (as a real persisted snapshot
would, round-tripped through to_dict/from_dict) is not shape-gated
away and is used when it narrows the fallback."""
fallback = ExecutionScope(workspace_segments=("tenant-a",))
snapshot_data = ExecutionScope(workspace_segments=("tenant-a", "sub")).to_dict()
assert snapshot_data["version"] == EXECUTION_SCOPE_SHAPE_VERSION
snapshot_scope = ExecutionScope.from_dict(snapshot_data)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot_scope,
)
assert resolve_execution_scope("1") == snapshot_scope
def test_defer_uses_fallback_when_snapshot_absent(self):
fallback = ExecutionScope(strict_memory_isolation=True)
self._register(lambda task_id: DeferToSnapshot(fallback), lambda task_id: None)
assert resolve_execution_scope("1") == fallback
def test_defer_loader_exception_propagates(self):
"""Unlike the authoritative branch (``test_broken_snapshot_loader_
does_not_veto_resolver_scope`` above), a broken loader here must fail
the turn: the resolver has just said it does not know this task's
scope, so a broken candidate means nobody knows, and turn faces that
reach this branch must fail closed rather than silently proceed
under a possibly-wrong fallback."""
def boom(task_id):
raise RuntimeError("db down")
fallback = ExecutionScope(strict_memory_isolation=True)
self._register(lambda task_id: DeferToSnapshot(fallback), boom)
with pytest.raises(RuntimeError, match="db down"):
resolve_execution_scope("1")
def test_defer_snapshot_wrong_type_raises_contract_error(self):
"""A snapshot loader is held to the same return-type discipline as
the resolver: it must return an ExecutionScope or None."""
fallback = ExecutionScope(strict_memory_isolation=True)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: {"not": "a scope"},
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope("1")
def test_defer_snapshot_carrier_from_loader_raises_contract_error(self):
"""A loader returning a DeferToSnapshot (instead of an actual
snapshot) is exactly as invalid as a raw dict -- both fail the same
isinstance(ExecutionScope) gate."""
fallback = ExecutionScope(strict_memory_isolation=True)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: DeferToSnapshot(ExecutionScope()),
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope("1")
def test_defer_stale_version_snapshot_is_ignored_falls_back(self):
fallback = ExecutionScope(sandbox_key_suffix="fallback")
stale_data = ExecutionScope(sandbox_key_suffix="stale").to_dict()
del stale_data["version"]
stale_snapshot = ExecutionScope.from_dict(stale_data)
assert stale_snapshot.version == 0
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: stale_snapshot,
)
with scope_log_records() as records:
assert resolve_execution_scope("1") == fallback
assert any("shape" in r and "sandbox_key_suffix" in r for r in records)
@pytest.mark.parametrize(
"field_name,fallback_kwargs,snapshot_kwargs",
[
(
"sandbox_key_suffix",
{"sandbox_key_suffix": "fallback-suffix"},
{"sandbox_key_suffix": "different-suffix"},
),
(
"workspace_segments",
{"workspace_segments": ("tenant-a", "b")},
{"workspace_segments": ("tenant-a",)},
),
(
"sandbox_mount_segments",
{
"workspace_segments": ("tenant-a", "b", "c"),
"sandbox_mount_segments": ("tenant-a", "b", "c"),
},
{
"workspace_segments": ("tenant-a", "b", "c"),
"sandbox_mount_segments": ("tenant-a",),
},
),
(
"isolate_external_dirs",
{"isolate_external_dirs": True},
{"isolate_external_dirs": False},
),
(
"memory_dimensions",
{"memory_dimensions": {"k": "v"}},
{"memory_dimensions": {}},
),
# All-default fallback: the resolver has claimed no authority in
# any dimension, so introducing scoping the fallback never
# committed to is rejected even though, taken alone, it would
# look like a narrowing (null -> set; False -> True). See
# TestDeferSnapshotAllDefaultFallback for the case that varies
# every field of such a fallback at once.
("sandbox_key_suffix", {}, {"sandbox_key_suffix": "attacker-chosen"}),
("isolate_external_dirs", {}, {"isolate_external_dirs": True}),
],
)
def test_defer_snapshot_widening_fallback_fails_the_turn(
self, field_name, fallback_kwargs, snapshot_kwargs
):
"""A snapshot that is *wider* than the resolver's mandatory fallback
on any namespace field must fail the turn: the snapshot remains
untrusted input even though request bodies can no longer seed it --
a runtime-extension provider holding a ``session_factory`` can write
``Task.agent_config`` directly, and a row persisted before
``execution_scope`` was reserved at the request boundary still
carries whatever a request seeded at the time -- so an unchecked
snapshot here would let a caller widen its own namespace past the
resolver's own most conservative answer."""
fallback = ExecutionScope(**fallback_kwargs)
snapshot = ExecutionScope(**snapshot_kwargs)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot,
)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert field_name in exc_info.value.mismatched_fields
assert exc_info.value.resolver_scope == fallback
assert exc_info.value.snapshot_scope == snapshot
@pytest.mark.parametrize(
"fallback_kwargs,snapshot_kwargs",
[
(
{"workspace_segments": ("tenant-a",)},
{"workspace_segments": ("tenant-a", "sub")},
),
(
{
"workspace_segments": ("tenant-a", "b", "c"),
"sandbox_mount_segments": ("tenant-a",),
},
{
"workspace_segments": ("tenant-a", "b", "c"),
"sandbox_mount_segments": ("tenant-a", "b"),
},
),
(
{"memory_dimensions": {"k": "v"}},
{"memory_dimensions": {"k": "v", "k2": "v2"}},
),
(
{"sandbox_key_suffix": "same"},
{"sandbox_key_suffix": "same"},
),
],
)
def test_defer_snapshot_narrowing_fallback_is_accepted(
self, fallback_kwargs, snapshot_kwargs
):
"""The mirror of the widening cases above: a snapshot that only
extends scoping the fallback already committed to (a deeper
workspace path, a deeper mount prefix within one, or extra memory
dimensions) is accepted and used as the resolved scope. Every case
here has a non-default fallback for the field under test -- see
TestDeferSnapshotAllDefaultFallback for why an all-default fallback
accepts nothing but an equal snapshot instead."""
fallback = ExecutionScope(**fallback_kwargs)
snapshot = ExecutionScope(**snapshot_kwargs)
self._register(
lambda task_id: DeferToSnapshot(fallback),
lambda task_id: snapshot,
)
assert resolve_execution_scope("1") == snapshot
# --- boundary judgment / resolver misbehavior ---------------------------
def test_resolver_returning_unexpected_type_raises_contract_error(self):
self._register(lambda task_id: "not-a-scope")
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope("1")
def test_resolver_exception_short_circuits_before_the_snapshot(self):
loader_calls = []
def boom(task_id):
raise RuntimeError("resolver down")
self._register(boom, lambda task_id: loader_calls.append(task_id))
with pytest.raises(RuntimeError, match="resolver down"):
resolve_execution_scope("1")
assert loader_calls == []
# --- no resolver registered: golden: unchanged resolver-less contract --------
def test_no_resolver_registered_snapshot_alone_drives(self):
set_execution_scope_snapshot_loader(lambda task_id: self.RESOLVER_SCOPE)
assert resolve_execution_scope("1") == self.RESOLVER_SCOPE
def test_no_resolver_registered_no_snapshot_is_unscoped(self):
assert resolve_execution_scope("1") is None
def test_no_resolver_registered_loader_exception_propagates(self):
def boom(task_id):
raise RuntimeError("db down")
set_execution_scope_snapshot_loader(boom)
with pytest.raises(RuntimeError, match="db down"):
resolve_execution_scope("1")
def test_no_resolver_registered_stale_version_snapshot_is_used_as_is(self):
"""The no-resolver branch returns whatever the loader returns
directly (see resolve_execution_scope's ``if
_execution_scope_resolver is None`` branch) -- it never routes
through ``_validate_execution_scope_snapshot_candidate``, so a
stale-shape snapshot is not shape-gated here the way it is on the
other two branches. This pins that pre-existing, byte-identical-to-
pre-authority behavior; it is not a new contract."""
stale_data = ExecutionScope(sandbox_key_suffix="stale").to_dict()
del stale_data["version"]
stale_snapshot = ExecutionScope.from_dict(stale_data)
assert stale_snapshot.version == 0
set_execution_scope_snapshot_loader(lambda task_id: stale_snapshot)
assert resolve_execution_scope("1") == stale_snapshot
def test_no_resolver_registered_non_scope_loader_output_passes_through(self):
"""Same branch, same absence of validation: a loader returning
something other than an ExecutionScope is not caught here (unlike
the resolver-registered branches, which route every loaded
candidate through ``_validate_execution_scope_snapshot_candidate``
and raise ExecutionScopeResolverContractError for exactly this
input). Pinned as a known, pre-existing gap on this branch rather
than asserted correct."""
set_execution_scope_snapshot_loader(lambda task_id: {"not": "a scope"})
assert resolve_execution_scope("1") == {"not": "a scope"}
class TestDeferSnapshotAllDefaultFallback:
"""A namespace field sitting at its own identity default admits no
narrowing, only an exact match: there is no scoping there for a snapshot
to narrow into.
This is what a purely relative per-field test cannot express. Evaluated
only against the fallback's own value, every narrowing relation is
vacuously satisfied once that value is the field's no-scoping default --
so an all-default ``ExecutionScope()`` fallback, the natural value for a
resolver with no opinion on a task, would accept any snapshot at all.
"""
def test_all_default_fallback_rejects_a_snapshot_widening_every_field_at_once(
self,
):
"""The worst case for a vacuous predicate: a fully unscoped fallback
plus a snapshot that sets every namespace field simultaneously. Every
field is out-of-authority for this fallback, so all five must be
reported."""
fallback = ExecutionScope()
snapshot = ExecutionScope(
sandbox_key_suffix="attacker-chosen",
workspace_segments=("other", "tenant"),
sandbox_mount_segments=("other", "tenant"),
isolate_external_dirs=True,
memory_dimensions={"tenant": "other"},
)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert set(exc_info.value.mismatched_fields) == {
"sandbox_key_suffix",
"workspace_segments",
"sandbox_mount_segments",
"isolate_external_dirs",
"memory_dimensions",
}
def test_all_default_fallback_accepts_an_equal_snapshot(self):
"""The permissive half: an all-default snapshot introduces no scoping,
so it passes the identity rule and is what gets returned.
Asserted by identity, not equality: an all-default fallback and an
all-default snapshot compare equal, so ``== fallback`` would hold
whichever of the two the function returned -- and would keep holding
if the snapshot were rejected or shape-gated away. ``is snapshot``
distinguishes the accept path from both."""
fallback = ExecutionScope()
snapshot = ExecutionScope()
assert snapshot is not fallback
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
assert resolve_execution_scope("1") is snapshot
class TestDeferSnapshotDefinesNamespaceOptIn:
"""``DeferToSnapshot(fallback, snapshot_defines_namespace=True)``: the
resolver states it does not own this task and the persisted snapshot is
the intended namespace authority (the workforce/delegated-task shape).
A conforming ``fallback`` claims no namespace of its own -- if the
resolver knew the namespace it would return an authoritative
``ExecutionScope`` instead of deferring -- which is enforced at
construction, so the strict narrowing rule in
``TestDeferSnapshotAllDefaultFallback`` above has nothing left to protect
and is skipped for namespace fields here. Everything else still applies:
the type check, the mandatory fallback, policy symmetry, and the
newer-shape half of the version gate. Only the older-shape half is
relaxed, since this branch compares nothing.
"""
def test_opt_in_with_all_default_fallback_uses_snapshot_verbatim(self):
"""The workforce shape: the resolver has no opinion (all-default
fallback) but explicitly hands namespace authority to the snapshot."""
fallback = ExecutionScope()
snapshot = ExecutionScope(
sandbox_key_suffix="workforce-task",
workspace_segments=("workforce", "task-7"),
memory_dimensions={"tenant": "acme"},
)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
assert resolve_execution_scope("1") == snapshot
def test_without_opt_in_the_same_snapshot_fails_closed(self):
"""The security half: the identical snapshot/fallback pair, without
the opt-in, must still fail closed under the strict narrowing rule
-- the opt-in is what changes the outcome, not the snapshot shape."""
fallback = ExecutionScope()
snapshot = ExecutionScope(
sandbox_key_suffix="workforce-task",
workspace_segments=("workforce", "task-7"),
memory_dimensions={"tenant": "acme"},
)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert set(exc_info.value.mismatched_fields) == {
"sandbox_key_suffix",
"workspace_segments",
"sandbox_mount_segments",
"memory_dimensions",
}
def test_opt_in_accepts_an_older_shape_snapshot_and_keeps_its_data(self):
"""The older half of the asymmetric shape gate. Every field an
older-shape snapshot carries is decodable here and the ones it lacks
take current defaults, so the only thing its version breaks is a
field-by-field comparison -- and this branch performs none. Gating it
away would de-scope a workforce sub-task purely because its snapshot
predates the version field."""
fallback = ExecutionScope()
older_data = ExecutionScope(
sandbox_key_suffix="older", workspace_segments=("workforce", "task-7")
).to_dict()
del older_data["version"]
older_snapshot = ExecutionScope.from_dict(older_data)
assert older_snapshot.version == 0
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: older_snapshot)
assert resolve_execution_scope("1") == older_snapshot
def test_opt_in_still_refuses_a_newer_shape_snapshot(self):
"""The newer half, which the opt-in does *not* relax.
``from_dict`` drops keys this shape does not know, so a snapshot
written by a newer process arrives partially decoded -- possibly with
a namespace-narrowing field gone -- and "used verbatim" would mean
activating that truncated namespace. ``to_dict`` then stamps the
current constant, so accepting it would also re-persist the
truncation as if it were current."""
fallback = ExecutionScope()
newer_data = ExecutionScope(
sandbox_key_suffix="newer", workspace_segments=("workforce", "task-7")
).to_dict()
newer_data["version"] = EXECUTION_SCOPE_SHAPE_VERSION + 1
newer_data["a_field_this_shape_does_not_know"] = "dropped-on-decode"
newer_snapshot = ExecutionScope.from_dict(newer_data)
assert newer_snapshot.version == EXECUTION_SCOPE_SHAPE_VERSION + 1
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: newer_snapshot)
with scope_log_records() as records:
assert resolve_execution_scope("1") == fallback
assert any("shape" in r and "sandbox_key_suffix" in r for r in records)
def test_default_abstention_path_refuses_a_newer_shape_snapshot(self):
"""The same newer-shape refusal on the comparing abstention path,
where the fallback's own namespace is what the snapshot would have
had to narrow."""
fallback = ExecutionScope(workspace_segments=("tenant-a",))
newer_data = ExecutionScope(workspace_segments=("tenant-a", "sub")).to_dict()
newer_data["version"] = EXECUTION_SCOPE_SHAPE_VERSION + 1
newer_snapshot = ExecutionScope.from_dict(newer_data)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: newer_snapshot)
assert resolve_execution_scope("1") == fallback
def test_opt_in_still_type_gates_a_non_scope_snapshot(self):
"""The older-shape relaxation does not extend to the type check -- a
candidate that isn't even an ExecutionScope still raises, opt-in or
not."""
fallback = ExecutionScope()
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: object())
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope("1")
def test_opt_in_rejects_a_namespace_committed_fallback_at_construction(self):
"""The opt-in's precondition is machine-checked, not prose. This
branch hands the namespace to the snapshot verbatim, so a fallback
that already committed to one would have it *replaced* rather than
treated as a floor -- silent de-tenanting. A resolver that knows the
namespace must return an authoritative scope instead of deferring,
so the carrier refuses to exist."""
committed = ExecutionScope(
sandbox_key_suffix="tenant-a",
workspace_segments=("tenant-a",),
memory_dimensions={"tenant": "a"},
)
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
DeferToSnapshot(committed, snapshot_defines_namespace=True)
message = str(exc_info.value)
for name in ("sandbox_key_suffix", "workspace_segments", "memory_dimensions"):
assert name in message
# The same pair is accepted without the opt-in, where the snapshot is
# held to the narrowing rule instead: it is the flag that is refused,
# not the fallback.
assert DeferToSnapshot(committed).fallback == committed
@pytest.mark.parametrize(
"field_name,committed_kwargs",
[
("sandbox_key_suffix", {"sandbox_key_suffix": "tenant-a"}),
("workspace_segments", {"workspace_segments": ("tenant-a",)}),
(
"sandbox_mount_segments",
{
"workspace_segments": ("tenant-a",),
"sandbox_mount_segments": ("tenant-a",),
},
),
("memory_dimensions", {"memory_dimensions": {"tenant": "a"}}),
("isolate_external_dirs", {"isolate_external_dirs": True}),
],
)
def test_opt_in_rejects_a_commitment_on_any_single_namespace_field(
self, field_name, committed_kwargs
):
"""Per-field, so the precondition cannot be satisfied by checking only
the obvious fields. Each case commits exactly one field of the
fallback (the mount case necessarily carries the workspace segments
it must prefix, and reports both)."""
with pytest.raises(ExecutionScopeResolverContractError) as exc_info:
DeferToSnapshot(
ExecutionScope(**committed_kwargs), snapshot_defines_namespace=True
)
assert field_name in str(exc_info.value)
def test_opt_in_with_a_policy_only_fallback_is_accepted(self):
"""Policy fields are not part of the precondition: the fallback still
owns those on this branch (see
test_opt_in_still_honours_policy_field_symmetry), so committing one
must not be mistaken for claiming a namespace."""
fallback = ExecutionScope(strict_memory_isolation=True)
carrier = DeferToSnapshot(fallback, snapshot_defines_namespace=True)
assert carrier.snapshot_defines_namespace is True
assert carrier.fallback == fallback
def test_opt_in_with_a_conforming_fallback_and_a_present_snapshot(self):
"""The whole conforming shape end to end: a fallback that claims no
namespace but does set a policy field, plus a present snapshot that
supplies the namespace. The snapshot's namespace is adopted and the
fallback's policy value is kept."""
fallback = ExecutionScope(strict_memory_isolation=True)
snapshot = ExecutionScope(
sandbox_key_suffix="workforce-task",
workspace_segments=("workforce", "task-7"),
memory_dimensions={"tenant": "acme"},
)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
result = resolve_execution_scope("1")
assert result.sandbox_key_suffix == "workforce-task"
assert result.workspace_segments == ("workforce", "task-7")
assert dict(result.memory_dimensions) == {"tenant": "acme"}
assert result.strict_memory_isolation is True
def test_opt_in_still_honours_policy_field_symmetry(self):
"""Namespace fields agree (both all-default), only
strict_memory_isolation differs: the fallback's policy value still
wins and the disagreement is still logged, exactly as on the
default (narrowing) branch."""
fallback = ExecutionScope(strict_memory_isolation=True)
snapshot = ExecutionScope(strict_memory_isolation=False)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot)
with scope_log_records() as records:
result = resolve_execution_scope("1")
assert result.strict_memory_isolation is True
assert any(
"policy-only mismatch" in r and "strict_memory_isolation" in r
for r in records
)
def test_flag_does_not_make_the_fallback_optional(self):
"""The opt-in changes what a present snapshot is checked against,
not whether a fallback is required at all: ``DeferToSnapshot``
still rejects a non-ExecutionScope fallback even with the flag set,
and the mandatory fallback still applies on a snapshot miss.
The fallback here commits no namespace (the opt-in's precondition) but
does set a policy field, which keeps it distinguishable from the
all-default scope an unscoped resolution would return."""
with pytest.raises(TypeError):
DeferToSnapshot("not-a-scope", snapshot_defines_namespace=True)
fallback = ExecutionScope(strict_memory_isolation=True)
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback, snapshot_defines_namespace=True),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: None)
assert resolve_execution_scope("1") == fallback
class TestShapeGateLogsFieldDiffLazily:
"""The shape-version gate's field diff exists only to populate its own
log message -- unlike the narrowing/authoritative diffs, which are also
needed for control flow, nothing downstream reads this one. It must
therefore be computed only when that message will actually be emitted,
since the gate runs on every turn for any snapshot that predates a
shape bump."""
def test_field_diff_not_computed_when_warning_is_disabled(self, monkeypatch):
from xagent.core import execution_scope as scope_module
def boom(*_args, **_kwargs):
raise AssertionError(
"field diff computed even though WARNING logging is disabled"
)
monkeypatch.setattr(scope_module, "_execution_scope_field_diff", boom)
resolver_scope = ExecutionScope()
stale_data = ExecutionScope(sandbox_key_suffix="stale").to_dict()
del stale_data["version"]
stale_snapshot = ExecutionScope.from_dict(stale_data)
set_execution_scope_resolver(
lambda task_id: resolver_scope,
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: stale_snapshot)
with scope_log_records(level=logging.ERROR) as records:
# Gate behavior is unaffected by the logging level: the stale
# snapshot is still ignored and the resolver's scope wins.
assert resolve_execution_scope("1") == resolver_scope
assert records == []
def test_field_diff_still_computed_and_logged_when_warning_is_enabled(self):
"""Positive mirror: with WARNING enabled (the default), the gate's
existing observable behavior -- a log line naming the differing
field -- is unchanged by the lazy guard."""
resolver_scope = ExecutionScope()
stale_data = ExecutionScope(sandbox_key_suffix="stale").to_dict()
del stale_data["version"]
stale_snapshot = ExecutionScope.from_dict(stale_data)
set_execution_scope_resolver(
lambda task_id: resolver_scope,
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: stale_snapshot)
with scope_log_records() as records:
assert resolve_execution_scope("1") == resolver_scope
assert any("shape" in r and "sandbox_key_suffix" in r for r in records)
class TestResolveExecutionScopeOffTurn:
"""What decides whether a consumer may downgrade a mismatch is whether it
is selecting a namespace for new bytes, not whether a turn is running.
A consumer that selects one -- websocket ``_scope_segments_for_task``,
whose caller composes the storage key for a brand-new durable object --
resolves fail-closed through ``resolve_execution_scope`` even though it
runs outside any turn: choosing where new bytes land is an authority
decision that must not be downgraded to either side's guess. The
consumers that come through this entry point instead read a namespace
something else already committed to: ``ManagedFileRef``'s construction,
the pause/resume handlers, and workspace cleanup. For them a
resolver-authoritative namespace mismatch downgrades to the resolver's
answer rather than failing an operation that has no turn left to fail.
A mismatch whose ``resolver_scope`` is not an authoritative answer has
nothing to downgrade to and stays fail-closed even here -- see
``ExecutionScopeAbstentionMismatchError``'s docstring."""
def test_passthrough_when_no_mismatch(self):
scope = ExecutionScope(sandbox_key_suffix="s")
set_execution_scope_resolver(
lambda task_id: scope, acknowledges_snapshot_candidate_contract=True
)
assert resolve_execution_scope_off_turn("1") == scope
def test_authoritative_branch_mismatch_downgrades_to_resolver_value_with_warning(
self,
):
"""The resolver returned a real ``ExecutionScope`` (authoritative
branch): its value is a genuine answer, so a disagreeing snapshot's
mismatch is downgraded to it off-turn instead of raised."""
resolver_scope = ExecutionScope(sandbox_key_suffix="from-resolver")
snapshot_scope = ExecutionScope(sandbox_key_suffix="from-snapshot")
set_execution_scope_resolver(
lambda task_id: resolver_scope,
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot_scope)
# A real disagreement: the fail-closed entry point must reject it, or
# the downgrade below would be indistinguishable from "nothing
# disagreed" -- which also returns the resolver's scope.
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert not isinstance(exc_info.value, ExecutionScopeAbstentionMismatchError)
with scope_log_records() as records:
result = resolve_execution_scope_off_turn("1")
assert result == resolver_scope
assert any("authority mismatch" in r.lower() for r in records)
def test_abstention_branch_mismatch_stays_fail_closed_off_turn(self):
"""The resolver deferred to the snapshot (abstention branch) and the
snapshot widens the fallback: unlike the authoritative case above,
``resolved.fallback`` here is not an authoritative answer -- it is
what the resolver supplied while declining to answer, all-default
for this test. Downgrading to it off-turn would hand a caller like
workspace cleanup an unscoped value indistinguishable from no scope
at all, so this must propagate unchanged instead of being
downgraded. No existing test covered this off-turn path before --
every prior off-turn mismatch case used an authoritative resolver."""
fallback = ExecutionScope()
snapshot_scope = ExecutionScope(sandbox_key_suffix="attacker-chosen")
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot_scope)
# Confirm the in-turn behavior this off-turn call must not soften.
with pytest.raises(ExecutionScopeAbstentionMismatchError):
resolve_execution_scope("1")
with pytest.raises(ExecutionScopeAbstentionMismatchError):
resolve_execution_scope_off_turn("1")
def test_a_new_authority_error_subclass_is_not_downgraded_by_default(self):
"""The downgrade condition is positive -- "this raise site declared an
authoritative value" -- rather than an exclusion list of the subclasses
known to be unsafe. A subclass defined here, which no exclusion list in
the module could name, must therefore propagate: an off-turn face that
fails open for anything it has not been taught about would hand out
``resolver_scope`` values no branch ever sanctioned."""
class _FutureMismatchError(ExecutionScopeAuthorityError):
"""A mismatch shape added after this predicate was written."""
def resolver(task_id):
raise _FutureMismatchError(
str(task_id),
resolver_scope=ExecutionScope(sandbox_key_suffix="not-an-authority"),
snapshot_scope=ExecutionScope(sandbox_key_suffix="from-snapshot"),
mismatched_fields={
"sandbox_key_suffix": ("from-snapshot", "not-an-authority")
},
resolver_scope_is_authoritative=False,
)
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
with pytest.raises(_FutureMismatchError):
resolve_execution_scope_off_turn("1")
def test_a_subclass_declaring_an_authority_is_still_downgraded(self):
"""The other half: the predicate keys on the declaration, not on the
class, so a subclass that does have a sanctioned value is downgraded
without the function needing to know the type."""
class _FutureAuthoritativeMismatchError(ExecutionScopeAuthorityError):
"""A mismatch shape that does carry an authoritative answer."""
authoritative = ExecutionScope(sandbox_key_suffix="from-resolver")
def resolver(task_id):
raise _FutureAuthoritativeMismatchError(
str(task_id),
resolver_scope=authoritative,
snapshot_scope=ExecutionScope(sandbox_key_suffix="from-snapshot"),
mismatched_fields={
"sandbox_key_suffix": ("from-snapshot", "from-resolver")
},
resolver_scope_is_authoritative=True,
)
set_execution_scope_resolver(
resolver, acknowledges_snapshot_candidate_contract=True
)
with scope_log_records() as records:
assert resolve_execution_scope_off_turn("1") == authoritative
assert any("authority mismatch" in r.lower() for r in records)
def test_other_exceptions_still_propagate(self):
def boom(task_id):
raise RuntimeError("resolver down")
set_execution_scope_resolver(
boom, acknowledges_snapshot_candidate_contract=True
)
with pytest.raises(RuntimeError, match="resolver down"):
resolve_execution_scope_off_turn("1")
class TestExecutionScopeAbstentionMismatchErrorIsDistinguishable:
"""Pin: the abstention-branch error is a distinct type a caller must
explicitly widen its ``except`` clause to catch, so an existing
``except ExecutionScopeAuthorityError: return exc.resolver_scope``
downgrade path (written for the authoritative branch) cannot silently
also catch and downgrade an abstention mismatch."""
def test_is_a_subclass_of_the_base_authority_error(self):
assert issubclass(
ExecutionScopeAbstentionMismatchError, ExecutionScopeAuthorityError
)
def test_abstention_raise_site_declares_no_authoritative_value(self):
"""The attribute, not the class, is what blocks the off-turn
downgrade (see ``resolve_execution_scope_off_turn``), so the
abstention branch's raise site must declare ``False`` for it."""
fallback = ExecutionScope()
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(
lambda task_id: ExecutionScope(sandbox_key_suffix="attacker-chosen")
)
with pytest.raises(ExecutionScopeAbstentionMismatchError) as exc_info:
resolve_execution_scope("1")
assert exc_info.value.resolver_scope_is_authoritative is False
def test_authoritative_raise_site_declares_an_authoritative_value(self):
"""The mirror: the branch that really has an answer says so, which is
what licenses the off-turn downgrade."""
resolver_scope = ExecutionScope(sandbox_key_suffix="from-resolver")
set_execution_scope_resolver(
lambda task_id: resolver_scope,
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(
lambda task_id: ExecutionScope(sandbox_key_suffix="from-snapshot")
)
with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
resolve_execution_scope("1")
assert exc_info.value.resolver_scope_is_authoritative is True
class TestDeferCarrierNeverActivated:
"""The carrier is never mistaken for a real scope, and the turn
contextvar only ever holds the resolved fallback/snapshot, never the
carrier itself."""
def test_turn_activates_the_fallback_not_the_carrier(self):
fallback = ExecutionScope(sandbox_key_suffix="fallback")
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback),
acknowledges_snapshot_candidate_contract=True,
)
with turn_execution_scope("1") as active:
assert active == fallback
current = get_execution_scope()
assert isinstance(current, ExecutionScope)
assert isinstance(current, DeferToSnapshot) is False
class TestExecutionScopeFieldClassificationCompleteness:
"""Every dataclass field must be
explicitly bucketed as namespace-affecting or policy-only, so a newly
added field can't silently miss ``resolve_execution_scope``'s
authority-mismatch classification. A field landing in neither bucket
would never be compared at all (not even logged), which is worse than
being misclassified into either one.
"""
def test_namespace_field_classification_is_complete_and_disjoint_from_policy(
self,
):
"""Static classification-completeness check only -- this does not
call ``scope_fingerprint`` at all, so it claims no fingerprint
coverage: a set-vs-set comparison cannot exercise one. Real per-field
fingerprint behavior is covered by
``TestScopeFingerprintFieldCoverage`` below, which does call it."""
from xagent.core import execution_scope as scope_module
namespace_fields = set(scope_module._EXECUTION_SCOPE_NAMESPACE_FIELDS)
policy_fields = set(scope_module._EXECUTION_SCOPE_POLICY_FIELDS)
assert namespace_fields.isdisjoint(policy_fields)
assert namespace_fields | policy_fields | {"version"} == {
f.name for f in dataclasses.fields(ExecutionScope)
}
class TestNarrowingViolationsFieldCoverage:
"""``_execution_scope_narrowing_violations`` must classify every
namespace field through the shared
``_EXECUTION_SCOPE_NAMESPACE_FIELD_NARROWING`` table rather than a
hardcoded per-field check, so a namespace field added to
``_EXECUTION_SCOPE_NAMESPACE_FIELDS`` cannot be silently skipped by this
one consumer while the diff (``_execution_scope_field_diff``) and the
fingerprint (``scope_fingerprint``), which already iterate their own
tables, pick it up automatically.
"""
def test_narrowing_table_tracks_the_namespace_fields_exactly(self):
from xagent.core import execution_scope as scope_module
assert set(scope_module._EXECUTION_SCOPE_NAMESPACE_FIELD_NARROWING) == set(
scope_module._EXECUTION_SCOPE_NAMESPACE_FIELDS
)
# One (base_kwargs, changed_kwargs) probe per namespace field: constructing
# ExecutionScope(**base_kwargs) and ExecutionScope(**changed_kwargs) changes
# only that field's contribution to scope_fingerprint(). Keyed by field name
# so TestScopeFingerprintFieldCoverage can assert this dict's keys track
# _EXECUTION_SCOPE_NAMESPACE_FIELDS exactly -- a namespace field added
# without a probe here fails loudly instead of being silently skipped.
# The ``sandbox_mount_segments`` probe holds ``workspace_segments`` fixed
# across both sides and varies only the mount, so the fingerprint difference
# it exercises comes from the mount slot alone. It does not, by itself, prove
# ``scope_fingerprint`` reads the *derived* mount value rather than the raw
# field -- see ``test_mount_fingerprint_reads_the_effective_value_not_the_raw_field``
# below for the probe that actually pins that.
_NAMESPACE_FIELD_FINGERPRINT_PROBES: dict[str, tuple[dict, dict]] = {
"sandbox_key_suffix": ({}, {"sandbox_key_suffix": "probe-suffix"}),
"workspace_segments": ({}, {"workspace_segments": ("probe",)}),
"sandbox_mount_segments": (
{
"workspace_segments": ("probe", "deep"),
"sandbox_mount_segments": ("probe",),
},
{
"workspace_segments": ("probe", "deep"),
"sandbox_mount_segments": None,
},
),
"memory_dimensions": ({}, {"memory_dimensions": {"k": "v"}}),
"isolate_external_dirs": ({}, {"isolate_external_dirs": True}),
}
# Same idea for the one field the fingerprint deliberately excludes.
_POLICY_FIELD_FINGERPRINT_PROBES: dict[str, tuple[dict, dict]] = {
"strict_memory_isolation": ({}, {"strict_memory_isolation": True}),
}
class TestScopeFingerprintFieldCoverage:
"""Behavior-derived counterpart to the set-comparison-only test above:
calls ``scope_fingerprint()`` itself, per field, rather than comparing
two hand-maintained collections against each other. Reverting
``scope_fingerprint()`` to drop any namespace field's contribution fails
the corresponding parametrized case here directly.
Why each bucket matters to the fingerprint: a namespace field is baked
into per-task cached state at build time -- ``isolate_external_dirs``, for
instance, into the cached ``AgentService``'s
``Workspace.allowed_external_dirs`` via
``AgentServiceManager.get_agent_for_task`` ->
``_build_allowed_external_dirs`` -- so a change there must evict the cache
or the stale value keeps being enforced. A policy field like
``strict_memory_isolation`` is read fresh from the contextvar on every
operation (``UserIsolatedMemoryStore``), so nothing cached goes stale and
including it would only cause needless rebuilds.
"""
def test_probes_cover_exactly_the_classified_fields(self):
"""Fixture completeness: every namespace/policy field must have a
probe pair here, so a newly added field can't be silently skipped.
Which bucket a field belongs to is separately pinned by
TestExecutionScopeFieldClassificationCompleteness above; this only
checks the probe tables track that bucketing."""
from xagent.core import execution_scope as scope_module
assert set(_NAMESPACE_FIELD_FINGERPRINT_PROBES) == set(
scope_module._EXECUTION_SCOPE_NAMESPACE_FIELDS
)
assert set(_POLICY_FIELD_FINGERPRINT_PROBES) == set(
scope_module._EXECUTION_SCOPE_POLICY_FIELDS
)
@pytest.mark.parametrize("field_name", list(_NAMESPACE_FIELD_FINGERPRINT_PROBES))
def test_namespace_field_change_changes_the_fingerprint(self, field_name):
base_kwargs, changed_kwargs = _NAMESPACE_FIELD_FINGERPRINT_PROBES[field_name]
base = ExecutionScope(**base_kwargs)
changed = ExecutionScope(**changed_kwargs)
assert scope_fingerprint(base) != scope_fingerprint(changed)
@pytest.mark.parametrize("field_name", list(_POLICY_FIELD_FINGERPRINT_PROBES))
def test_policy_field_change_does_not_change_the_fingerprint(self, field_name):
base_kwargs, changed_kwargs = _POLICY_FIELD_FINGERPRINT_PROBES[field_name]
base = ExecutionScope(**base_kwargs)
changed = ExecutionScope(**changed_kwargs)
assert scope_fingerprint(base) == scope_fingerprint(changed)
def test_mount_fingerprint_reads_the_effective_value_not_the_raw_field(self):
"""The ``!=`` probe above cannot tell a correct (derived) mount read
apart from a regression to the raw ``sandbox_mount_segments``
attribute: whenever the two probe scopes' raw mount values differ --
as they must, to make the mount the only varying input -- a
raw-reading ``scope_fingerprint`` also reports a difference, so that
assertion passes under either implementation. This test uses the
one pair that actually depends on which value is read: a scope left
at the mount's default (``None``, meaning the full
``workspace_segments``) and a scope whose mount explicitly repeats
those same segments have equal *effective* mounts but different
*raw* ones, so their fingerprints must match only if
``scope_fingerprint`` reads ``effective_mount_segments``."""
default_mount = ExecutionScope(workspace_segments=("a",))
explicit_full_mount = ExecutionScope(
workspace_segments=("a",), sandbox_mount_segments=("a",)
)
assert (
default_mount.sandbox_mount_segments
!= explicit_full_mount.sandbox_mount_segments
)
assert (
default_mount.effective_mount_segments
== explicit_full_mount.effective_mount_segments
)
assert scope_fingerprint(default_mount) == scope_fingerprint(
explicit_full_mount
)
class TestAuthorityMismatchNamesItsRemediation:
"""The mismatch is stable, so every turn of the task fails the same way
until the persisted snapshot is removed or corrected. The operator-facing
log has to say that, because the snapshot sits in a column no request path
offers to clear and a bare repeating failure states no way out."""
def test_error_log_names_the_key_to_clear(self):
resolver_scope = ExecutionScope(sandbox_key_suffix="from-resolver")
snapshot_scope = ExecutionScope(sandbox_key_suffix="from-snapshot")
set_execution_scope_resolver(
lambda task_id: resolver_scope,
acknowledges_snapshot_candidate_contract=True,
)
set_execution_scope_snapshot_loader(lambda task_id: snapshot_scope)
with scope_log_records() as records:
with pytest.raises(ExecutionScopeAuthorityError):
resolve_execution_scope("1")
remediation = [r for r in records if EXECUTION_SCOPE_AGENT_CONFIG_KEY in r]
assert remediation, records
assert "every turn" in remediation[0].lower()
class TestPersistedAgentConfigRejectsADecodedScope:
"""The override takes the task's raw ``agent_config``. An already-decoded
scope is not a Mapping, so decoding it would yield "no snapshot" -- which
on the abstention and no-resolver branches is indistinguishable from an
authoritative unscoped answer. It has to be refused, not dropped."""
def test_passing_a_scope_is_a_contract_error_not_a_silent_miss(self):
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope(
"1", persisted_agent_config=ExecutionScope(sandbox_key_suffix="s")
)
def test_raw_agent_config_still_resolves(self):
scope = ExecutionScope(sandbox_key_suffix="s")
assert (
resolve_execution_scope(
"1",
persisted_agent_config={
EXECUTION_SCOPE_AGENT_CONFIG_KEY: scope.to_dict()
},
)
== scope
)
class TestWrongTypedSnapshotIsCorruptNotAbsent:
"""A present ``execution_scope`` that is not a mapping cannot be decoded,
exactly like a mapping with an invalid field. Reporting "no candidate" for
one shape and raising for the other would make the same accidental
namespace decision on every branch where the snapshot is the only
authority."""
@pytest.mark.parametrize("value", ["garbage-string", ["a"], 5, True])
def test_present_but_wrong_typed_raises(self, value):
with pytest.raises(ExecutionScopeResolverContractError):
execution_scope_from_agent_config({EXECUTION_SCOPE_AGENT_CONFIG_KEY: value})
def test_absent_key_is_still_absent(self):
assert execution_scope_from_agent_config({"other": 1}) is None
def test_explicit_null_is_still_absent(self):
assert (
execution_scope_from_agent_config({EXECUTION_SCOPE_AGENT_CONFIG_KEY: None})
is None
)
def test_wrong_typed_snapshot_fails_the_abstention_branch(self):
"""The branch where "absent" would resolve to the abstention's
fallback -- the widest value the narrowing check would ever admit."""
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback=ExecutionScope()),
acknowledges_snapshot_candidate_contract=True,
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope(
"1",
persisted_agent_config={
EXECUTION_SCOPE_AGENT_CONFIG_KEY: "garbage-string"
},
)
class TestDecodedScopeGuardRunsBeforeBranchDispatch:
"""The guard rejects a caller bug, so which resolver happens to be
registered must not decide whether it is heard. The authoritative branch
wraps its snapshot load in a tolerant except -- so a bad candidate cannot
veto a real answer -- and a raise from inside that wrapper would be
absorbed and misreported as a loader failure."""
def test_raises_with_an_authoritative_resolver_registered(self):
set_execution_scope_resolver(
lambda task_id: ExecutionScope(sandbox_key_suffix="from-resolver"),
acknowledges_snapshot_candidate_contract=True,
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope(
"1", persisted_agent_config=ExecutionScope(sandbox_key_suffix="s")
)
def test_raises_when_the_resolver_abstains(self):
set_execution_scope_resolver(
lambda task_id: DeferToSnapshot(fallback=ExecutionScope()),
acknowledges_snapshot_candidate_contract=True,
)
with pytest.raises(ExecutionScopeResolverContractError):
resolve_execution_scope(
"1", persisted_agent_config=ExecutionScope(sandbox_key_suffix="s")
)