okstra 0.207.0 → 0.208.0

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

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal, TypedDict
+
+from ..json_boundary import load_owned_object, write_owned_object_atomic
+from ..paths import find_asset_root
+from ..report_language import is_language_tag
+
+OPERATION = "explain-flow"
+MODES = ("current", "pre", "post", "contribute", "reconcile")
+LEVELS = ("static", "execution-verified", "expected", "unknown")
+
+
+class BusinessEvidence(TypedDict):
+    projectId: str
+    path: str
+    line: int
+    endLine: int
+    excerpt: str
+
+
+class _BusinessFactRequired(TypedDict):
+    key: str
+    business: str
+    value: str
+    level: Literal["static", "execution-verified", "expected", "unknown"]
+    evidence: list[BusinessEvidence]
+
+
+class BusinessFact(_BusinessFactRequired, total=False):
+    executionEvidence: list[str]
+    relatedKeys: list[str]
+    aliases: list[str]
+
+
+class BusinessStep(TypedDict):
+    id: str
+    title: str
+    purpose: str
+    projectIds: list[str]
+    inputs: list[str]
+    outputs: list[str]
+    rules: list[str]
+    states: list[str]
+    failures: list[str]
+    retries: list[str]
+    recovery: list[str]
+    factKeys: list[str]
+    before: str
+    after: str
+    risks: list[str]
+    sideEffects: list[str]
+
+
+BusinessRelationship = TypedDict(
+    "BusinessRelationship",
+    {
+        "from": str,
+        "to": str,
+        "kind": Literal["call", "event", "queue", "shared-data", "file", "batch"],
+        "data": str,
+        "factKeys": list[str],
+    },
+)
+
+
+class BusinessResolution(TypedDict):
+    claimIds: list[str]
+    acceptedClaimId: str
+    reason: str
+
+
+class BusinessTerm(TypedDict):
+    term: str
+    meaning: str
+
+
+class BusinessResult(TypedDict):
+    title: str
+    summary: str
+    terms: list[BusinessTerm]
+    steps: list[BusinessStep]
+    relationships: list[BusinessRelationship]
+    facts: list[BusinessFact]
+    inspectedProjects: list[str]
+    gaps: list[str]
+    questions: list[str]
+    resolutions: list[BusinessResolution]
+
+
+class ProjectCandidate(TypedDict):
+    projectId: str
+    root: str
+
+
+class _SourceSnapshotRequired(ProjectCandidate):
+    head: str
+    digest: str
+    files: dict[str, str]
+    dirty: dict[str, str]
+    gaps: list[str]
+
+
+class SourceSnapshot(_SourceSnapshotRequired, total=False):
+    indexDigest: str
+    indexPatch: str
+    statusDigest: str
+
+
+class FlowRequestPayload(TypedDict):
+    project_root: str
+    question: str
+    mode: str
+    task_key: str
+    baseline: str
+    source_root: str | None
+    report_language: str
+    source_artifacts: list[str]
+    host_runtime: str
+
+
+class _FlowExecutionRequired(TypedDict):
+    schemaVersion: int
+    id: str
+    createdAt: str
+    request: FlowRequestPayload
+    projects: list[SourceSnapshot]
+    status: str
+    readOnlyAudit: dict[str, object]
+
+
+class FlowExecution(_FlowExecutionRequired, total=False):
+    sourceArtifactDigests: dict[str, str]
+    changes: list[dict[str, object]]
+    metadataPath: str
+    result: BusinessResult
+    reports: dict[str, str]
+    contribution: dict[str, list[str]]
+    reconciliation: dict[str, object]
+    error: str
+
+
+class TaskLinkRow(TypedDict):
+    id: str
+    mode: str
+    status: str
+    inputDigest: str
+    reports: dict[str, str]
+    summary: str
+    error: str
+
+
+class TaskLink(TypedDict):
+    schemaVersion: int
+    taskKey: str
+    executions: list[TaskLinkRow]
+
+
+class ClaimProducer(TypedDict):
+    executionId: str
+    taskKey: str
+    mode: str
+    metadataPath: str
+
+
+class SourceState(TypedDict):
+    root: str
+    digest: str
+    head: str
+
+
+class StoredClaim(BusinessFact):
+    id: str
+    sourceStates: dict[str, SourceState]
+    producer: ClaimProducer
+    producers: list[ClaimProducer]
+    createdAt: str
+    status: Literal["accepted", "conflict", "superseded"]
+
+
+class BusinessKnowledge(TypedDict):
+    schemaVersion: int
+    claims: list[StoredClaim]
+    resolutions: list[dict[str, object]]
+
+
+class BusinessFlowError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class FlowRequest:
+    project_root: Path
+    question: str
+    mode: str = "current"
+    task_key: str = ""
+    baseline: str = ""
+    source_root: Path | None = None
+    report_language: str = "en"
+    source_artifacts: tuple[str, ...] = ()
+    host_runtime: str = "claude-code"
+
+    def validate(self) -> None:
+        if not self.project_root.is_dir() or not self.question.strip():
+            raise BusinessFlowError(
+                "a project directory and business question are required"
+            )
+        if self.mode not in MODES:
+            raise BusinessFlowError(f"unknown explanation mode: {self.mode}")
+        if self.source_root is not None and not self.source_root.is_dir():
+            raise BusinessFlowError(f"source directory unavailable: {self.source_root}")
+        if not is_language_tag(self.report_language):
+            raise BusinessFlowError(
+                "report language must be a language tag such as en or ko"
+            )
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def fingerprint(value: object) -> str:
+    body = json.dumps(value, sort_keys=True, ensure_ascii=False, allow_nan=False)
+    return hashlib.sha256(body.encode("utf-8")).hexdigest()
+
+
+def business_root(project_root: Path) -> Path:
+    project = project_root.resolve(strict=True)
+    root = project / ".okstra" / "business"
+    if not root.resolve().is_relative_to(project):
+        raise BusinessFlowError("business artifact root escapes project")
+    return root
+
+
+def artifact_path(project_root: Path, *parts: str) -> Path:
+    root = business_root(project_root)
+    target = root.joinpath(*parts)
+    if not target.resolve().is_relative_to(root.resolve()):
+        raise BusinessFlowError("business artifact path escapes its root")
+    return target
+
+
+def schema_definition(name: str) -> dict[str, Any]:
+    relative = ("schemas", "business-flow-v1.schema.json")
+    root = find_asset_root(relative)
+    if root is None:
+        raise BusinessFlowError("business flow schema asset is unavailable")
+    schema = load_owned_object(
+        root.joinpath(*relative), artifact="business flow schema"
+    )
+    return {"$ref": f"#/$defs/{name}", "$defs": schema["$defs"]}
+
+
+def read_artifact(path: Path, name: str) -> dict[str, Any]:
+    return load_owned_object(
+        path, artifact=f"business flow {name}", schema=schema_definition(name)
+    )
+
+
+def write_artifact(path: Path, payload: dict[str, Any], name: str) -> None:
+    write_owned_object_atomic(
+        path, payload, artifact=f"business flow {name}", schema=schema_definition(name)
+    )