commerce-trust-safety

Trust and safety rules

commerce_common/ is commerce-common/commerce_common/, shopping_agent/ is shopping-agent/core/shopping_agent/, and merchant_agent/ is merchant-agent/core/merchant_agent/; docs/safety.md lists the same rules. A rule inside a tool call holds on all three paths, which share one executor (commerce-architecture); rules 10 and 15 name the paths they run on. Merchant staging, guardrails, approval, and marketplace posture are in commerce-merchant-operations.

Fence third-party content

1. Every tool result from catalog, review, policy, order, metric, message, or web content goes through

Fence.fence_payload (commerce_common/fencing.py): NFKC-normalized, invisible and control characters removed, fence markers, forged turn markers, and special tokens replaced, wrapped in the role's label, and cut at max_fenced_chars. The executor's _fenced applies it to every handler.

1. The label and the notice are per-role constants (STOREFRONT_FENCE in shopping_agent/fencing.py, MERCHANT_FENCE in

merchant_agent/fencing.py); the notice appears once, in the static prompt, with nothing untrusted in it.

1. The per-request block (profile, cart, memory facts, page, store context) sits inside the same fence after the cache

breakpoint (build_dynamic_context in each role's prompt.py); backend context blocks have their own cap.

1. A model-supplied result count is clamped to max_search_results (clamp_limit in commerce_common/execution.py).

Gate writes on provenance and caps

1. A cart write accepts only ids in ShoppingSessionState.seen_products, filled by the session's catalog and order reads

(check_provenance and remember_order_items in shopping_agent/gates.py); update and remove also accept a line already in the cart. Merchant staging accepts only ids in seen_listings and read_listings, apply and discard only ids in seen_changes (merchant_agent/gates.py; commerce-merchant-operations).

1. max_quantity_per_item caps the line after the write and max_cart_lines the cart, under a session lock

(gated_add_to_cart in shopping_agent/gates.py; caps in shopping_agent/config.py). The lock is per process, so StorefrontBackend cart methods enforce them too; eligibility, pricing, and inventory are the backend's in both roles.

1. Nothing in either interface charges or places an order: checkout renders the cart (enrich_checkout in

shopping_agent/enrichment.py) and the host completes it; post-purchase care is reads, with no cancel or refund tool.

1. Provenance lives on the session state (ShoppingSessionState, MerchantSessionState), saved with the session when

the request or turn ends (SessionStore in examples/demo_common/sessions.py, a versioned state document beside the transcript), so a request on another process loads it. Each map keeps its newest PROVENANCE_CAP records (remember in commerce_common/types.py); a dropped id needs a fresh read.

1. A component is validated, its products, orders, metrics, or changes are joined from those records, and ids without

provenance are dropped and reported (run_presentation in commerce_common/presentation.py; each role's enrichment.py; commerce-ui-tools).

Ground the answers that are figures or terms

1. A terms question, an order question, or an unseen product id (GROUNDING_RULES in shopping_agent/grounding.py), or

a performance question or an apply request with nothing staged (merchant_agent/grounding.py), starts from the matching read: first_forced_tool in commerce_common/grounding.py picks it, the Messages API runtimes force it with tool_choice, and the SDK runtimes prefetch it when the rule has a prefetch form (ground in commerce_common/agent_sdk.py; the terms rule has none); the hosted path has the prompt only.

1. The lexicons are config tuples (policy_intent_terms, order_intent_terms, product_id_patterns, metrics_intent_terms,

and their cues); a deployment appends its own words, a gate flag turns a rule off, and neither changes prompt bytes.

Hold identity on the server

1. Session start binds the authenticated principal to an unguessable session id; later requests carry only that id, and

routes read the principal from the record (SessionStore.start and session_dependency in examples/demo_common/sessions.py). No request field or tool argument names a user, merchant, or operator; the MCP servers take the principal from their environment, a production server from its request.

1. Whether the principal owns a record (order, ticket, listing), and whether the step a call depends on has

happened, is the backend's check against its store; an id having provenance does not make it theirs or ready.

Bound what is remembered

1. Every fact on both write paths (save_memory and post-turn extraction) passes validate_fact in

commerce_common/memory.py: key of at most 64 characters, value of at most 200, one of the three MemoryCategory values, and the MemoryWriteFilter, which refuses identifier-shaped values by default; memory_blocked_patterns adds patterns, and a filter with checks replaces it (MemoryRuntime.build).

1. Extraction reads the last exchange's user and assistant text (transcript_text in commerce_common/turn.py), and

extract_and_store drops its batch when the subject was purged meanwhile; the Messages API runtimes run it (update_memory), the SDK host calls the runtime, and the hosted path writes through save_memory only.

1. memory_retention_days (with_retention), MemoryStore.delete_fact, MemoryStore.clear, and enable_memory hold

on every path without changing prompt or tool bytes; the examples expose read and delete routes (install_memory_routes in examples/demo_common/memory.py), and clear belongs in account deletion.

1. The subject is the shopper's user_id or the operation's merchant_id (memory_subject in each role's executor.py).

Refuse in the result, and keep the surface fixed

1. A held call returns a normal result naming its gate (ToolOutcome.held in commerce_common/streaming.py; the host's

tool_result event carries status: blocked), a failure returns an error result, and execute never raises.

1. The tool list is a function of the config: enable_web_search (default off) adds the tool, the SDK runtimes allow-list

the registered names, and the manifests enable tools one by one.

1. The reference MCP servers bind to loopback unless an environment variable states that an authenticating gateway is in

front (enforce_local_only_bind in commerce_common/mcp_server.py).

Two rules for adversarial evals

• Poisoned listings, reviews, and messages live in eval fixtures merged in for a run, outside demo and catalog data.
• Every refusal case has a should-serve counterpart in the same niche, so a suite catches over-refusal too (commerce-evals).