shellbrain 0.1.0__py3-none-any.whl

app/core/policies/read_policy/expansion.py

@@ -0,0 +1,132 @@
+"""This module defines explicit and implicit expansion stage helpers for read policy."""
+
+from typing import Any
+
+from app.boot.read_policy import resolve_read_payload_defaults
+from app.core.interfaces.repos import IReadPolicyRepo, ISemanticRetrievalRepo
+
+
+def expand_candidates(
+    direct_candidates: list[dict[str, Any]],
+    payload: dict[str, Any],
+    *,
+    read_policy: IReadPolicyRepo,
+    semantic_retrieval: ISemanticRetrievalRepo,
+) -> dict[str, list[dict[str, Any]]]:
+    """This function expands direct candidates via explicit links and semantic neighbors."""
+
+    payload = resolve_read_payload_defaults(payload)
+    explicit: list[dict[str, Any]] = []
+    implicit: list[dict[str, Any]] = []
+    expand = payload["expand"]
+    repo_id = payload["repo_id"]
+    include_global = bool(payload["include_global"])
+    kinds = payload.get("kinds")
+    min_strength = float(expand["min_association_strength"])
+    semantic_hops = int(expand["semantic_hops"])
+    max_association_depth = int(expand["max_association_depth"])
+
+    for direct_candidate in direct_candidates:
+        anchor_memory_id = direct_candidate["memory_id"]
+        anchor_score = float(direct_candidate.get("rrf_score", direct_candidate.get("score", 0.0)))
+
+        if expand["include_problem_links"]:
+            for neighbor in read_policy.list_problem_attempt_neighbors(
+                repo_id=repo_id,
+                include_global=include_global,
+                anchor_memory_id=anchor_memory_id,
+                kinds=kinds,
+            ):
+                explicit.append(
+                    {
+                        "memory_id": neighbor["memory_id"],
+                        "anchor_memory_id": anchor_memory_id,
+                        "anchor_score": anchor_score,
+                        "depth": 1,
+                        "expansion_type": neighbor["expansion_type"],
+                    }
+                )
+
+        if expand["include_fact_update_links"]:
+            for neighbor in read_policy.list_fact_update_neighbors(
+                repo_id=repo_id,
+                include_global=include_global,
+                anchor_memory_id=anchor_memory_id,
+                kinds=kinds,
+            ):
+                explicit.append(
+                    {
+                        "memory_id": neighbor["memory_id"],
+                        "anchor_memory_id": anchor_memory_id,
+                        "anchor_score": anchor_score,
+                        "depth": 1,
+                        "expansion_type": neighbor["expansion_type"],
+                    }
+                )
+
+        if expand["include_association_links"] and max_association_depth > 0:
+            seen_association_memory_ids = {str(anchor_memory_id)}
+            association_frontier = [str(anchor_memory_id)]
+            for depth in range(1, max_association_depth + 1):
+                next_association_frontier: list[str] = []
+                for frontier_memory_id in association_frontier:
+                    for neighbor in read_policy.list_association_neighbors(
+                        repo_id=repo_id,
+                        include_global=include_global,
+                        anchor_memory_id=frontier_memory_id,
+                        kinds=kinds,
+                        min_strength=min_strength,
+                    ):
+                        neighbor_memory_id = str(neighbor["memory_id"])
+                        if neighbor_memory_id in seen_association_memory_ids:
+                            continue
+                        seen_association_memory_ids.add(neighbor_memory_id)
+                        next_association_frontier.append(neighbor_memory_id)
+                        explicit.append(
+                            {
+                                "memory_id": neighbor_memory_id,
+                                "anchor_memory_id": anchor_memory_id,
+                                "anchor_score": anchor_score,
+                                "depth": depth,
+                                "expansion_type": neighbor["expansion_type"],
+                                "relation_strength": float(neighbor["strength"]),
+                                "relation_type": neighbor["relation_type"],
+                            }
+                        )
+                association_frontier = next_association_frontier
+                if not association_frontier:
+                    break
+
+        if semantic_hops > 0:
+            seen_memory_ids = {str(anchor_memory_id)}
+            frontier = [str(anchor_memory_id)]
+            for hop in range(1, semantic_hops + 1):
+                next_frontier: list[str] = []
+                for frontier_memory_id in frontier:
+                    for neighbor in semantic_retrieval.list_semantic_neighbors(
+                        repo_id=repo_id,
+                        include_global=include_global,
+                        anchor_memory_id=frontier_memory_id,
+                        kinds=kinds,
+                        limit=payload.get("limit"),
+                    ):
+                        neighbor_memory_id = str(neighbor["memory_id"])
+                        if neighbor_memory_id in seen_memory_ids:
+                            continue
+                        seen_memory_ids.add(neighbor_memory_id)
+                        next_frontier.append(neighbor_memory_id)
+                        implicit.append(
+                            {
+                                "memory_id": neighbor_memory_id,
+                                "anchor_memory_id": anchor_memory_id,
+                                "anchor_score": anchor_score,
+                                "hop": hop,
+                                "expansion_type": "semantic_neighbor",
+                                "neighbor_similarity": float(neighbor["score"]),
+                            }
+                        )
+                frontier = next_frontier
+                if not frontier:
+                    break
+
+    return {"explicit": explicit, "implicit": implicit}

