amfs-http-server 0.3.37__tar.gz → 0.3.39__tar.gz

{amfs_http_server-0.3.37 → amfs_http_server-0.3.39}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: amfs-http-server
-Version: 0.3.37
+Version: 0.3.39
 Summary: AMFS HTTP/REST API server with SSE support
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
-Requires-Dist: amfs-core>=0.3.32
-Requires-Dist: amfs>=0.5.22
+Requires-Dist: amfs-core>=0.3.37
+Requires-Dist: amfs>=0.5.27
 Requires-Dist: fastapi>=0.115
 Requires-Dist: httpx>=0.27
 Requires-Dist: sse-starlette>=2.0

{amfs_http_server-0.3.37 → amfs_http_server-0.3.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amfs-http-server"
-version = "0.3.37"
+version = "0.3.39"
 description = "AMFS HTTP/REST API server with SSE support"
 requires-python = ">=3.11"
 license = "Apache-2.0"
@@ -13,7 +13,7 @@ dependencies = [
     # this tree is what test_dependency_floors forbids.
     # 0.5.18 for AgentMemory.as_agent, which the agent detail page calls to list
     # an agent's entries as that agent rather than as the server.
-    "amfs>=0.5.22",
+    "amfs>=0.5.27",
     # 0.3.23 is real in the silent way: the write path calls
     # adapter.scope_counts(), which is a default on AdapterABC from 0.3.23. On an
     # older core the adapters that do not override it — filesystem, S3 — have no
@@ -27,7 +27,7 @@ dependencies = [
     # unexpected keyword, _scope_block swallows it, and the block disappears —
     # while an adapter that ignored the argument instead would name another
     # agent's private keys. Either way the floor is what makes the rule real.
-    "amfs-core>=0.3.32",
+    "amfs-core>=0.3.37",
     "fastapi>=0.115",
     "uvicorn[standard]>=0.32",
     "sse-starlette>=2.0",

{amfs_http_server-0.3.37 → amfs_http_server-0.3.39}/src/amfs_http/models.py

@@ -93,7 +93,11 @@ class SearchRequest(BaseModel):
     pattern_ref: str | None = None
     limit: int = 100
     sort_by: str = "confidence"
-    branch: str = "main"
+    # ``None`` rather than ``"main"`` so the server can tell a caller that
+    # named no branch from one that asked for main: the former may be routed
+    # onto a canary branch by the SaaS layer (``request.state.memory_branch``),
+    # the latter never is. The SDK omits the field when it is main.
+    branch: str | None = None
     depth: int = 3
     # When True (default) artifacts are demoted to the bottom of results; when
     # False they are excluded entirely.
@@ -118,7 +122,7 @@ class AggregateRequest(BaseModel):
     field: str | None = None
     group_by: str | None = None
     row_path: str | None = None
-    branch: str = "main"
+    branch: str | None = None  # see SearchRequest.branch
 
 
 class RetrieveRequest(BaseModel):
@@ -136,7 +140,7 @@ class RetrieveRequest(BaseModel):
     semantic_weight: float = 0.5
     recency_weight: float = 0.3
     confidence_weight: float = 0.2
-    branch: str = "main"
+    branch: str | None = None  # see SearchRequest.branch
     # When True (default) artifacts (stored source files) are demoted but still
     # returned; when False they are excluded entirely from results.
     include_artifacts: bool = True
@@ -178,6 +182,16 @@ class RetrieveRequest(BaseModel):
     #: breakdown, importance dimensions, integrity fields, long values trimmed).
     #: Roughly a third of the tokens of the full payload.
     compact: bool = False
+    #: The asking run's environment — ``{"model", "agent_version", "runtime",
+    #: "platform"}`` — from the SDK's session or the MCP identity. A procedure
+    #: whose ``preconditions`` contradict it is dropped from the hits (it is a
+    #: way of doing the task somewhere else) and the priors weight outcomes
+    #: recorded under another environment less. Nothing changes when omitted.
+    environment: dict[str, str] | None = None
+    #: Say ``abstain`` in the recommendation when nothing in scope has been
+    #: tried or validated, instead of staying silent. Opt-in; with it a client
+    #: can tell "no guidance" from "guidance not requested".
+    abstain: bool = False
 
 
 class ContextRequest(BaseModel):

{amfs_http_server-0.3.37 → amfs_http_server-0.3.39}/src/amfs_http/server.py

@@ -30,6 +30,7 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
 from datetime import UTC, datetime, timedelta, timezone
+from collections.abc import Mapping
 from typing import Any
 
 import uvicorn
@@ -53,6 +54,7 @@ from amfs_core.scope import SqlScope
 from amfs_core.ranking import keyword_coverage as _keyword_coverage
 from amfs_core.reuse_value import REUSE_VALUE_HEADER, reuse_value_block
 from amfs_core.capture import scan_captured_arguments, scan_captured_text
+from amfs_core.actions import CONTRAST_MIN_W as _CONTRAST_MIN_W
 from amfs_core.actions import actions_taken as derive_actions_taken
 from amfs_core.engine import read_tracker_scope
 from amfs_core.evidence import evidence_signal as _evidence_signal
@@ -70,6 +72,7 @@ from amfs_core.models import (
     MemoryEntry,
     SearchQuery,
     SemanticQuery,
+    SessionMetadata,
 )
 from amfs_core.pagination import (
     InvalidCursorError,
@@ -348,7 +351,9 @@ from amfs_core.evidence import (  # noqa: E402
     DISCREDIT_THRESHOLD,
     blend_local_evidence as _blend_local_evidence,
     is_synthetic_key as _is_synthetic_key,
+    locally_discredited as _locally_discredited,
     locally_valid as _locally_valid,
+    replacements_from_lessons as _replacements_from_lessons,
 )
 
 
@@ -903,12 +908,58 @@ async def _discredited_below_gate(
     ]
 
 
+def _as_utc(value: Any) -> datetime | None:
+    """A datetime or ISO string as an aware UTC datetime; ``None`` otherwise."""
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    if isinstance(value, str) and value:
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+        return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+    return None
+
+
+def _resolved_actions_from_lessons(
+    lessons: list[MemoryEntry], contrasts: list[dict[str, Any]]
+) -> dict[str, str]:
+    """``entry_key -> action_key``: for each entry a contrast lesson names
+    under ``avoid``, the action that resolved that task instead.
+
+    The lesson's own ``resolved_action`` where it carries one (written by
+    ``amfs_core.evidence.contrast_lesson`` from the record's actions); else
+    the priors contrast for the same ``outcome_ref`` — the lesson and the
+    contrast are two readings of one outcome, joined on its ref. Neither the
+    nearest contrast nor any other is applied to an entry no lesson ties it
+    to: the entry keys are the lesson's, the action is the outcome's, and an
+    avoided rule that no fail-then-succeed outcome named gets nothing.
+    """
+    by_ref = {
+        str(c.get("outcome_ref")): str(c["resolved_with"])
+        for c in contrasts
+        if c.get("outcome_ref") and c.get("resolved_with")
+    }
+    out: dict[str, str] = {}
+    for e in lessons:
+        value = e.value if isinstance(e.value, dict) else None
+        if not value or not isinstance(value.get("avoid"), list):
+            continue
+        action = value.get("resolved_action") or by_ref.get(str(value.get("outcome_ref")))
+        if not action:
+            continue
+        for spec in value["avoid"]:
+            out.setdefault(str(spec), str(action))
+    return out
+
+
 def _priors_for_retrieve(
     *,
     entity_path: str,
     text: str,
     embedder: Any,
     candidate_actions: list[str] | None,
+    environment: Mapping[str, Any] | None = None,
     query_vector: list[float] | None = None,
 ) -> dict[str, Any] | None:
     """Action priors for ``entity_path`` on tasks like ``text``.
@@ -925,6 +976,9 @@ def _priors_for_retrieve(
     Synchronous, and blocking on the sync adapter: callers on the event loop
     run it through ``_offload``. ``query_vector`` is the caller's embedding of
     ``text`` when it has one, so the model is not run a second time.
+    *environment* down-weights outcomes recorded under another model /
+    runtime / agent version (the rows carry ``session_metadata`` or an
+    ``environment`` column when the adapter returns it).
     """
     from amfs_core.actions import (
         PRIORS_K,
@@ -964,7 +1018,9 @@ def _priors_for_retrieve(
             rows = []
     if not rows:
         return None
-    block = aggregate_priors(rows, candidate_actions=candidate_actions)
+    block = aggregate_priors(
+        rows, candidate_actions=candidate_actions, environment=environment or None
+    )
     block["source"] = source
     block["entity_path"] = entity_path
     if source == "similar_outcomes" and rows:
@@ -980,6 +1036,94 @@ def _get_visibility_filter(request: Request):
     return getattr(request.state, "visibility_filter", None)
 
 
+#: ``request.state`` attribute a layer in front of these routes may set to move
+#: a session's *reads* onto a memory branch it never named. The SaaS layer sets
+#: it when the calling session is in the canary arm of a live repair canary.
+MEMORY_BRANCH_STATE = "memory_branch"
+#: ``request.state`` attribute holding attributes the same layer wants on the
+#: sealed trace — which canary the session was in and which arm. Merged
+#: server-side, after the caller's bag has been validated, so they are exempt
+#: from the client cap and cannot be forged from the body.
+TRACE_ATTRIBUTES_STATE = "trace_attributes"
+
+
+def _effective_branch(request: Request | None, branch: str | None) -> str:
+    """The branch a read should hit: the caller's when named, else routed, else main.
+
+    A caller that names a branch always gets that branch — an explicit
+    ``branch=main`` from a canary session still reads main, which is what a
+    repair tool inspecting the baseline needs. A caller that names none reads
+    whatever ``request.state.memory_branch`` says, which is how a session the
+    SaaS layer put in a canary arm reads the proposal without knowing it, and
+    ``main`` when nothing is set — the behaviour every route had before.
+
+    Reads only. Writes and commits never consult this: a canary session reads
+    its branch and writes main, because what the agent learns during the test
+    is the user's, not the proposal's.
+    """
+    # ``isinstance`` rather than truthiness: a handler invoked in-process (Pro
+    # composes several, and the tests do) receives the ``Query(...)`` sentinel
+    # as its default, and that object is truthy without being a branch.
+    if isinstance(branch, str) and branch.strip():
+        return branch.strip()
+    state = getattr(request, "state", None) if request is not None else None
+    routed = getattr(state, MEMORY_BRANCH_STATE, None) if state is not None else None
+    if isinstance(routed, str) and routed.strip():
+        return routed.strip()
+    return "main"
+
+
+#: Attribute keys only the routing layer may set. When it has made a decision
+#: for the request (``trace_attributes`` is present, even empty) a client's own
+#: claims under these keys are dropped: a session nothing routed must not be
+#: able to vote in a canary it was not in.
+ROUTED_ONLY_ATTRIBUTES = frozenset({"canary_fix_id", "canary_arm"})
+
+
+def _routed_trace_attributes(request: Request | None) -> dict[str, Any] | None:
+    """Attributes the layer in front of this route wants on the sealed trace.
+
+    ``None`` when no layer made a decision for this request; a dict — possibly
+    empty — when one did. Values are coerced to scalars the trace store
+    accepts; anything else is dropped rather than failing the commit.
+    """
+    state = getattr(request, "state", None) if request is not None else None
+    raw = getattr(state, TRACE_ATTRIBUTES_STATE, None) if state is not None else None
+    if not isinstance(raw, dict):
+        return None
+    out: dict[str, Any] = {}
+    for key, value in raw.items():
+        if not isinstance(key, str) or not key.strip():
+            continue
+        if isinstance(value, (str, int, float, bool)):
+            out[key.strip().lower()] = value
+    return out
+
+
+def _merge_routed_attributes(
+    request: Request | None, attributes: dict[str, Any] | None
+) -> dict[str, Any] | None:
+    """*attributes* with the routed stamps on top; ``None`` stays ``None`` when nothing is added.
+
+    The server's values win. A client must not be able to put itself in the
+    canary arm by sending ``canary_arm`` in its own bag, and the tally reads
+    only these keys to decide which arm a trace belongs to — so once the
+    routing layer has spoken for a request, the client's claims under those
+    keys are dropped even when the layer's answer was "not routed".
+    """
+    routed = _routed_trace_attributes(request)
+    if routed is None:
+        return attributes
+    merged = {
+        k: v for k, v in (attributes or {}).items()
+        if str(k).strip().lower() not in ROUTED_ONLY_ATTRIBUTES
+    }
+    merged.update(routed)
+    if not merged and attributes is None:
+        return None
+    return merged
+
+
 def _active_visibility_filter(request: Request):
     """Return the visibility filter when per-user scoping applies, else None.
 
@@ -1403,7 +1547,7 @@ async def read_entry_by_query(
     request: Request,
     entity_path: str = Query(...),
     key: str = Query(...),
-    branch: str = Query("main"),
+    branch: str | None = Query(None),
     response: Response = None,
     _auth: str | None = Depends(verify_api_key),
 ) -> dict[str, Any]:
@@ -1435,7 +1579,7 @@ async def read_entry(
     request: Request,
     entity_path: str,
     key: str,
-    branch: str = Query("main"),
+    branch: str | None = Query(None),
     response: Response = None,
     _auth: str | None = Depends(verify_api_key),
 ) -> dict[str, Any]:
@@ -1446,9 +1590,10 @@ async def _read_entry(
     request: Request,
     entity_path: str,
     key: str,
-    branch: str,
+    branch: str | None,
     response: Response | None = None,
 ) -> dict[str, Any]:
+    branch = _effective_branch(request, branch)
     mem = _get_memory()
     credited = False
     if _async_adapter is not None:
@@ -1494,10 +1639,11 @@ async def entry_quality(
     request: Request,
     entity_path: str,
     key: str,
-    branch: str = Query("main"),
+    branch: str | None = Query(None),
     _auth: str | None = Depends(verify_api_key),
 ) -> dict[str, Any]:
     """Compute a quality report for a stored entry on demand."""
+    branch = _effective_branch(request, branch)
     mem = _get_memory()
     # Read straight from the adapter — this is an internal/dashboard inspection,
     # not an agent recall, so it must NOT increment recall_count (doing so
@@ -1609,11 +1755,7 @@ async def write_entry(
 ) -> dict[str, Any]:
     mem = _get_memory()
 
-    type_map = {
-        "fact": MemoryType.FACT,
-        "belief": MemoryType.BELIEF,
-        "experience": MemoryType.EXPERIENCE,
-    }
+    type_map = {m.value: m for m in MemoryType}
     mt = type_map.get(req.memory_type.lower(), MemoryType.FACT)
 
     # The caller's identity lives on a per-request handle. This block awaits
@@ -1852,7 +1994,7 @@ async def write_entry(
 async def list_entries(
     request: Request,
     entity_path: str | None = Query(None),
-    branch: str = Query("main"),
+    branch: str | None = Query(None),
     include_superseded: bool = Query(False),
     limit: int | None = Query(None, ge=1, le=10_000),
     offset: int = Query(0, ge=0),
@@ -1872,6 +2014,7 @@ async def list_entries(
         "[TLS-DIAG] /entries tls_account=%s state_account=%s state_user=%s has_tenant_ctx=%s",
         _tls_acct, _state_acct, _state_user, _has_ctx,
     )
+    branch = _effective_branch(request, branch)
     mem = _get_memory()
     if limit is None and ENTRIES_DEFAULT_LIMIT > 0:
         limit = ENTRIES_DEFAULT_LIMIT
@@ -2068,7 +2211,7 @@ async def aggregate_entries_endpoint(
         )
 
     mem = _get_memory()
-    entries = mem.list(req.entity_path, branch=req.branch)
+    entries = mem.list(req.entity_path, branch=_effective_branch(request, req.branch))
 
     vis = _get_visibility_filter(request)
     if vis is not None and vis.should_filter():
@@ -2238,7 +2381,7 @@ async def search_entries(
     response: Response = None,
     _auth: str | None = Depends(verify_api_key),
 ) -> list[dict[str, Any]]:
-    branch = getattr(req, "branch", "main") or "main"
+    branch = _effective_branch(request, getattr(req, "branch", None))
     sq = SearchQuery(
         query=req.query,
         entity_path=req.entity_path,
@@ -2356,10 +2499,10 @@ async def retrieve_entries(
     """
     from datetime import datetime as _dt, timezone as _tz
 
-    from amfs_core.content import ARTIFACT_PENALTY, classify_artifact
+    from amfs_core.content import ARTIFACT_PENALTY, PROCEDURE_BOOST, classify_artifact
     from amfs_core.query_norm import normalize_temporal
 
-    branch = req.branch or "main"
+    branch = _effective_branch(request, req.branch)
     vis = _get_visibility_filter(request)
     embedder = _get_server_embedder()
 
@@ -2530,7 +2673,14 @@ async def retrieve_entries(
     # 4. Drop benchmark/system scratch namespaces from user recall, and the
     #    system-written contrast lessons: those are consumed by the briefing
     #    (folded into the discredited section as "replaced by") and are not
-    #    knowledge an agent should read or be credited for.
+    #    knowledge an agent should read or be credited for. The lessons this
+    #    query surfaced are kept aside for the avoid list, which names what
+    #    replaced each avoided entry the same way the briefing does.
+    lessons: list[MemoryEntry] = [
+        v["entry"] for v in candidates.values()
+        if _is_synthetic_key(getattr(v["entry"], "key", ""))
+        and not _is_excluded_entity(getattr(v["entry"], "entity_path", ""))
+    ]
     candidates = {
         k: v
         for k, v in candidates.items()
@@ -2540,10 +2690,13 @@ async def retrieve_entries(
 
     # 5. Visibility (account RLS already scoped the fetch; this adds per-user +
     #    room scoping) applied ONCE over the full merged set so lexical-only
-    #    hits are filtered exactly like semantic ones — no leak path.
+    #    hits are filtered exactly like semantic ones — no leak path. The
+    #    lessons kept aside are filtered the same way: a replacement link
+    #    read from a lesson the caller cannot see is a leak by another name.
     if vis is not None and vis.should_filter():
         allowed = {e.entry_key for e in vis.filter_entries([v["entry"] for v in candidates.values()])}
         candidates = {k: v for k, v in candidates.items() if k in allowed}
+        lessons = vis.filter_entries(lessons) if lessons else lessons
 
     # 6. Artifact awareness (column authoritative once backfilled; classify on
     #    the fly otherwise so demotion works immediately).
@@ -2594,17 +2747,34 @@ async def retrieve_entries(
     #     be conditioned on the query — and a discredited rule that still works
     #     for tasks like this one is kept, labelled ``contested``, rather than
     #     hidden from the one class that needs it.
+    #
+    #     The same record, read the other way: a *validated* rule whose two
+    #     most recent outcomes on tasks like this one were failures has
+    #     stopped working for this class of task, whatever its pooled label
+    #     says (``locally_discredited``). It leaves the ranked list for the
+    #     avoid list, with what replaced it. Grid v4 measured the alternative
+    #     — the rule kept its ``validated`` label and its rank through 4-7
+    #     failures on the same quirk, because the pooled record was long and
+    #     the failures few.
     local_evidence: dict[str, dict[str, Any]] = {}
     if _local_evidence_enabled() and topical in query_vectors and candidates:
         near_fn = getattr(_get_memory()._adapter, "evidence_near", None)
         if callable(near_fn):
+            from amfs_core.actions import PRIORS_MIN_SIMILARITY as _PRIORS_MIN_SIM
+
             by_relevance = sorted(
                 candidates.values(), key=lambda v: (v["sim"], v["keyword"]), reverse=True
             )
             head_keys = [v["entry"].entry_key for v in by_relevance[:LOCAL_EVIDENCE_HEAD]]
             try:
+                # The priors' absolute floor, under the relative weighting the
+                # adapter applies: an outcome on an unrelated task is not local
+                # evidence however alone it is.
                 local_evidence = await _offload(
-                    _db_executor, near_fn, head_keys, query_vectors[topical]
+                    _db_executor,
+                    functools.partial(near_fn, min_similarity=_PRIORS_MIN_SIM),
+                    head_keys,
+                    query_vectors[topical],
                 )
             except Exception:  # noqa: BLE001 - the pooled record stands
                 logger.debug("evidence_near failed", exc_info=True)
@@ -2614,6 +2784,8 @@ async def retrieve_entries(
     # entry_key -> (similarity, keyword) for the query-scoped shift reading.
     avoided_match: dict[str, tuple[float, float]] = {}
     rescued: set[str] = set()
+    # Validated by the pooled record, failed on the last two tasks like this.
+    locally_discredited: set[str] = set()
     if not req.include_discredited:
         kept_candidates: dict[str, dict[str, Any]] = {}
         for k, v in candidates.items():
@@ -2624,6 +2796,10 @@ async def retrieve_entries(
                 elif v["sim"] > 0.0 or v["keyword"] > 0.0:
                     avoided.append(v["entry"])
                     avoided_match[k] = (float(v["sim"]), float(v["keyword"]))
+            elif _locally_discredited(local_evidence.get(k)):
+                locally_discredited.add(k)
+                avoided.append(v["entry"])
+                avoided_match[k] = (float(v["sim"]), float(v["keyword"]))
             else:
                 kept_candidates[k] = v
         candidates = kept_candidates
@@ -2640,9 +2816,13 @@ async def retrieve_entries(
     keyword_weight = 0.15
     evidence_weight = req.evidence_weight
 
+    def _is_procedure(e: MemoryEntry) -> bool:
+        mt = getattr(e, "memory_type", None)
+        return str(getattr(mt, "value", mt)) == MemoryType.PROCEDURE.value
+
     def _composite(
         relevance: float, recency: float, conf: float, keyword: float, artifact: bool,
-        evidence: float = 0.0,
+        evidence: float = 0.0, procedure: bool = False,
     ) -> float:
         """The composite score, in one place because step 8 recomputes it.
 
@@ -2657,6 +2837,9 @@ async def retrieve_entries(
         outcomes; this term is what separates an author's untested 0.9 from a
         0.9 that has been confirmed a dozen times, and what pushes an entry
         with a mixed record below both.
+
+        *procedure* applies ``PROCEDURE_BOOST``: at equal relevance, how to do
+        the task ranks above a fact about it.
         """
         score = composite_score(
             relevance=relevance,
@@ -2671,7 +2854,34 @@ async def retrieve_entries(
             evidence_weight=evidence_weight,
             anchored=anchored,
         )
-        return score * ARTIFACT_PENALTY if artifact else score
+        if artifact:
+            score *= ARTIFACT_PENALTY
+        if procedure:
+            score *= PROCEDURE_BOOST
+        return score
+
+    # Environment scoping: a procedure whose stated environment preconditions
+    # contradict the asking run (``{"runtime": "python3.12"}`` against a
+    # python3.9 run) is a way of doing the task somewhere else. It is dropped
+    # from the hits and named in ``_meta.not_applicable`` so the agent knows a
+    # way exists. Without an environment on the request nothing is dropped.
+    environment = {k: v for k, v in (req.environment or {}).items() if v}
+    not_applicable: list[dict[str, Any]] = []
+    if environment:
+        from amfs_core.models import preconditions_status as _preconditions_status
+
+        kept_env: dict[Any, Any] = {}
+        for ck, slot in candidates.items():
+            entry = slot["entry"]
+            if _is_procedure(entry):
+                status, detail = _preconditions_status(entry.value, environment)
+                if status == "not_applicable":
+                    not_applicable.append({
+                        "entity_path": entry.entity_path, "key": entry.key, "why": detail,
+                    })
+                    continue
+            kept_env[ck] = slot
+        candidates = kept_env
 
     scored: list[tuple[MemoryEntry, float, dict[str, Any]]] = []
     for slot in candidates.values():
@@ -2688,6 +2898,7 @@ async def retrieve_entries(
             recency = 0.0
         conf = float(entry.confidence)
         artifact = _is_artifact(entry)
+        procedure = _is_procedure(entry)
         pooled = _evidence_signal(entry)
         local = local_evidence.get(entry.entry_key)
         evidence, local_w = _blend_local_evidence(pooled, local)
@@ -2709,6 +2920,7 @@ async def retrieve_entries(
             "evidence": evidence,
             "evidence_status": status,
             "is_artifact": artifact,
+            "is_procedure": procedure,
         }
         if local_w > 0.0 and local is not None:
             bd["evidence_local"] = {
@@ -2717,7 +2929,11 @@ async def retrieve_entries(
                 "n": int(local.get("n", 0)),
                 "weight": round(local_w, 3),
             }
-        scored.append((entry, _composite(sim, recency, conf, keyword, artifact, evidence), bd))
+        scored.append((
+            entry,
+            _composite(sim, recency, conf, keyword, artifact, evidence, procedure),
+            bd,
+        ))
 
     scored.sort(key=lambda t: t[1], reverse=True)
 
@@ -2765,6 +2981,7 @@ async def retrieve_entries(
                     _composite(
                         norm, bd["recency"], bd["confidence"], bd["keyword"],
                         bd["is_artifact"], bd.get("evidence", 0.0),
+                        bd.get("is_procedure", False),
                     ),
                     {**bd, "rerank": rs, "rerank_normalised": norm,
                      "rerank_absolute": absolute_score,
@@ -2865,13 +3082,16 @@ async def retrieve_entries(
             # or carries a rare query term the leader lacks (its lexical
             # coverage ahead by ADAPTIVE_K_KEYWORD_GAP) — the cases where the
             # leader's record, not its topic, put it first, and the agent
-            # should still see what the query was actually about.
+            # should still see what the query was actually about. A rescued
+            # peer — discredited by the pooled record, confirmed on tasks
+            # like this one — is read as validated here: the record that
+            # kept it is the local one.
             top_rel = float(head[0][2].get("relevance") or 0.0)
             top_kw = float(head[0][2].get("keyword") or 0.0)
             head = [head[0]] + [
                 t for t in head[1:]
                 if (
-                    t[0].evidence_status == "validated"
+                    (t[0].evidence_status == "validated" or t[0].entry_key in rescued)
                     and t[1] >= top_score * ADAPTIVE_K_KEEP_RATIO
                 )
                 or float(t[2].get("relevance") or 0.0) > top_rel
@@ -2880,49 +3100,15 @@ async def retrieve_entries(
         else:
             head = [t for t in head if t[1] >= top_score * ADAPTIVE_K_KEEP_RATIO] or head[:1]
 
-    render = _compact_entry_response if req.compact else _entry_to_response
-    out: list[dict[str, Any]] = []
-    for rank, (entry, score, breakdown) in enumerate(head):
-        data = _compact_entry_response(entry, rank=rank) if req.compact else render(entry)
-        data["_score"] = round(score, 4)
-        if entry.entry_key in rescued:
-            # The label the ranking used, not the pooled one the entry carries:
-            # to this query the rule is contested, not discredited, and the
-            # agent reads the top-level field.
-            data["evidence_status"] = breakdown.get("evidence_status")
-            data["_rescued"] = True
-        if req.compact:
-            data["_breakdown"] = {"evidence_status": breakdown.get("evidence_status")}
-        else:
-            data["_breakdown"] = {
-                k: round(v, 4) if isinstance(v, float) else v
-                for k, v in breakdown.items()
-            }
-        out.append(data)
-    if req.include_avoid and avoided:
-        avoided.sort(key=lambda e: (e.last_outcome_at or e.provenance.written_at), reverse=True)
-        for entry in avoided[:AVOID_LIST_MAX]:
-            # A preview, in compact mode: an avoid row's work is to name what
-            # stopped working and how it failed, and a 120-character head is
-            # enough to recognise it. Rendering it at rank 0 carried the whole
-            # value, which for three avoided entries cost more than the hits.
-            data = (
-                _compact_entry_response(entry, rank=_COMPACT_FULL_HITS) if req.compact
-                else render(entry)
-            )
-            data["_score"] = 0.0
-            data["_avoid"] = True
-            data["_breakdown"] = {
-                "evidence": -1.0,
-                "evidence_status": "discredited",
-                "failure_count": entry.failure_count,
-                "last_outcome": entry.last_outcome,
-            }
-            out.append(data)
-
     # 12. Action priors and a recommendation, as one trailing element the client
     #     asked for. What the entries cannot say — "tried here and failed",
     #     "nobody has tried X" — comes from the outcome record, not from memory.
+    #     Computed before the hits are rendered: the query-scoped shift it
+    #     reads also tightens the hit list (11b), and the contrast it finds
+    #     names what to do instead of an avoided entry.
+    meta: dict[str, Any] | None = None
+    priors: dict[str, Any] | None = None
+    shifted_local = False
     if req.include_priors and req.entity_path:
         from amfs_core.actions import recommend as _recommend
 
@@ -2940,6 +3126,7 @@ async def retrieve_entries(
             text=priors_text,
             embedder=embedder,
             candidate_actions=req.candidate_actions,
+            environment=environment,
             query_vector=priors_vec,
         )
         top = head[0][0] if head else None
@@ -3032,6 +3219,7 @@ async def retrieve_entries(
         top_shifted = bool(
             top is not None and not top_rescued and _regime_shifted(top, now=now)
         )
+        hit_statuses = [str(e.evidence_status) for e, _, _ in head if e.evidence_status]
         recommendation = _recommend(
             priors,
             agent_id=req.agent_id or "",
@@ -3044,13 +3232,20 @@ async def retrieve_entries(
             top_hit_shifted=top_shifted,
             regime_shift=shifted_local,
             regime_shift_at=_shift_at(shifted_local_entries),
+            abstain=req.abstain,
+            hit_statuses=hit_statuses,
             # ``action_stats`` is every outcome on the entity, no similarity:
             # a record that can name a winner but is not about this kind of
             # task, so a shift read over it does not send the agent exploring.
             priors_are_local=(priors or {}).get("source") != "action_stats",
         )
-        if priors is not None or recommendation is not None or shifted:
-            out.append({
+        if (
+            priors is not None or recommendation is not None or shifted
+            or req.abstain or not_applicable
+        ):
+            from amfs_core.actions import guidance_strength as _guidance_strength
+
+            meta = {
                 "_meta": True,
                 "priors": priors,
                 "recommendation": recommendation,
@@ -3058,7 +3253,131 @@ async def retrieve_entries(
                 "regime_shift_scope": (
                     "query" if shifted_local else ("entity" if shifted else None)
                 ),
-            })
+                # Rated over the query-scoped shift, like the recommendation:
+                # a rule that stopped working for another class of task does
+                # not thin the guidance for this one.
+                "guidance_strength": _guidance_strength(
+                    priors, hit_statuses, regime_shift=shifted_local
+                ),
+            }
+            if not_applicable:
+                meta["not_applicable"] = not_applicable
+    if meta is None and not_applicable:
+        # No priors asked for, but the environment dropped a procedure: say so
+        # in the same trailing element, so the client learns a way exists.
+        meta = {"_meta": True, "not_applicable": not_applicable}
+
+    # 11b. Under a query-scoped shift — a rule the query is about has stopped
+    #      working — the alternatives to the leader that the record has
+    #      already marked against on tasks like this are noise with a cost:
+    #      grid v4 found 5.4 discredited-or-contested rows in the context of
+    #      failing episodes against 3.0 in successes. Drop the non-leading
+    #      hits whose status is ``contested`` or whose local record on this
+    #      kind of task is more failure than success. Never below one hit,
+    #      and the leader itself is never dropped here: what to do about the
+    #      leader is the recommendation's call. A rescued hit is never weak:
+    #      it carries the ``contested`` label too, but it is in the list
+    #      because its local record says it works here — the opposite of
+    #      what the label means on a pooled record.
+    if req.adaptive_k and shifted_local and len(head) > 1:
+        def _weak_under_shift(t: tuple[MemoryEntry, float, dict[str, Any]]) -> bool:
+            if t[0].entry_key in rescued:
+                return False
+            bd = t[2]
+            if str(bd.get("evidence_status") or "") == "contested":
+                return True
+            local = bd.get("evidence_local") or {}
+            return float(local.get("failure") or 0.0) > float(local.get("success") or 0.0)
+
+        head = [head[0]] + [t for t in head[1:] if not _weak_under_shift(t)]
+
+    # 13. Render. Hits first, then the avoid list, then the trailing meta
+    #     element (clients lift it out by its ``_meta`` flag).
+    render = _compact_entry_response if req.compact else _entry_to_response
+    out: list[dict[str, Any]] = []
+    for rank, (entry, score, breakdown) in enumerate(head):
+        data = _compact_entry_response(entry, rank=rank) if req.compact else render(entry)
+        data["_score"] = round(score, 4)
+        if entry.entry_key in rescued:
+            # The label the ranking used, not the pooled one the entry carries:
+            # to this query the rule is contested, not discredited, and the
+            # agent reads the top-level field.
+            data["evidence_status"] = breakdown.get("evidence_status")
+            data["_rescued"] = True
+        if req.compact:
+            data["_breakdown"] = {"evidence_status": breakdown.get("evidence_status")}
+        else:
+            data["_breakdown"] = {
+                k: round(v, 4) if isinstance(v, float) else v
+                for k, v in breakdown.items()
+            }
+        out.append(data)
+    if req.include_avoid and avoided:
+        avoided.sort(key=lambda e: (e.last_outcome_at or e.provenance.written_at), reverse=True)
+        # What replaced each avoided entry, per entry: the entries a contrast
+        # lesson on this query says the task was resolved with (same reading
+        # as the briefing's ``discredited[].replaced_by``), and the action
+        # that resolved it — the lesson's own ``resolved_action`` where it
+        # carries one, else the priors contrast for the same outcome. A
+        # contrast the lessons do not tie to this entry says nothing about
+        # it: two avoided rules must not both claim the one fix.
+        replaced_by = _replacements_from_lessons(lessons) if lessons else {}
+        resolved_action = _resolved_actions_from_lessons(
+            lessons, (priors or {}).get("contrasts") or []
+        )
+        for entry in avoided[:AVOID_LIST_MAX]:
+            data = (
+                _compact_entry_response(entry, rank=_COMPACT_FULL_HITS) if req.compact
+                else render(entry)
+            )
+            data["_score"] = 0.0
+            data["_avoid"] = True
+            local_only = entry.entry_key in locally_discredited
+            replacements = list(replaced_by.get(entry.entry_key) or [])
+            action = resolved_action.get(entry.entry_key)
+            data["_breakdown"] = {
+                "evidence": -1.0,
+                "evidence_status": "discredited",
+                "failure_count": entry.failure_count,
+                "last_outcome": entry.last_outcome,
+                "locally_discredited": local_only,
+                "replaced_by": replacements,
+                "resolved_with_action": action,
+            }
+            if req.compact:
+                # An avoid row's work is to name what stopped working and what
+                # replaced it, not to restate the rule: the value it carried
+                # was, in grid v4, the text failing agents were still acting
+                # on. Compact mode already cut it to a preview; a one-liner
+                # that says so is the whole message. The field stays a string
+                # so every client parses the row as an entry.
+                #
+                # The date is the last *failure*: for a locally discredited
+                # rule the newest nearby outcome (a failure by construction —
+                # the entry's own ``last_outcome_at`` may be a later success
+                # on another class of task); otherwise the entry's last
+                # outcome when that was a failure, else nothing.
+                when = None
+                if local_only:
+                    recent = (local_evidence.get(entry.entry_key) or {}).get("recent") or []
+                    when = _as_utc(recent[0].get("committed_at")) if recent else None
+                elif entry.last_outcome is not None and not _evidence_is_success(entry.last_outcome):
+                    when = entry.last_outcome_at
+                parts = [
+                    "stopped working on tasks like this" if local_only else "discredited",
+                    f"last failure {when.date().isoformat()}" if when else "",
+                ]
+                if replacements:
+                    parts.append("replaced by " + ", ".join(
+                        r.rsplit("/", 1)[-1] for r in replacements[:3]
+                    ))
+                if action:
+                    parts.append(f"resolved instead with {action}")
+                data["value"] = "; ".join(p for p in parts if p)
+                data.pop("value_truncated", None)
+            out.append(data)
+    if meta is not None:
+        out.append(meta)
     return out
 
 
@@ -4199,6 +4518,10 @@ async def commit_outcome(
         raise HTTPException(
             status_code=422, detail=f"session_metadata.attributes: {exc}"
         ) from exc
+    # After validation, never before: the routing layer's stamps (which canary
+    # this session was in, and which arm) are the server's, so they are exempt
+    # from the client's key cap and overwrite anything the body claimed.
+    client_attributes = _merge_routed_attributes(request, client_attributes) or {}
     client_llm_calls = client_meta.get("llm_calls")
     if not isinstance(client_llm_calls, list):
         client_llm_calls = []
@@ -4512,6 +4835,33 @@ async def save_trace(
                 session_id=trace.session_id,
             ),
         })
+    raw_meta = body.get("session_metadata") if isinstance(body, dict) else None
+    # The routing layer's stamps, on the same footing as in /outcomes: this is
+    # the other request a routed session's trace can arrive on, and a canary
+    # arm that is stamped on one path and not the other is a tally that counts
+    # SDK sessions in neither arm. Written onto the trace that is saved and onto
+    # the raw metadata that is sealed, since the seal prefers the raw body when
+    # there is one and the trace's own metadata when there is not. Through the
+    # same merge as /outcomes, so a decided-but-unrouted request (``{}``) drops
+    # the client's own canary claims here too — this is the path every
+    # HttpAdapter commit seals on, since ``trace_follows`` skips the other.
+    if _routed_trace_attributes(req) is not None:
+        meta = trace.session_metadata or SessionMetadata()
+        existing = getattr(meta, "attributes", None)
+        merged = _merge_routed_attributes(
+            req, dict(existing) if isinstance(existing, dict) else {}
+        )
+        trace = trace.model_copy(
+            update={"session_metadata": meta.model_copy(update={"attributes": merged or {}})}
+        )
+        if isinstance(raw_meta, dict):
+            raw_attrs = raw_meta.get("attributes")
+            raw_meta = {
+                **raw_meta,
+                "attributes": _merge_routed_attributes(
+                    req, dict(raw_attrs) if isinstance(raw_attrs, dict) else {}
+                ) or {},
+            }
     # Both DB round trips off the event loop; the seal takes its own lock on
     # the trace store, and nothing here reads the shared handle's tracker, so
     # unlike /outcomes this path needs no serialisation of its own.
@@ -4522,7 +4872,6 @@ async def save_trace(
     # is sealed, so the immutable copy carries the persisted id; the raw body is
     # passed alongside because ``model_validate`` above dropped the
     # ``session_metadata`` keys the Pro recorder's spans travel in.
-    raw_meta = body.get("session_metadata") if isinstance(body, dict) else None
     immutable_trace_id = await _offload(
         _db_executor, _auto_seal_trace, mem, saved, session_metadata=raw_meta
     )
@@ -7853,6 +8202,11 @@ async def get_briefing(
     credit_reuse: bool = Query(False),
     compact: bool = Query(False),
     since: datetime | None = Query(None),
+    branch: str | None = Query(None),
+    env_model: str | None = Query(None),
+    env_agent_version: str | None = Query(None),
+    env_runtime: str | None = Query(None),
+    env_platform: str | None = Query(None),
     # See retrieve_entries: injected on the type, defaulted so the handler stays
     # callable in-process without one.
     response: Response = None,
@@ -7863,6 +8217,11 @@ async def get_briefing(
     *compact* returns only the lead entity digest with its hot context and
     evidence sections, narrative trimmed. *since* trims the list sections to
     what changed after that moment — the delta since the last briefing.
+    *branch* reads the hot context and evidence sections from that memory
+    branch instead of ``main`` — how a repair branch or a canary is briefed
+    before it is merged. The ``env_*`` parameters describe the asking run;
+    with them each procedure in the lead digest is marked applicable or not
+    against its environment preconditions.
 
     *credit_reuse* books the briefing as a real read of the knowledge it
     surfaces. It is off by default and has to be asked for, because the same
@@ -7880,6 +8239,21 @@ async def get_briefing(
     }
     if since is not None:
         briefing_kwargs["since"] = since
+    environment = {
+        k: v for k, v in (
+            ("model", env_model), ("agent_version", env_agent_version),
+            ("runtime", env_runtime), ("platform", env_platform),
+        ) if v
+    }
+    if environment:
+        briefing_kwargs["environment"] = environment
+    # Resolved through the routing hook like every other read, then passed only
+    # when it is not main so a server-side ``briefing`` that predates the
+    # keyword keeps working (``mem.briefing`` here is always current, but the
+    # in-process callers in Pro compose this handler with their own memory).
+    branch = _effective_branch(request, branch)
+    if branch != "main":
+        briefing_kwargs["branch"] = branch
     digests = mem.briefing(**briefing_kwargs)
 
     vis = _get_visibility_filter(request)
@@ -7889,7 +8263,7 @@ async def get_briefing(
     # After visibility filtering, never before: an entry the caller may not see
     # must not be credited to them either.
     if credit_reuse:
-        await _credit_briefing_reuse(response, request, digests)
+        await _credit_briefing_reuse(response, request, digests, branch=branch)
 
     return {
         "digests": [d.model_dump(mode="json") for d in digests],