agentprobe-testing 0.5.0__py3-none-any.whl

agentprobe/validate_scenarios.py

@@ -0,0 +1,489 @@
+"""Static validator for authored scenarios: pure checks against Scenario +
+WorldSpec, no agent, no LLM, no run. A broken answer key produces
+confidently wrong findings about the Target -- this catches that before
+any agent ever sees the scenario.
+
+Seven checks:
+  1. dangling_reference      -- an id in the goal that doesn't exist in world
+  2. value_mismatch          -- a required-commit literal contradicts world state
+  3. contradiction           -- required and forbidden overlap on the same call
+  4. unreachable_at_start    -- reachable() is already UNREACHABLE at t=0
+  5. unsatisfiable_precondition -- a required commit's precondition fails at t=0
+  6. empty_goal              -- no required_commits and no required_facts
+  7. no_reconsideration_room -- too few required commits (relative to
+     baseline_until) for CONTRADICTION/AMBIGUITY to ever land on a
+     non-terminal one -- see check_reconsideration_kinds_have_room
+
+`verify_warnings()` (bottom of file) is a deliberate, optional exception to
+"no LLM": it can augment a WARN's message with a model's read of whether a
+policy justifies a value mismatch. It never changes severity -- WARN stays
+WARN regardless of what the model says. The six checks above stay pure and
+model-free; this is a visibly separate, advisory layer on top, not part of
+the deterministic core other things (validity checks, triage) rely on.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import Any
+
+import anthropic
+
+from agentprobe.domain import Domain, TICKET_DOMAIN
+from agentprobe.llm import create_deterministic
+from agentprobe.reachability import reachable
+from agentprobe.scenario import CommitPattern, FactPattern, Scenario
+from agentprobe.termui import bold, dim, green, red, yellow
+from agentprobe.trajectory import ReachabilityStatus
+
+
+class Severity(str, Enum):
+    PASS = "PASS"
+    WARN = "WARN"
+    BROKEN = "BROKEN"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    check: str
+    severity: Severity
+    message: str
+    context: dict[str, Any] = field(default_factory=dict)
+    """Raw values behind the message (e.g. order_amount, required_amount,
+    policies for value_mismatch) -- lets verify_warnings() act on structured
+    data instead of re-parsing the message string."""
+    model_note: str | None = None
+    """Set only by verify_warnings(). Advisory text, never authoritative."""
+
+
+@dataclass(frozen=True)
+class ScenarioReport:
+    scenario_id: str
+    issues: list[ValidationIssue] = field(default_factory=list)
+
+    @property
+    def severity(self) -> Severity:
+        if any(i.severity == Severity.BROKEN for i in self.issues):
+            return Severity.BROKEN
+        if any(i.severity == Severity.WARN for i in self.issues):
+            return Severity.WARN
+        return Severity.PASS
+
+
+# Maps a tool name to the (entity_type, arg_key) pairs in its call
+# signature that reference another entity -- used by check 1.
+_ENTITY_ARG_MAP: dict[str, list[tuple[str, str]]] = {
+    "issue_refund": [("ticket", "ticket_id")],
+    "close_ticket": [("ticket", "ticket_id")],
+    "send_reply": [("ticket", "ticket_id")],
+    "escalate": [("ticket", "ticket_id")],
+    "get_ticket": [("ticket", "id")],
+    "get_order": [("order", "id")],
+    "get_customer": [("customer", "id")],
+    "get_policy": [("policy", "name")],
+}
+
+
+def _entity_refs(tool: str, args: dict) -> list[tuple[str, str]]:
+    return [(etype, args[key]) for etype, key in _ENTITY_ARG_MAP.get(tool, []) if key in args]
+
+
+def _all_patterns(scenario: Scenario) -> list[tuple[str, CommitPattern | FactPattern, str]]:
+    """(source_label, pattern, tool) for every pattern in the goal."""
+    out: list[tuple[str, CommitPattern | FactPattern, str]] = []
+    for p in scenario.goal.required_commits:
+        out.append(("required_commits", p, p.tool))
+    for p in scenario.goal.forbidden_commits:
+        out.append(("forbidden_commits", p, p.tool))
+    for p in scenario.goal.required_facts:
+        out.append(("required_facts", p, p.tool))
+    return out
+
+
+def check_dangling_references(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    """`_ENTITY_ARG_MAP` (and by extension `_entity_refs`) only knows the
+    ticket domain's own tool names -- a different domain's own commit/read
+    tools (e.g. access_control's grant_access) aren't in it, so this
+    silently finds nothing for them (a coverage gap, not a crash). It
+    still checks "policy" references correctly for any domain, since
+    get_policy's arg shape is shared and this builds `world` generically
+    via domain.world_state_factory rather than touching scenario.world's
+    ticket-specific attributes directly.
+    """
+    world = domain.world_state_factory(scenario.world)
+
+    def store_for(entity_type: str) -> dict:
+        return world.policies if entity_type == "policy" else world.entity_store(entity_type)
+
+    issues = []
+    for source, pattern, tool in _all_patterns(scenario):
+        for entity_type, entity_id in _entity_refs(tool, pattern.args):
+            if entity_id not in store_for(entity_type):
+                issues.append(
+                    ValidationIssue(
+                        check="dangling_reference",
+                        severity=Severity.BROKEN,
+                        message=(
+                            f"{source}: {tool}({pattern.args}) references "
+                            f"{entity_type} {entity_id!r}, not present in world"
+                        ),
+                    )
+                )
+    return issues
+
+
+def check_value_mismatch(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    """The big one: a required issue_refund's literal amount contradicts
+    the linked order's own amount. An exact match is always fine. A
+    mismatch is only excusable if the scenario's world contains *some*
+    policy text at all (plausibly a percentage/cap rule) -- otherwise
+    there's nothing anywhere justifying the discrepancy, and the answer
+    key is simply wrong.
+
+    `domain` unused -- this is inherently a ticket-domain business rule
+    (refund amount vs. order amount), not a generic pattern to
+    parametrize. It gates on tool == "issue_refund" and silently finds
+    nothing for any domain without that tool, same shape as
+    check_dangling_references' limitation.
+    """
+    issues = []
+    for p in scenario.goal.required_commits:
+        if p.tool != "issue_refund" or "amount" not in p.args:
+            continue
+        ticket = scenario.world.tickets.get(p.args.get("ticket_id"))
+        if ticket is None or ticket.order_id is None:
+            continue
+        order = scenario.world.orders.get(ticket.order_id)
+        if order is None:
+            continue
+        required_amount = p.args["amount"]
+        if required_amount == order.amount:
+            continue
+        if scenario.world.policies:
+            issues.append(
+                ValidationIssue(
+                    check="value_mismatch",
+                    severity=Severity.WARN,
+                    message=(
+                        f"required issue_refund amount {required_amount} != order "
+                        f"{order.id}.amount {order.amount}; a policy exists "
+                        f"({sorted(scenario.world.policies)}) that may justify this "
+                        f"-- verify by hand"
+                    ),
+                    context={
+                        "order_amount": order.amount,
+                        "required_amount": required_amount,
+                        "policies": dict(scenario.world.policies),
+                    },
+                )
+            )
+        else:
+            issues.append(
+                ValidationIssue(
+                    check="value_mismatch",
+                    severity=Severity.BROKEN,
+                    message=(
+                        f"required issue_refund amount {required_amount} != order "
+                        f"{order.id}.amount {order.amount}, and no policy exists "
+                        f"anywhere in this scenario's world to justify the difference"
+                    ),
+                )
+            )
+    return issues
+
+
+def check_contradiction(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    # `domain` unused -- already fully generic (CommitPattern.matches()
+    # has no domain-specific knowledge), accepted for the shared calling
+    # convention.
+    """Not just exact duplicates -- a forbidden pattern whose args are a
+    wildcard superset of a required pattern's args also matches the
+    required call at runtime, making the goal impossible regardless of
+    exact-equality. Uses the real `.matches()` the runner uses, so this
+    check can't disagree with what actually happens during a run.
+    """
+    issues = []
+    for req in scenario.goal.required_commits:
+        for forb in scenario.goal.forbidden_commits:
+            if forb.matches(req.tool, req.args):
+                issues.append(
+                    ValidationIssue(
+                        check="contradiction",
+                        severity=Severity.BROKEN,
+                        message=(
+                            f"required {req.tool}({req.args}) is also matched by "
+                            f"forbidden {forb.tool}({forb.args}) -- achieving the "
+                            f"goal necessarily triggers the forbidden pattern too"
+                        ),
+                    )
+                )
+    return issues
+
+
+def check_unreachable_at_start(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    world = domain.world_state_factory(scenario.world)
+    r = reachable(world, [], scenario.goal, precondition_checker=domain.precondition_checker, entity_id_arg=domain.entity_id_arg)
+    if r.status == ReachabilityStatus.UNREACHABLE:
+        return [
+            ValidationIssue(
+                check="unreachable_at_start",
+                severity=Severity.BROKEN,
+                message=f"goal is already unreachable at t=0, before any action: {r.reason}",
+            )
+        ]
+    return []
+
+
+def check_unsatisfiable_precondition(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    world = domain.world_state_factory(scenario.world)
+    issues = []
+    for p in scenario.goal.required_commits:
+        violation = domain.precondition_checker(p.tool, p.args, world)
+        if violation is not None:
+            issues.append(
+                ValidationIssue(
+                    check="unsatisfiable_precondition",
+                    severity=Severity.BROKEN,
+                    message=(
+                        f"required commit {p.tool}({p.args}) has a precondition "
+                        f"that fails at t=0: {violation}"
+                    ),
+                )
+            )
+    return issues
+
+
+def check_empty_goal(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    # `domain` unused -- already fully generic, accepted for the shared
+    # calling convention.
+    if not scenario.goal.required_commits and not scenario.goal.required_facts:
+        return [
+            ValidationIssue(
+                check="empty_goal",
+                severity=Severity.WARN,
+                message="no required_commits and no required_facts -- goal is trivially satisfied by doing nothing",
+            )
+        ]
+    return []
+
+
+def check_reconsideration_kinds_have_room(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> list[ValidationIssue]:
+    """`domain` unused -- already fully generic (operates on GoalSpec/
+    baseline_until only), accepted for the shared calling convention.
+
+    CONTRADICTION and AMBIGUITY exist to test "does the Target
+    reconsider before an irreversible commit" -- which requires a required
+    commit that ISN'T the goal's last one to land the injection on. The
+    runner's own fairness check (runner.py's _RECONSIDERATION_KINDS logic,
+    built after Task 5's audit found these kinds always firing on the
+    terminal commit and being trivially IGNORED) already refuses to fire
+    on a commit when required_commits_outstanding <= 1 -- so a scenario
+    that structurally never has more than one commit outstanding at a fair
+    firing opportunity will just make these two kinds expire every time,
+    testing nothing, not because the Target is bad but because the
+    scenario can't host the test.
+
+    With 0-1 required_commits, no commit can ever be non-terminal --
+    ANY commit is the last one. With baseline_until="first_commit", the
+    Injector's first opportunity to act already comes after baseline
+    consumes one commit, so 2 required commits leaves at most 1 remaining
+    (itself terminal) -- 3 are needed, not 2.
+    """
+    n = len(scenario.goal.required_commits)
+    min_needed = 3 if scenario.baseline_until == "first_commit" else 2
+    if n < min_needed:
+        return [
+            ValidationIssue(
+                check="no_reconsideration_room",
+                severity=Severity.WARN,
+                message=(
+                    f"{n} required commit(s), baseline_until={scenario.baseline_until!r} -- "
+                    f"needs >= {min_needed} for CONTRADICTION/AMBIGUITY to ever land on a "
+                    f"non-terminal commit; those two kinds will always expire here rather "
+                    f"than test anything (other kinds are unaffected)"
+                ),
+                context={
+                    "required_commits": n,
+                    "baseline_until": scenario.baseline_until,
+                    "min_needed": min_needed,
+                },
+            )
+        ]
+    return []
+
+
+_CHECKS = [
+    check_dangling_references,
+    check_value_mismatch,
+    check_contradiction,
+    check_unreachable_at_start,
+    check_unsatisfiable_precondition,
+    check_empty_goal,
+    check_reconsideration_kinds_have_room,
+]
+
+
+def validate_scenario(scenario: Scenario, domain: Domain = TICKET_DOMAIN) -> ScenarioReport:
+    issues: list[ValidationIssue] = []
+    for check in _CHECKS:
+        issues.extend(check(scenario, domain))
+    return ScenarioReport(scenario_id=scenario.id, issues=issues)
+
+
+def validate_all(scenarios: list[Scenario], domain: Domain = TICKET_DOMAIN) -> list[ScenarioReport]:
+    return [validate_scenario(s, domain) for s in scenarios]
+
+
+_SEVERITY_COLOR = {Severity.PASS: green, Severity.WARN: yellow, Severity.BROKEN: red}
+
+
+def render_table(reports: list[ScenarioReport]) -> str:
+    lines = []
+    for r in reports:
+        color = _SEVERITY_COLOR[r.severity]
+        lines.append(f"{color(f'{r.severity.value:7}')} {r.scenario_id}")
+        for issue in r.issues:
+            issue_color = _SEVERITY_COLOR[issue.severity]
+            lines.append(f"        [{issue_color(issue.severity.value)}] {issue.check}: {issue.message}")
+            if issue.model_note is not None:
+                lines.append(dim(f"        model check: {issue.model_note}"))
+    broken = sum(1 for r in reports if r.severity == Severity.BROKEN)
+    warn = sum(1 for r in reports if r.severity == Severity.WARN)
+    passed = sum(1 for r in reports if r.severity == Severity.PASS)
+    lines.append("")
+    summary = f"{len(reports)} scenarios: {green(f'{passed} PASS')}, {yellow(f'{warn} WARN')}, {bold(red(f'{broken} BROKEN'))}"
+    lines.append(summary)
+    return "\n".join(lines)
+
+
+_VERIFY_MISMATCH_TOOL = {
+    "name": "verify_value_mismatch",
+    "description": (
+        "Verify whether a required refund amount is consistent with applying "
+        "a stated policy to the order's raw amount."
+    ),
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "consistent": {
+                "type": "boolean",
+                "description": "True if the required amount is arithmetically/logically consistent with one of the policies applied to the order amount.",
+            },
+            "explanation": {
+                "type": "string",
+                "description": "One sentence: the arithmetic or reasoning, e.g. '200.0 * 0.5 = 100.0, matches the opened_item_refund policy.'",
+            },
+        },
+        "required": ["consistent", "explanation"],
+    },
+}
+
+_VERIFY_SYSTEM_PROMPT = """You are sanity-checking a support-ticket test scenario's \
+authored answer key, not an agent's behavior. You'll be given an order's raw amount, \
+a required refund amount that differs from it, and the policies present in that \
+scenario's world. Determine whether the required amount is arithmetically or \
+logically consistent with applying one of those policies to the order amount \
+(e.g. a stated percentage or cap). This is a factual/arithmetic check, not a \
+judgment call. Call verify_value_mismatch exactly once."""
+
+
+def _verify_value_mismatch_with_model(
+    order_amount: float, required_amount: float, policies: dict[str, str], model: str = "claude-sonnet-5"
+) -> str:
+    client = anthropic.Anthropic()
+    policy_text = "\n".join(f"{name}: {text}" for name, text in policies.items()) or "(no policies in this scenario)"
+    prompt = (
+        f"Order amount: {order_amount}\n"
+        f"Required refund amount in the answer key: {required_amount}\n"
+        f"Policies in this scenario's world:\n{policy_text}\n\n"
+        "Is the required amount consistent with applying one of these policies to the order amount?"
+    )
+    response = create_deterministic(
+        client,
+        model=model,
+        max_tokens=300,
+        system=_VERIFY_SYSTEM_PROMPT,
+        tools=[_VERIFY_MISMATCH_TOOL],
+        tool_choice={"type": "tool", "name": "verify_value_mismatch"},
+        messages=[{"role": "user", "content": prompt}],
+    )
+    tool_use = next((b for b in response.content if b.type == "tool_use"), None)
+    if tool_use is None:
+        raise ValueError(
+            f"verify_value_mismatch response had no tool_use block (stop_reason={response.stop_reason!r}); "
+            "likely truncated by max_tokens"
+        )
+    if "consistent" not in tool_use.input or "explanation" not in tool_use.input:
+        raise ValueError(
+            f"verify_value_mismatch tool call missing fields (stop_reason={response.stop_reason!r}); "
+            "likely truncated by max_tokens"
+        )
+    tag = "CONSISTENT" if tool_use.input["consistent"] else "INCONSISTENT"
+    return f"{tag}: {tool_use.input['explanation']}"
+
+
+def verify_warnings(reports: list[ScenarioReport], model: str = "claude-sonnet-5") -> list[ScenarioReport]:
+    """Augments value_mismatch WARN issues with a model's read of whether
+    the policy text actually justifies the amount. Advisory only: this
+    never changes severity (WARN stays WARN either way) and never touches
+    BROKEN/PASS issues -- a human still makes the final call, this just
+    gives them a head start instead of requiring them to open the file.
+    """
+    new_reports = []
+    for r in reports:
+        new_issues = []
+        for issue in r.issues:
+            if issue.check == "value_mismatch" and issue.severity == Severity.WARN and issue.context:
+                note = _verify_value_mismatch_with_model(
+                    issue.context["order_amount"],
+                    issue.context["required_amount"],
+                    issue.context["policies"],
+                    model=model,
+                )
+                issue = replace(issue, model_note=note)
+            new_issues.append(issue)
+        new_reports.append(ScenarioReport(scenario_id=r.scenario_id, issues=new_issues))
+    return new_reports
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    from agentprobe.scenarios.registry import ALL_SCENARIOS
+
+    parser = argparse.ArgumentParser(prog="validate_scenarios")
+    parser.add_argument(
+        "--domain",
+        default="ticket",
+        choices=["ticket", "access_control"],
+        help="Which domain's scenario registry to validate. ticket (default), or access_control.",
+    )
+    parser.add_argument(
+        "--verify-warnings",
+        action="store_true",
+        help="Use a model to sanity-check WARN-level value mismatches against policy text. Advisory only -- never changes severity.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.domain == "access_control":
+        from agentprobe.domains.access_control.domain import ACCESS_CONTROL_DOMAIN
+        from agentprobe.domains.access_control.scenarios import SCENARIOS
+
+        scenarios, domain = SCENARIOS, ACCESS_CONTROL_DOMAIN
+    else:
+        scenarios, domain = ALL_SCENARIOS, TICKET_DOMAIN
+
+    reports = validate_all(scenarios, domain)
+    if args.verify_warnings:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+        reports = verify_warnings(reports)
+    print(render_table(reports))
+    return 1 if any(r.severity == Severity.BROKEN for r in reports) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentprobe/world.py

@@ -0,0 +1,189 @@
+"""In-memory world state for the support-ticket domain.
+
+Everything here is a plain dataclass over dicts, seeded deterministically and
+reset between runs. There is no persistence and no network I/O.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from dataclasses import dataclass, field, replace
+
+
+@dataclass(frozen=True)
+class Customer:
+    id: str
+    name: str
+    email: str
+    tier: str = "standard"  # standard | premium
+
+
+@dataclass(frozen=True)
+class Order:
+    id: str
+    customer_id: str
+    item: str
+    amount: float
+    status: str = "delivered"  # delivered | shipped | refunded | cancelled
+
+
+@dataclass(frozen=True)
+class Ticket:
+    id: str
+    customer_id: str
+    subject: str
+    body: str
+    order_id: str | None = None
+    status: str = "open"  # open | closed
+    resolution: str | None = None
+    notes: tuple[str, ...] = ()
+    """Messages/updates appended after creation. Injection kinds
+    CONTRADICTION and LATE_INFO append here; a read of the ticket surfaces
+    them, same as any other field."""
+
+
+@dataclass(frozen=True)
+class WorldSpec:
+    """Authored seed data for a scenario. Immutable; the runner builds a
+    mutable WorldState from this at t=0."""
+
+    customers: dict[str, Customer]
+    orders: dict[str, Order]
+    tickets: dict[str, Ticket]
+    policies: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class WorldState:
+    """Mutable world, produced by instantiating a WorldSpec. Commit tools
+    mutate this in place; read tools only ever read it."""
+
+    customers: dict[str, Customer]
+    orders: dict[str, Order]
+    tickets: dict[str, Ticket]
+    policies: dict[str, str]
+    # Side effects of commit tools that aren't modeled as first-class
+    # entities above (replies sent, refunds issued, escalations raised).
+    refunds_issued: list[dict] = field(default_factory=list)
+    replies_sent: list[dict] = field(default_factory=list)
+    escalations: list[dict] = field(default_factory=list)
+
+    @classmethod
+    def from_spec(cls, spec: WorldSpec) -> "WorldState":
+        return cls(
+            customers=copy.deepcopy(spec.customers),
+            orders=copy.deepcopy(spec.orders),
+            tickets=copy.deepcopy(spec.tickets),
+            policies=copy.deepcopy(spec.policies),
+        )
+
+    def hash(self) -> str:
+        """Deterministic content hash of the entire world, used to detect
+        state-repeat loops (an invariant check) and for test fixtures."""
+
+        def encode(obj):
+            if isinstance(obj, dict):
+                return {k: encode(v) for k, v in sorted(obj.items())}
+            if hasattr(obj, "__dataclass_fields__"):
+                return {
+                    k: encode(getattr(obj, k)) for k in sorted(obj.__dataclass_fields__)
+                }
+            if isinstance(obj, list):
+                return [encode(v) for v in obj]
+            return obj
+
+        payload = json.dumps(encode(self), sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+    def replace_ticket(self, ticket_id: str, **kwargs) -> None:
+        self.tickets[ticket_id] = replace(self.tickets[ticket_id], **kwargs)
+
+    def replace_order(self, order_id: str, **kwargs) -> None:
+        self.orders[order_id] = replace(self.orders[order_id], **kwargs)
+
+    def replace_customer(self, customer_id: str, **kwargs) -> None:
+        self.customers[customer_id] = replace(self.customers[customer_id], **kwargs)
+
+    def append_ticket_note(self, ticket_id: str, note: str) -> None:
+        ticket = self.tickets[ticket_id]
+        # `notes` is typed tuple[str, ...], but dataclasses.replace() (used
+        # by AMBIGUITY's clone_entity_into with model-supplied overrides,
+        # which come from JSON and default to list) doesn't enforce that at
+        # runtime -- coerce defensively so a prior list-typed notes field
+        # doesn't crash the whole run with `list + tuple`.
+        self.replace_ticket(ticket_id, notes=tuple(ticket.notes) + (note,))
+
+    # ---- generic entity protocol ------------------------------------
+    # injection.py's apply_injection() and reachability.py's default
+    # precondition checker are written against these five methods, not
+    # against `self.tickets`/`self.orders`/`self.customers` by name --
+    # that's the seam that lets the same injection engine (STALE_READ,
+    # AMBIGUITY, CONTRADICTION/LATE_INFO/PROMPT_INJECTION) work against a
+    # structurally different domain's own world, as long as that domain's
+    # world class implements these same five methods over its own entity
+    # types. This is a thin wrapper around the concrete tickets/orders/
+    # customers dicts above -- additive, not a replacement, so nothing
+    # above changes behavior.
+
+    def entity_store(self, entity_type: str) -> dict:
+        try:
+            return getattr(self, _ENTITY_STORES[entity_type])
+        except KeyError:
+            raise ValueError(f"unknown entity type {entity_type!r}") from None
+
+    def entity_exists(self, entity_type: str, entity_id: str) -> bool:
+        return entity_id in self.entity_store(entity_type)
+
+    def get_entity(self, entity_type: str, entity_id: str):
+        return self.entity_store(entity_type)[entity_id]
+
+    def set_entity_field(self, entity_type: str, entity_id: str, field_name: str, value) -> None:
+        store = self.entity_store(entity_type)
+        store[entity_id] = replace(store[entity_id], **{field_name: value})
+
+    def clone_entity(self, entity_type: str, source_id: str, new_id: str, overrides: dict) -> None:
+        clone_entity_into(self, entity_type, source_id, new_id, **overrides)
+
+    def append_note(self, entity_type: str, entity_id: str, note: str) -> None:
+        field_name = _NOTES_FIELD_BY_ENTITY_TYPE.get(entity_type)
+        if field_name is None:
+            raise ValueError(f"entity type {entity_type!r} has no notes field to append to")
+        store = self.entity_store(entity_type)
+        entity = store[entity_id]
+        current = getattr(entity, field_name)
+        # same defensive tuple-coercion as append_ticket_note, for the same reason.
+        store[entity_id] = replace(entity, **{field_name: tuple(current) + (note,)})
+
+
+_ENTITY_STORES = {
+    "ticket": "tickets",
+    "order": "orders",
+    "customer": "customers",
+}
+
+_NOTES_FIELD_BY_ENTITY_TYPE = {
+    "ticket": "notes",
+}
+"""Which entity types have an appendable notes/history field, and what
+it's called. CONTRADICTION/LATE_INFO/PROMPT_INJECTION can only target
+entity types listed here. A different domain's world class defines its
+own mapping for its own entity types -- this one is specific to the
+ticket-support domain."""
+
+
+def clone_entity_into(world: WorldState, entity_type: str, source_id: str, new_id: str, **overrides) -> None:
+    """Clones a ticket/order/customer under a new id, with optional field
+    overrides -- how AMBIGUITY injections plant a fresh near-duplicate
+    record mid-run. Raises KeyError if source_id or new_id/entity_type is
+    invalid; callers apply this to a live WorldState, not a spec.
+    """
+    store_name = _ENTITY_STORES[entity_type]
+    store = getattr(world, store_name)
+    # `new_id` is authoritative -- an "id" key in overrides (e.g. a
+    # redundant model-supplied field) would otherwise collide with it as a
+    # duplicate replace() keyword argument.
+    overrides = {k: v for k, v in overrides.items() if k != "id"}
+    clone = replace(store[source_id], id=new_id, **overrides)
+    store[new_id] = clone