devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/source_doc_assumptions.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import json
+from hashlib import sha256
+from typing import Any
+
+ASSUMPTION_STATUSES = {"open", "confirmed", "rejected", "superseded", "stale"}
+
+
+def _stable_hash(payload: Any) -> str:
+    return sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def _stable_id(prefix: str, payload: Any, *, size: int = 12) -> str:
+    return f"{prefix}{_stable_hash(payload)[:size]}"
+
+
+def default_assumptions_registry_payload() -> dict[str, Any]:
+    return {"assumptions": []}
+
+
+def normalize_assumptions_registry(payload: Any) -> dict[str, Any]:
+    raw = payload if isinstance(payload, dict) else {}
+    normalized = default_assumptions_registry_payload()
+    assumptions = raw.get("assumptions")
+    if not isinstance(assumptions, list):
+        assumptions = []
+    normalized["assumptions"] = [normalize_assumption_item(item) for item in assumptions if isinstance(item, dict)]
+    return normalized
+
+
+def normalize_assumption_item(item: dict[str, Any]) -> dict[str, Any]:
+    linkage = item.get("linkage")
+    if not isinstance(linkage, dict):
+        linkage = {}
+    doc_path = str(linkage.get("doc_path") or item.get("doc_path") or "").strip()
+    section_key = str(linkage.get("section_key") or item.get("section_key") or "").strip()
+    topic_key = str(linkage.get("topic_key") or item.get("topic_key") or "").strip()
+    assumption_key = str(item.get("assumption_key") or "").strip() or make_assumption_key(
+        doc_path=doc_path,
+        section_key=section_key,
+        topic_key=topic_key,
+    )
+    assumption_id = str(item.get("assumption_id") or "").strip() or assumption_key
+    status = str(item.get("status") or "open").strip().lower()
+    if status not in ASSUMPTION_STATUSES:
+        status = "open"
+
+    reason = str(item.get("reason") or item.get("reasoning") or "").strip()
+    source = str(item.get("source") or "unknown").strip() or "unknown"
+    confidence = str(item.get("confidence") or "low").strip().lower() or "low"
+    impact = str(item.get("impact") or "section_local").strip() or "section_local"
+
+    affected_docs = [str(value).strip() for value in (item.get("affected_docs") or []) if str(value).strip()]
+    if not affected_docs and doc_path:
+        affected_docs = [doc_path]
+    affected_sections = [str(value).strip() for value in (item.get("affected_sections") or []) if str(value).strip()]
+    if not affected_sections and section_key:
+        affected_sections = [section_key]
+    evidence = [str(value).strip() for value in (item.get("evidence") or []) if str(value).strip()]
+    unresolved_questions = [str(value).strip() for value in (item.get("unresolved_questions") or []) if str(value).strip()]
+
+    normalized = dict(item)
+    normalized["assumption_id"] = assumption_id
+    normalized["assumption_key"] = assumption_key
+    normalized["status"] = status
+    normalized["doc_path"] = doc_path
+    normalized["section_key"] = section_key
+    normalized["topic_key"] = topic_key
+    normalized["reason"] = reason
+    normalized["reasoning"] = reason
+    normalized["source"] = source
+    normalized["confidence"] = confidence
+    normalized["impact"] = impact
+    normalized["affected_docs"] = affected_docs
+    normalized["affected_sections"] = affected_sections
+    normalized["evidence"] = evidence
+    normalized["unresolved_questions"] = unresolved_questions
+    normalized["linkage"] = {
+        "doc_path": doc_path,
+        "section_key": section_key,
+        "topic_key": topic_key,
+        "affected_docs": affected_docs,
+        "affected_sections": affected_sections,
+    }
+    return normalized
+
+
+def make_assumption_key(*, doc_path: str, section_key: str, topic_key: str) -> str:
+    return _stable_id(
+        "asmk_",
+        {
+            "doc_path": doc_path,
+            "section_key": section_key,
+            "topic_key": topic_key,
+        },
+        size=16,
+    )
+
+
+def make_assumption_id(
+    *,
+    doc_path: str,
+    section_key: str,
+    topic_key: str,
+    current_value: Any,
+    message_id: str,
+) -> str:
+    return _stable_id(
+        "asm_",
+        {
+            "doc_path": doc_path,
+            "section_key": section_key,
+            "topic_key": topic_key,
+            "current_value": current_value,
+            "message_id": message_id,
+        },
+        size=16,
+    )
+
+
+def register_assumption(
+    registry_payload: dict[str, Any],
+    *,
+    doc_path: str,
+    section_key: str,
+    topic_key: str,
+    current_value: Any,
+    reasoning: str,
+    source: str,
+    message_id: str,
+    confidence: str | None = None,
+) -> dict[str, Any]:
+    registry = normalize_assumptions_registry(registry_payload)
+    assumption_key = make_assumption_key(doc_path=doc_path, section_key=section_key, topic_key=topic_key)
+    assumption_id = make_assumption_id(
+        doc_path=doc_path,
+        section_key=section_key,
+        topic_key=topic_key,
+        current_value=current_value,
+        message_id=message_id,
+    )
+
+    for item in registry["assumptions"]:
+        if str(item.get("assumption_key") or "") != assumption_key:
+            continue
+        if str(item.get("status") or "open") != "open":
+            continue
+        if _json_equal(item.get("current_value"), current_value):
+            item.update(
+                {
+                    "assumption_id": assumption_id,
+                    "reason": reasoning,
+                    "reasoning": reasoning,
+                    "source": source,
+                    "confidence": confidence or item.get("confidence") or ("medium" if source == "grounded_inference" else "low"),
+                    "impact": str(item.get("impact") or "section_local"),
+                    "affected_docs": [doc_path],
+                    "affected_sections": [section_key] if section_key else [],
+                    "evidence": [f"{doc_path}:{section_key}:{topic_key}".strip(":")],
+                    "unresolved_questions": list(item.get("unresolved_questions") or []),
+                    "last_updated_from_message_id": message_id,
+                    "status": "open",
+                    "superseded_by_assumption_id": None,
+                }
+            )
+            return registry
+
+    for item in registry["assumptions"]:
+        if str(item.get("assumption_key") or "") != assumption_key:
+            continue
+        if str(item.get("status") or "open") != "open":
+            continue
+        item["status"] = "superseded"
+        item["superseded_by_assumption_id"] = assumption_id
+
+    registry["assumptions"].append(
+        normalize_assumption_item(
+            {
+                "assumption_id": assumption_id,
+                "assumption_key": assumption_key,
+                "status": "open",
+                "confidence": confidence or ("medium" if source == "grounded_inference" else "low"),
+                "source": source,
+                "impact": "section_local",
+                "doc_path": doc_path,
+                "section_key": section_key,
+                "topic_key": topic_key,
+                "current_value": current_value,
+                "reason": reasoning,
+                "reasoning": reasoning,
+                "affected_docs": [doc_path],
+                "affected_sections": [section_key] if section_key else [],
+                "evidence": [f"{doc_path}:{section_key}:{topic_key}".strip(":")],
+                "unresolved_questions": [],
+                "last_updated_from_message_id": message_id,
+                "superseded_by_assumption_id": None,
+            }
+        )
+    )
+    return registry
+
+
+def reconcile_assumptions_registry(
+    *,
+    registry_payload: dict[str, Any],
+    source_docs_by_name: dict[str, Any],
+    changed_docs: list[str] | None = None,
+) -> tuple[dict[str, Any], bool]:
+    registry = normalize_assumptions_registry(registry_payload)
+    changed_doc_names = {str(name).strip() for name in (changed_docs or []) if str(name).strip()}
+    mutated = False
+
+    for item in registry["assumptions"]:
+        doc_name = _doc_name_from_path(str(item.get("doc_path") or ""))
+        if changed_doc_names and doc_name not in changed_doc_names:
+            continue
+        explicit_value = resolve_linked_topic_value(
+            source_docs_by_name=source_docs_by_name,
+            doc_path=str(item.get("doc_path") or ""),
+            section_key=str(item.get("section_key") or ""),
+            topic_key=str(item.get("topic_key") or ""),
+        )
+        has_explicit = _has_explicit_value(explicit_value)
+        status = str(item.get("status") or "open")
+        current_value = item.get("current_value")
+
+        if status == "open":
+            if has_explicit and _json_equal(explicit_value, current_value):
+                item["status"] = "confirmed"
+                mutated = True
+            elif has_explicit:
+                item["status"] = "rejected"
+                mutated = True
+        elif status == "confirmed":
+            if not has_explicit:
+                item["status"] = "stale"
+                mutated = True
+            elif not _json_equal(explicit_value, current_value):
+                item["status"] = "superseded"
+                mutated = True
+        elif status == "stale" and has_explicit and _json_equal(explicit_value, current_value):
+            item["status"] = "confirmed"
+            mutated = True
+
+    return registry, mutated
+
+
+def resolve_linked_topic_value(
+    *,
+    source_docs_by_name: dict[str, Any],
+    doc_path: str,
+    section_key: str,
+    topic_key: str,
+) -> Any:
+    doc_name = _doc_name_from_path(doc_path)
+    payload = source_docs_by_name.get(doc_name)
+    if not isinstance(payload, dict):
+        return None
+    section_value = payload.get(section_key)
+    if section_key == "problem_statement":
+        return section_value
+    if section_key == "target_users" and topic_key == "primary_users":
+        return section_value
+    if section_key == "goals" and topic_key == "primary_goal":
+        return section_value[0] if isinstance(section_value, list) and section_value else None
+    if section_key == "scope" and topic_key == "initial_scope":
+        return section_value.get("in_scope") if isinstance(section_value, dict) else None
+    if section_key == "actors" and topic_key == "primary_users":
+        return section_value
+    if isinstance(section_value, dict):
+        return section_value.get(topic_key)
+    return section_value
+
+
+def _doc_name_from_path(doc_path: str) -> str:
+    return doc_path.strip().split("/")[-1]
+
+
+def _has_explicit_value(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return bool(value.strip())
+    if isinstance(value, (list, dict, tuple, set)):
+        return bool(value)
+    return True
+
+
+def _json_equal(left: Any, right: Any) -> bool:
+    return json.dumps(left, sort_keys=True) == json.dumps(right, sort_keys=True)