app/core/policies/read_policy/fusion_rrf.py

@@ -0,0 +1,34 @@
+"""This module defines reciprocal-rank fusion helpers for direct seed ranking."""
+
+from typing import Any
+
+from app.boot.retrieval import get_retrieval_defaults
+
+
+def fuse_with_rrf(semantic: list[dict[str, Any]], keyword: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """This function merges lane candidates using reciprocal-rank fusion."""
+
+    defaults = get_retrieval_defaults()
+    k_rrf = defaults["k_rrf"]
+    lane_weights = {
+        "semantic": defaults["semantic_weight"],
+        "keyword": defaults["keyword_weight"],
+    }
+    fused: dict[str, dict[str, Any]] = {}
+
+    for lane_name, candidates in (("semantic", semantic), ("keyword", keyword)):
+        for rank, candidate in enumerate(candidates, start=1):
+            memory_id = candidate["memory_id"]
+            entry = fused.setdefault(
+                memory_id,
+                {
+                    "memory_id": memory_id,
+                    "rrf_score": 0.0,
+                    "rank_semantic": None,
+                    "rank_keyword": None,
+                },
+            )
+            entry[f"rank_{lane_name}"] = rank
+            entry["rrf_score"] += lane_weights[lane_name] / (k_rrf + rank)
+
+    return sorted(fused.values(), key=lambda item: (-float(item["rrf_score"]), str(item["memory_id"])))

app/core/policies/read_policy/lexical_query.py

@@ -0,0 +1,101 @@
+"""Helpers for constructing normalized lexical queries and document terms."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+_TOKEN_PATTERN = re.compile(r"[a-z0-9]+")
+_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "and",
+        "are",
+        "as",
+        "at",
+        "be",
+        "before",
+        "by",
+        "for",
+        "from",
+        "in",
+        "into",
+        "is",
+        "it",
+        "of",
+        "on",
+        "or",
+        "that",
+        "the",
+        "these",
+        "this",
+        "those",
+        "to",
+        "with",
+        "without",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class LexicalQuery:
+    """Normalized lexical query terms used by the keyword retrieval lane."""
+
+    raw_terms: tuple[str, ...]
+    informative_terms: tuple[str, ...]
+    terms: tuple[str, ...]
+    uses_stopword_fallback: bool
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedLexicalText:
+    """Normalized raw and informative token views for one text payload."""
+
+    raw_terms: tuple[str, ...]
+    informative_terms: tuple[str, ...]
+
+    def terms_for(self, query: LexicalQuery) -> tuple[str, ...]:
+        """Return the document term view aligned to the lexical query mode."""
+
+        if query.uses_stopword_fallback:
+            return self.raw_terms
+        return self.informative_terms
+
+
+def build_lexical_query(query_text: str) -> LexicalQuery:
+    """Build a normalized lexical query with strict informative-term semantics."""
+
+    normalized = normalize_lexical_text(query_text)
+    raw_terms = _unique_terms(normalized.raw_terms)
+    informative_terms = _unique_terms(normalized.informative_terms)
+    uses_stopword_fallback = not informative_terms and bool(raw_terms)
+    terms = raw_terms if uses_stopword_fallback else informative_terms
+    return LexicalQuery(
+        raw_terms=raw_terms,
+        informative_terms=informative_terms,
+        terms=terms,
+        uses_stopword_fallback=uses_stopword_fallback,
+    )
+
+
+def normalize_lexical_text(text: str) -> NormalizedLexicalText:
+    """Normalize text into raw and informative lexical token sequences."""
+
+    raw_terms = tuple(_TOKEN_PATTERN.findall(text.lower()))
+    informative_terms = tuple(term for term in raw_terms if term not in _STOPWORDS)
+    return NormalizedLexicalText(raw_terms=raw_terms, informative_terms=informative_terms)
+
+
+def _unique_terms(terms: tuple[str, ...]) -> tuple[str, ...]:
+    """Deduplicate terms while preserving original order."""
+
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for term in terms:
+        if term in seen:
+            continue
+        seen.add(term)
+        ordered.append(term)
+    return tuple(ordered)

app/core/policies/read_policy/pipeline.py

@@ -0,0 +1,93 @@
+"""This module defines read-policy pipeline orchestration for context-pack generation."""
+
+from typing import Any
+
+from app.boot.read_policy import resolve_read_payload_defaults
+from app.core.interfaces.repos import IKeywordRetrievalRepo, IMemoriesRepo, IReadPolicyRepo, ISemanticRetrievalRepo
+from app.core.interfaces.retrieval import IVectorSearch
+from app.core.policies.read_policy.context_pack_builder import assemble_context_pack
+from app.core.policies.read_policy.expansion import expand_candidates
+from app.core.policies.read_policy.fusion_rrf import fuse_with_rrf
+from app.core.policies.read_policy.scenario_lift import derive_scenarios
+from app.core.policies.read_policy.scoring import score_candidates
+from app.core.policies.read_policy.seed_retrieval import retrieve_seeds
+from app.core.policies.read_policy.utility_prior import apply_utility_prior
+
+
+def build_context_pack(
+    payload: dict[str, Any],
+    *,
+    keyword_retrieval: IKeywordRetrievalRepo,
+    memories: IMemoriesRepo,
+    semantic_retrieval: ISemanticRetrievalRepo,
+    read_policy: IReadPolicyRepo,
+    vector_search: IVectorSearch | None,
+) -> dict[str, Any]:
+    """This function orchestrates ratified read-policy stages into a final pack."""
+
+    payload = _resolve_read_defaults(payload)
+    seeds = retrieve_seeds(
+        payload,
+        semantic_retrieval=semantic_retrieval,
+        keyword_retrieval=keyword_retrieval,
+        vector_search=vector_search,
+    )
+    direct_candidates = fuse_with_rrf(seeds["semantic"], seeds["keyword"])
+    expanded_candidates = expand_candidates(
+        direct_candidates,
+        payload,
+        read_policy=read_policy,
+        semantic_retrieval=semantic_retrieval,
+    )
+    bucketed_candidates = {
+        "direct": direct_candidates,
+        "explicit": expanded_candidates["explicit"],
+        "implicit": expanded_candidates["implicit"],
+    }
+    scored_candidates = score_candidates(bucketed_candidates, payload)
+    adjusted_candidates = {
+        bucket_name: apply_utility_prior(candidates, payload)
+        for bucket_name, candidates in scored_candidates.items()
+    }
+    pack = assemble_context_pack(adjusted_candidates, payload)
+    hydrated_pack = _hydrate_pack_items(pack, memories)
+    return derive_scenarios(hydrated_pack, payload)["pack"]
+
+
+def _resolve_read_defaults(payload: dict[str, Any]) -> dict[str, Any]:
+    """Resolve mode-based read defaults for callers that omit a limit."""
+
+    return resolve_read_payload_defaults(payload)
+
+
+def _hydrate_pack_items(pack: dict[str, Any], memories: IMemoriesRepo) -> dict[str, Any]:
+    """Fill any missing display fields on selected pack items from the memories repository."""
+
+    missing_memory_ids: list[str] = []
+    seen_memory_ids: set[str] = set()
+    for section_name in ("direct", "explicit_related", "implicit_related"):
+        for item in pack[section_name]:
+            memory_id = str(item["memory_id"])
+            if ("kind" not in item or "text" not in item) and memory_id not in seen_memory_ids:
+                seen_memory_ids.add(memory_id)
+                missing_memory_ids.append(memory_id)
+
+    if missing_memory_ids:
+        hydrated_memories = {
+            memory.id: memory
+            for memory in memories.list_by_ids(missing_memory_ids)
+        }
+        for section_name in ("direct", "explicit_related", "implicit_related"):
+            for item in pack[section_name]:
+                if "kind" in item and "text" in item:
+                    continue
+                memory_id = str(item["memory_id"])
+                memory = hydrated_memories.get(memory_id)
+                if memory is None:
+                    raise ValueError(f"Missing hydrated memory for context-pack item: {memory_id}")
+                item.setdefault("kind", memory.kind.value)
+                item.setdefault("text", memory.text)
+                if "kind" not in item or "text" not in item:
+                    raise ValueError(f"Incomplete hydrated memory for context-pack item: {memory_id}")
+
+    return pack

app/core/policies/read_policy/scenario_lift.py

@@ -0,0 +1,11 @@
+"""This module defines scenario-lift stubs for deriving scenario abstractions from matches."""
+
+from typing import Any
+
+
+def derive_scenarios(pack: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+    """This function derives and ranks scenario projections from selected members."""
+
+    # TODO: Implement scenario projection schema once ratified fields are finalized.
+    _ = payload
+    return {"scenarios": [], "pack": pack}

app/core/policies/read_policy/scoring.py

@@ -0,0 +1,61 @@
+"""This module defines scoring helpers for explicit and implicit read candidates."""
+
+from typing import Any
+
+
+def score_candidates(candidates: dict[str, list[dict[str, Any]]], payload: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    """This function computes base scores used for bucket ranking and spillover."""
+
+    _ = payload
+    return {
+        "direct": _score_direct_candidates(candidates.get("direct", [])),
+        "explicit": _score_explicit_candidates(candidates.get("explicit", [])),
+        "implicit": _score_implicit_candidates(candidates.get("implicit", [])),
+    }
+
+
+def _score_direct_candidates(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Assign direct-bucket scores from reciprocal-rank fusion output."""
+
+    scored = []
+    for candidate in candidates:
+        item = dict(candidate)
+        item["score"] = float(candidate.get("rrf_score", candidate.get("score", 0.0)))
+        scored.append(item)
+    return _sort_scored_candidates(scored)
+
+
+def _score_explicit_candidates(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Assign explicit-bucket scores from anchor relevance and explicit-link metadata."""
+
+    scored = []
+    for candidate in candidates:
+        item = dict(candidate)
+        anchor_score = float(candidate.get("anchor_score", candidate.get("score", 0.0)))
+        depth = max(1, int(candidate.get("depth", 1)))
+        relation_strength = 1.0
+        if candidate.get("expansion_type") == "association":
+            relation_strength = float(candidate.get("relation_strength", 1.0))
+        item["score"] = anchor_score * relation_strength / depth
+        scored.append(item)
+    return _sort_scored_candidates(scored)
+
+
+def _score_implicit_candidates(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Assign implicit-bucket scores from anchor relevance, similarity, and hop count."""
+
+    scored = []
+    for candidate in candidates:
+        item = dict(candidate)
+        anchor_score = float(candidate.get("anchor_score", candidate.get("score", 0.0)))
+        hop = max(1, int(candidate.get("hop", 1)))
+        neighbor_similarity = float(candidate.get("neighbor_similarity", 1.0))
+        item["score"] = anchor_score * neighbor_similarity / hop
+        scored.append(item)
+    return _sort_scored_candidates(scored)
+
+
+def _sort_scored_candidates(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return candidates in deterministic descending score order."""
+
+    return sorted(candidates, key=lambda item: (-float(item["score"]), str(item["memory_id"])))

app/core/policies/read_policy/seed_retrieval.py

@@ -0,0 +1,54 @@
+"""This module defines semantic and keyword seed retrieval stage helpers."""
+
+from typing import Any
+
+from app.boot.thresholds import get_threshold_settings
+from app.core.interfaces.repos import IKeywordRetrievalRepo, ISemanticRetrievalRepo
+from app.core.interfaces.retrieval import IVectorSearch
+
+
+def retrieve_seeds(
+    payload: dict[str, Any],
+    *,
+    semantic_retrieval: ISemanticRetrievalRepo,
+    keyword_retrieval: IKeywordRetrievalRepo,
+    vector_search: IVectorSearch | None,
+) -> dict[str, list[dict[str, Any]]]:
+    """This function retrieves initial semantic and keyword candidate seeds."""
+
+    repo_id = payload["repo_id"]
+    include_global = bool(payload["include_global"])
+    kinds = payload.get("kinds")
+    limit = int(payload["limit"])
+    query_text = payload["query"]
+    query_vector = (
+        list(vector_search.embed_query(query_text))
+        if vector_search is not None
+        else []
+    )
+    thresholds = get_threshold_settings()
+
+    semantic = [
+        candidate
+        for candidate in semantic_retrieval.query_semantic(
+            repo_id=repo_id,
+            include_global=include_global,
+            query_vector=query_vector,
+            kinds=kinds,
+            limit=limit,
+        )
+        if float(candidate["score"]) >= thresholds["semantic_threshold"]
+    ]
+    keyword = [
+        candidate
+        for candidate in keyword_retrieval.query_keyword(
+            repo_id=repo_id,
+            mode=payload["mode"],
+            include_global=include_global,
+            query_text=query_text,
+            kinds=kinds,
+            limit=limit,
+        )
+        if float(candidate["score"]) >= thresholds["keyword_threshold"]
+    ]
+    return {"semantic": semantic, "keyword": keyword}

app/core/policies/read_policy/utility_prior.py

@@ -0,0 +1,11 @@
+"""This module defines weak late-stage utility-prior adjustments for near-tie ordering."""
+
+from typing import Any
+
+
+def apply_utility_prior(candidates: list[dict[str, Any]], payload: dict[str, Any]) -> list[dict[str, Any]]:
+    """This function applies bounded utility adjustments only for near-tie candidates."""
+
+    # TODO: Implement u_shrunk and alpha_utility near-tie nudging.
+    _ = payload
+    return candidates

app/core/policies/update_policy/__init__.py

@@ -0,0 +1 @@
+"""This package defines deterministic update-policy planning and execution."""

app/core/policies/update_policy/pipeline.py

@@ -0,0 +1,80 @@
+"""This module defines update-policy planning and execution helpers."""
+
+from uuid import uuid4
+from typing import Any
+
+from app.core.entities.associations import AssociationSourceMode, AssociationState
+from app.core.interfaces.unit_of_work import IUnitOfWork
+from app.core.policies._shared.executor import apply_side_effects
+from app.core.policies._shared.side_effects import make_side_effect
+
+
+def build_update_plan(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    """This function converts a validated update payload into deterministic side effects."""
+
+    update = payload["update"]
+    update_type = update["type"]
+    memory_id = payload["memory_id"]
+    repo_id = payload["repo_id"]
+
+    if update_type == "archive_state":
+        return [make_side_effect("memory.archive_state", {"memory_id": memory_id, "archived": update["archived"]})]
+
+    if update_type == "utility_vote":
+        return [
+            make_side_effect(
+                "utility_observation.append",
+                {
+                    "id": str(uuid4()),
+                    "memory_id": memory_id,
+                    "problem_id": update["problem_id"],
+                    "vote": update["vote"],
+                    "rationale": update.get("rationale"),
+                },
+            )
+        ]
+
+    if update_type == "fact_update_link":
+        return [
+            make_side_effect(
+                "fact_update.create",
+                {
+                    "id": str(uuid4()),
+                    "old_fact_id": update["old_fact_id"],
+                    "change_id": memory_id,
+                    "new_fact_id": update["new_fact_id"],
+                },
+            )
+        ]
+
+    if update_type == "association_link":
+        confidence = update.get("confidence")
+        salience = update.get("salience")
+        return [
+            make_side_effect(
+                "association.upsert_and_observe",
+                {
+                    "repo_id": repo_id,
+                    "edge_id": str(uuid4()),
+                    "from_memory_id": memory_id,
+                    "to_memory_id": update["to_memory_id"],
+                    "relation_type": update["relation_type"],
+                    "source_mode": AssociationSourceMode.AGENT.value,
+                    "state": AssociationState.TENTATIVE.value,
+                    "strength": confidence if confidence is not None else 0.5,
+                    "observation_id": str(uuid4()),
+                    "observation_source": "agent_explicit",
+                    "valence": confidence if confidence is not None else 0.5,
+                    "salience": salience if salience is not None else 0.5,
+                    "evidence_refs": list(update["evidence_refs"]),
+                },
+            )
+        ]
+
+    raise ValueError(f"Unsupported update type for plan build: {update_type}")
+
+
+def apply_update_plan(plan: list[dict[str, Any]], uow: IUnitOfWork) -> None:
+    """This function executes a deterministic update plan inside one transaction."""
+
+    apply_side_effects(plan, uow)

app/core/use_cases/__init__.py

@@ -0,0 +1 @@
+"""This package defines create, read, and update use-case entry points."""

app/core/use_cases/build_guidance.py

@@ -0,0 +1,85 @@
+"""Core guidance rules derived from trusted session state and telemetry."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from app.core.entities.guidance import GuidanceDecision
+from app.core.entities.identity import CallerIdentity, IdentityTrustLevel
+from app.core.entities.session_state import SessionState
+from app.core.interfaces.repos import ITelemetryRepo
+
+
+GUIDANCE_REMINDER_INTERVAL = timedelta(minutes=30)
+
+
+def should_emit_guidance_reminder(
+    *,
+    guidance: GuidanceDecision,
+    last_guidance_problem_id: str | None,
+    last_guidance_at: str | None,
+    now_iso: str,
+) -> bool:
+    """Return whether one reminder should be emitted for the current active problem."""
+
+    if guidance.problem_id is None:
+        return True
+    if last_guidance_problem_id != guidance.problem_id or last_guidance_at is None:
+        return True
+    last_seen = _parse_iso(last_guidance_at)
+    now = _parse_iso(now_iso)
+    return now - last_seen >= GUIDANCE_REMINDER_INTERVAL
+
+
+def build_pending_utility_guidance(
+    *,
+    repo_id: str,
+    caller_identity: CallerIdentity | None,
+    session_state: SessionState | None,
+    telemetry: ITelemetryRepo,
+    now_iso: str,
+    strong: bool = False,
+) -> list[GuidanceDecision]:
+    """Build pending utility-vote guidance for one trusted caller and active problem."""
+
+    if caller_identity is None or caller_identity.trust_level != IdentityTrustLevel.TRUSTED:
+        return []
+    if session_state is None or session_state.current_problem_id is None:
+        return []
+
+    candidates = telemetry.list_pending_utility_candidates(
+        repo_id=repo_id,
+        caller_id=caller_identity.canonical_id or "",
+        problem_id=session_state.current_problem_id,
+        since_iso=session_state.session_started_at,
+    )
+    if not candidates:
+        return []
+
+    decision = GuidanceDecision(
+        code="pending_utility_votes",
+        severity="info",
+        message=f"{len(candidates)} retrieved memories still need utility votes for the active problem.",
+        problem_id=session_state.current_problem_id,
+        memory_ids=[candidate.memory_id for candidate in candidates],
+        vote_scale_hint={"helpful": 1.0, "neutral": 0.0, "misleading": -1.0},
+    )
+    if strong:
+        return [decision]
+    if should_emit_guidance_reminder(
+        guidance=decision,
+        last_guidance_problem_id=session_state.last_guidance_problem_id,
+        last_guidance_at=session_state.last_guidance_at,
+        now_iso=now_iso,
+    ):
+        return [decision]
+    return []
+
+
+def _parse_iso(value: str) -> datetime:
+    """Parse one ISO timestamp into a timezone-aware datetime."""
+
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)