okstra 0.207.1 → 0.209.0

package/runtime/python/okstra_ctl/business_flow/store.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, cast
+
+from ..json_boundary import JsonBoundaryError
+from ..run_context import dir_flock
+from .contracts import (
+    BusinessFact,
+    BusinessFlowError,
+    BusinessKnowledge,
+    BusinessResolution,
+    ClaimProducer,
+    FlowExecution,
+    FlowRequest,
+    SourceSnapshot,
+    StoredClaim,
+    TaskLink,
+    TaskLinkRow,
+    artifact_path,
+    fingerprint,
+    now_iso,
+    read_artifact,
+    write_artifact,
+)
+from .source import candidate_projects, capture_project
+
+CONFIRMED_LEVELS = frozenset({"static", "execution-verified"})
+
+
+def task_link_path(project_root: Path, task_key: str) -> Path:
+    return artifact_path(
+        project_root, "task-links", fingerprint(task_key), "links.json"
+    )
+
+
+def read_task_links(project_root: Path, task_key: str) -> TaskLink:
+    path = task_link_path(project_root, task_key)
+    return (
+        cast(TaskLink, read_artifact(path, "taskLink"))
+        if path.exists()
+        else {"schemaVersion": 1, "taskKey": task_key, "executions": []}
+    )
+
+
+def record_task_execution(
+    request: FlowRequest, execution: FlowExecution, input_digest: str
+) -> TaskLinkRow:
+    path = task_link_path(request.project_root, request.task_key)
+    row: TaskLinkRow = {
+        "id": execution["id"],
+        "mode": request.mode,
+        "status": execution["status"],
+        "inputDigest": input_digest,
+        "reports": execution.get("reports", {}),
+        "summary": execution.get("result", {}).get("summary", ""),
+        "error": execution.get("error", ""),
+    }
+    with dir_flock(path.parent, ".links.lock"):
+        links = read_task_links(request.project_root, request.task_key)
+        if not any(item["id"] == row["id"] for item in links["executions"]):
+            links["executions"].append(row)
+        write_artifact(path, links, "taskLink")
+    return row
+
+
+def read_knowledge(project_root: Path) -> BusinessKnowledge:
+    path = artifact_path(project_root, "knowledge.json")
+    if not path.exists():
+        return {"schemaVersion": 1, "claims": [], "resolutions": []}
+    return cast(BusinessKnowledge, read_artifact(path, "knowledge"))
+
+
+def contribute_knowledge(
+    project_root: Path,
+    facts: list[BusinessFact],
+    projects: list[SourceSnapshot],
+    producer: ClaimProducer,
+) -> dict[str, Any]:
+    path = artifact_path(project_root, "knowledge.json")
+    with dir_flock(path.parent, ".knowledge.lock"):
+        data = read_knowledge(project_root)
+        claims = [_claim(fact, projects, producer) for fact in facts]
+        by_id = {row["id"]: row for row in data["claims"]}
+        added = []
+        for claim in claims:
+            if claim["id"] in by_id:
+                existing = by_id[claim["id"]]
+                if producer not in existing["producers"]:
+                    existing["producers"].append(producer)
+                for key in ("aliases", "relatedKeys", "executionEvidence"):
+                    if key in claim:
+                        existing[key] = list(
+                            dict.fromkeys(existing.get(key, []) + claim[key])
+                        )
+                continue
+            data["claims"].append(claim)
+            by_id[claim["id"]] = claim
+            added.append(claim["id"])
+        _mark_conflicts(data["claims"])
+        write_artifact(path, data, "knowledge")
+    return {
+        "added": added,
+        "conflicts": [
+            row["id"] for row in data["claims"] if row["status"] == "conflict"
+        ],
+    }
+
+
+def _claim(
+    fact: BusinessFact, projects: list[SourceSnapshot], producer: ClaimProducer
+) -> StoredClaim:
+    ids = {evidence["projectId"] for evidence in fact["evidence"]}
+    states = {
+        row["projectId"]: {
+            "root": row["root"],
+            "digest": row["digest"],
+            "head": row["head"],
+        }
+        for row in projects
+        if row["projectId"] in ids
+    }
+    identity = {
+        "key": fact["key"],
+        "value": fact["value"],
+        "level": fact["level"],
+        "sourceStates": {key: row["digest"] for key, row in states.items()},
+    }
+    return {
+        **fact,
+        "id": fingerprint(identity),
+        "sourceStates": states,
+        "producer": producer,
+        "producers": [producer],
+        "createdAt": now_iso(),
+        "status": "accepted",
+    }
+
+
+def _mark_conflicts(claims: list[StoredClaim]) -> None:
+    groups: dict[str, list[StoredClaim]] = {}
+    for claim in claims:
+        if claim["level"] not in CONFIRMED_LEVELS or claim["status"] == "superseded":
+            continue
+        if not claim["sourceStates"] or any(
+            not row["digest"] for row in claim["sourceStates"].values()
+        ):
+            continue
+        state = {key: row["digest"] for key, row in claim["sourceStates"].items()}
+        groups.setdefault(
+            fingerprint({"key": claim["key"], "states": state}), []
+        ).append(claim)
+    for rows in groups.values():
+        if len({row["value"] for row in rows}) > 1:
+            for row in rows:
+                row["status"] = "conflict"
+
+
+def resolve_conflicts(
+    project_root: Path, resolutions: list[BusinessResolution], producer: ClaimProducer
+) -> None:
+    path = artifact_path(project_root, "knowledge.json")
+    with dir_flock(path.parent, ".knowledge.lock"):
+        data = read_knowledge(project_root)
+        validate_resolutions(read_shared_knowledge(project_root), resolutions)
+        by_id = {row["id"]: row for row in data["claims"]}
+        for resolution in resolutions:
+            ids = resolution["claimIds"]
+            rows = [by_id[key] for key in ids if key in by_id]
+            for row in rows:
+                row["status"] = (
+                    "accepted"
+                    if row["id"] == resolution["acceptedClaimId"]
+                    else "superseded"
+                )
+            data["resolutions"].append(
+                {**resolution, "producer": producer, "createdAt": now_iso()}
+            )
+        write_artifact(path, data, "knowledge")
+
+
+def validate_resolutions(
+    data: BusinessKnowledge, resolutions: list[BusinessResolution]
+) -> None:
+    by_id = {row["id"]: row for row in data["claims"]}
+    visited = set()
+    for resolution in resolutions:
+        ids = set(resolution["claimIds"])
+        if (
+            not ids.issubset(by_id)
+            or resolution["acceptedClaimId"] not in ids
+            or ids & visited
+        ):
+            raise BusinessFlowError(
+                "conflict resolution references unknown or repeated claims"
+            )
+        rows = _resolution_rows(data["claims"], resolution)
+        state = fingerprint(
+            {key: source["digest"] for key, source in rows[0]["sourceStates"].items()}
+        )
+        group = {
+            row["id"]
+            for row in data["claims"]
+            if row["key"] == rows[0]["key"]
+            and row["status"] == "conflict"
+            and fingerprint(
+                {key: source["digest"] for key, source in row["sourceStates"].items()}
+            )
+            == state
+        }
+        if ids != group:
+            raise BusinessFlowError(
+                "conflict resolution must cover the complete active conflict"
+            )
+        visited.update(ids)
+
+
+def _resolution_rows(
+    claims: list[StoredClaim],
+    resolution: BusinessResolution,
+) -> list[StoredClaim]:
+    by_id = {row["id"]: row for row in claims}
+    ids = set(resolution["claimIds"])
+    if not ids.issubset(by_id) or resolution["acceptedClaimId"] not in ids:
+        raise BusinessFlowError("conflict resolution references unknown claims")
+    rows = [by_id[key] for key in ids]
+    states = {
+        fingerprint(
+            {key: state["digest"] for key, state in row["sourceStates"].items()}
+        )
+        for row in rows
+    }
+    if len({row["key"] for row in rows}) != 1 or len(states) != 1:
+        raise BusinessFlowError("conflict resolution mixes subjects or source versions")
+    return rows
+
+
+def read_shared_knowledge(project_root: Path) -> dict[str, Any]:
+    claims, resolutions, errors = [], [], []
+    candidates = candidate_projects(FlowRequest(project_root, "business"))
+    for candidate in candidates:
+        root = Path(candidate["root"])
+        try:
+            data = read_knowledge(root)
+            claims.extend({**claim, "ownerRoot": str(root)} for claim in data["claims"])
+            resolutions.extend(data["resolutions"])
+        except (OSError, BusinessFlowError, JsonBoundaryError) as exc:
+            errors.append(f"{candidate['projectId']}: {exc}")
+    _apply_shared_resolutions(claims, resolutions, errors)
+    _mark_conflicts(claims)
+    return {"claims": claims, "errors": errors}
+
+
+def _apply_shared_resolutions(
+    claims: list[StoredClaim],
+    resolutions: list[BusinessResolution],
+    errors: list[str],
+) -> None:
+    decisions: dict[frozenset[str], set[str]] = {}
+    for resolution in resolutions:
+        group = frozenset(resolution["claimIds"])
+        decisions.setdefault(group, set()).add(resolution["acceptedClaimId"])
+    disputed = {group for group, accepted in decisions.items() if len(accepted) > 1}
+    for resolution in resolutions:
+        try:
+            _resolution_rows(claims, resolution)
+        except BusinessFlowError as exc:
+            errors.append(f"Stored conflict resolution unavailable: {exc}")
+            continue
+        group = frozenset(resolution["claimIds"])
+        if group in disputed:
+            errors.append(
+                "Contradictory shared conflict resolutions: " + ", ".join(sorted(group))
+            )
+            continue
+        for row in claims:
+            if row["id"] in group:
+                row["status"] = (
+                    "accepted"
+                    if row["id"] == resolution["acceptedClaimId"]
+                    else "superseded"
+                )
+    for row in claims:
+        if any(row["id"] in group for group in disputed):
+            row["status"] = "conflict"
+
+
+def query_knowledge(
+    project_root: Path, query: str, source_root: Path | None = None
+) -> dict[str, Any]:
+    sources = {
+        row["projectId"]: row["root"]
+        for row in candidate_projects(
+            FlowRequest(project_root, query or "business", source_root=source_root)
+        )
+    }
+    tokens = set(re.findall(r"[\w-]{2,}", query.casefold()))
+    shared = read_shared_knowledge(project_root)
+    claims, errors = shared["claims"], shared["errors"]
+    selected = [
+        row
+        for row in claims
+        if any(
+            token
+            in (
+                row["business"]
+                + " "
+                + row["key"]
+                + " "
+                + row["value"]
+                + " "
+                + " ".join(row.get("aliases", []))
+            ).casefold()
+            for token in tokens
+        )
+    ]
+    keys = {row["key"] for row in selected}
+    while True:
+        related = keys | {key for row in selected for key in row.get("relatedKeys", [])}
+        expanded = [row for row in claims if row["key"] in related]
+        if {(row["ownerRoot"], row["id"]) for row in expanded} == {
+            (row["ownerRoot"], row["id"]) for row in selected
+        }:
+            break
+        selected, keys = expanded, {row["key"] for row in expanded}
+    states: dict[str, dict[str, Any]] = {}
+    for row in selected:
+        row["freshness"] = _freshness(row, states, sources)
+        row["selectionReason"] = "business terms or a connected claim key"
+    return {"claims": selected, "errors": errors, "query": query}
+
+
+def _freshness(
+    claim: dict[str, Any], cache: dict[str, dict[str, Any]], sources: dict[str, str]
+) -> str:
+    for project_id, expected in claim["sourceStates"].items():
+        root = sources.get(project_id)
+        if root is None:
+            return "unverified"
+        if root not in cache:
+            cache[root] = capture_project({"projectId": project_id, "root": root})
+        current = cache[root]
+        if current["gaps"] or not current["digest"]:
+            return "unverified"
+        if current["digest"] != expected["digest"]:
+            return "historical"
+    return "current" if claim["sourceStates"] else "unverified"
+
+
+def knowledge_packet(
+    project_root: Path, question: str, source_root: Path | None = None
+) -> str:
+    try:
+        result = query_knowledge(project_root, question, source_root)
+    except (OSError, BusinessFlowError, JsonBoundaryError) as exc:
+        return f"## Shared Business Knowledge\n\nKnowledge unavailable: {exc}\n"
+    lines = [
+        "## Shared Business Knowledge",
+        "",
+        "Preserve level, freshness, conflict and provenance. Recheck historical facts before relying on them.",
+        "",
+    ]
+    if not result["claims"]:
+        lines.append(
+            "No related stored claims were selected. Inspect source and use additional lookup when new business terms emerge."
+        )
+    for row in result["claims"]:
+        lines.extend(
+            [
+                f"- `{row['id']}`: {row['value']}",
+                f"  - Level: {row['level']}; freshness: {row['freshness']}; status: {row['status']}",
+                f"  - Owner: `{row['ownerRoot']}`; key: `{row['key']}`",
+            ]
+        )
+        lines.extend(
+            f"  - Evidence: `{item['projectId']}:{item['path']}:{item['line']}`"
+            for item in row["evidence"]
+        )
+    lines.extend(f"- Knowledge read error: {error}" for error in result["errors"])
+    lines.extend(
+        [
+            "",
+            "Additional lookup: `okstra explain-flow knowledge --query <business question>`",
+            "",
+        ]
+    )
+    return "\n".join(lines)

package/runtime/python/okstra_ctl/cmux.py

@@ -379,8 +379,8 @@ def plan_worker_height_resize(
     return None
 
 
-def shim_free_login_path() -> str:
-    """The user's login PATH with cmux's per-surface CLI shims removed.
+def shim_free_worker_path() -> str:
+    """The lead's inherited PATH with cmux's per-surface CLI shims removed.
 
     A cmux pane execs its command through `login … bash --noprofile --norc`, so
     none of the user's shell rc runs and PATH is cmux's own short list. What that
@@ -389,14 +389,23 @@ def shim_free_login_path() -> str:
     CLIs — and where a provider cmux does not know has no entry at all, which is
     a plain exit 127 inside the worker wrapper.
 
-    Restoring the login shell's PATH and dropping the shim entries gives the
-    wrapper what it would see in an ordinary terminal, which is what its own
-    `command -v <cli>` check expects. Nothing here is provider-specific, so
-    adding a provider does not touch this path.
+    The base is the PATH the lead process inherited, because the cli-wrapper
+    runtime (and every automatic retry, which always runs there) spawns with it.
+    A pane that resolved PATH from the login shell instead could pick another
+    install of the same CLI: on 2026-10-04 (fontsninja-v3-site dev-11118) the
+    login shell put Homebrew's codex 0.153.4 first, which rejects `gpt-6.1-sol`,
+    while the lead's PATH found nvm's 0.160.0, so every first attempt failed and
+    every retry passed. The login shell's PATH is the fallback when the inherited
+    one is empty after filtering.
     """
-    entries = _login_shell_path().split(os.pathsep)
+    path = _without_shims(os.environ.get("PATH", ""))
+    return path or _without_shims(_login_shell_path())
+
+
+def _without_shims(path_value: str) -> str:
     return os.pathsep.join(
-        entry for entry in entries if entry and SHIM_DIR_MARKER not in entry
+        entry for entry in path_value.split(os.pathsep)
+        if entry and SHIM_DIR_MARKER not in entry
     )
 
 
@@ -783,7 +792,7 @@ def _surface_from_split_echo(stdout: str) -> str:
 
 def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> None:
     line = worker_command_line(
-        cwd=cwd, argv=command, path_value=shim_free_login_path()
+        cwd=cwd, argv=command, path_value=shim_free_worker_path()
     )
     started = run_cmux(["respawn-pane", "--surface", surface_uuid, "--command", line])
     if started.returncode != 0:
@@ -939,11 +948,7 @@ def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
 
 
 def _login_shell_path() -> str:
-    """PATH as the user's own login shell resolves it.
-
-    Falls back to the inherited PATH: a worker started with a shim-filtered
-    inherited PATH is still better than one started with cmux's bare list.
-    """
+    """PATH as the user's own login shell resolves it, or '' when it cannot run."""
     shell = os.environ.get("SHELL", "") or "/bin/sh"
     try:
         result = subprocess.run(
@@ -954,9 +959,9 @@ def _login_shell_path() -> str:
             check=False,
         )
     except (OSError, subprocess.SubprocessError):
-        return os.environ.get("PATH", "")
+        return ""
     if result.returncode != 0 or not result.stdout.strip():
-        return os.environ.get("PATH", "")
+        return ""
     return result.stdout.strip()