okstra 0.122.0 → 0.123.0

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import fnmatch
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+class DesignSurfaceError(ValueError):
+    """The planning structure cannot be mapped to deterministic design surfaces."""
+
+
+@dataclass(frozen=True)
+class SurfaceRule:
+    kind: str
+    path_tokens: tuple[str, ...]
+    path_suffixes: tuple[str, ...]
+    path_patterns: tuple[str, ...]
+    action_phrases: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class TriggerEvidence:
+    step: int | None
+    field: str
+    match: str
+
+
+@dataclass(frozen=True)
+class DesignSurfaceTrigger:
+    stage: int
+    kind: str
+    evidence: tuple[TriggerEvidence, ...]
+
+
+RULES = (
+    SurfaceRule(
+        "domain-contract",
+        ("/domain/",),
+        (),
+        (),
+        ("entity", "value object", "aggregate", "domain error"),
+    ),
+    SurfaceRule(
+        "persistence-schema",
+        ("/migrations/", "/orm/", "/repositories/"),
+        (".sql",),
+        (),
+        (
+            "create table",
+            "alter table",
+            "column",
+            "index",
+            "foreign key",
+            "unique constraint",
+        ),
+    ),
+    SurfaceRule(
+        "external-interface",
+        ("/ports/", "/adapters/", "/clients/", "/gateways/", "/infrastructure/http/"),
+        (),
+        (),
+        ("port", "adapter", "client", "gateway", "external api"),
+    ),
+    SurfaceRule(
+        "transaction-consistency",
+        (),
+        (),
+        (),
+        ("transaction", "outbox", "unit of work", "atomic write"),
+    ),
+    SurfaceRule(
+        "transformation-mapping",
+        ("/mappers/", "/parsers/", "/normalizers/"),
+        (),
+        (),
+        ("parse", "map", "canonical", "normalize", "transform"),
+    ),
+    SurfaceRule(
+        "lifecycle-state-machine",
+        (),
+        (),
+        (),
+        (
+            "claim",
+            "lease",
+            "retry",
+            "dead",
+            "dead-letter",
+            "state transition",
+            "state machine",
+        ),
+    ),
+    SurfaceRule(
+        "rollout-observability",
+        ("/monitoring/", "/deploy/", "/helm/"),
+        ("/values.yaml",),
+        ("*/values-*.yaml",),
+        ("rollout", "liveness", "alert", "feature flag"),
+    ),
+)
+
+
+def _normalise(value: object) -> str:
+    return unicodedata.normalize("NFC", str(value or "")).replace("\\", "/").lower()
+
+
+def _phrase_matches(text: str, phrase: str) -> bool:
+    return re.search(rf"(?<![\w-]){re.escape(phrase)}(?![\w-])", text) is not None
+
+
+def _selected_candidate(planning: Mapping[str, Any]) -> Mapping[str, Any]:
+    recommended = _normalise((planning.get("recommendedOption") or {}).get("name"))
+    candidates = [
+        row
+        for row in planning.get("optionCandidates") or []
+        if isinstance(row, Mapping)
+    ]
+    exact = [row for row in candidates if _normalise(row.get("name")) == recommended]
+    if len(exact) > 1:
+        raise DesignSurfaceError(
+            f"recommended option {recommended!r} is missing or ambiguous"
+        )
+    if len(exact) == 1:
+        return exact[0]
+    prefixed = [
+        row
+        for row in candidates
+        if _normalise(row.get("name")).startswith(
+            (recommended + ":", recommended + " —")
+        )
+    ]
+    if len(prefixed) != 1:
+        raise DesignSurfaceError(
+            f"recommended option {recommended!r} is missing or ambiguous"
+        )
+    return prefixed[0]
+
+
+def expected_prep_plan_item_id(stage: int, kind: str) -> str:
+    return f"P-Prep-S{stage}-{kind}"
+
+
+def _path_matches(rule: SurfaceRule, raw_path: object) -> bool:
+    path = "/" + _normalise(raw_path).lstrip("/")
+    return (
+        any(token in path for token in rule.path_tokens)
+        or any(path.endswith(suffix) for suffix in rule.path_suffixes)
+        or any(fnmatch.fnmatch(path, pattern) for pattern in rule.path_patterns)
+    )
+
+
+def _matching_rule_evidence(
+    *,
+    step: int | None,
+    field: str,
+    value: object,
+) -> list[tuple[str, TriggerEvidence]]:
+    text = _normalise(value)
+    matches = []
+    for rule in RULES:
+        path_hit = field == "files" and _path_matches(rule, text)
+        action_hit = field == "action" and any(
+            _phrase_matches(text, phrase) for phrase in rule.action_phrases
+        )
+        if path_hit or action_hit:
+            matches.append((rule.kind, TriggerEvidence(step, field, text)))
+    return matches
+
+
+def _stage_rows(planning: Mapping[str, Any]) -> dict[int, Mapping[str, Any]]:
+    rows = {
+        int(stage["stage"]): stage
+        for stage in planning.get("stages") or []
+        if isinstance(stage, Mapping) and isinstance(stage.get("stage"), int)
+    }
+    if not rows:
+        raise DesignSurfaceError("implementationPlanning.stages is empty")
+    return rows
+
+
+def _stage_for_selected_path(
+    path: str,
+    stages: Mapping[int, Mapping[str, Any]],
+) -> int:
+    normalised = _normalise(path)
+    matched = []
+    for stage_number, stage in stages.items():
+        files = [
+            _normalise(step.get("files"))
+            for step in stage.get("stepwiseExecution") or []
+            if isinstance(step, Mapping)
+        ]
+        path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
+        if any(re.search(path_pattern, cell) is not None for cell in files):
+            matched.append(stage_number)
+    if len(matched) != 1:
+        raise DesignSurfaceError(
+            f"selected option path {path!r} is not mapped to a stage exactly once"
+        )
+    return matched[0]
+
+
+def detect_design_surfaces(
+    planning: Mapping[str, Any],
+) -> list[DesignSurfaceTrigger]:
+    stages = _stage_rows(planning)
+    grouped: dict[tuple[int, str], list[TriggerEvidence]] = {}
+    for stage_number, stage in stages.items():
+        for step in stage.get("stepwiseExecution") or []:
+            if not isinstance(step, Mapping):
+                continue
+            step_number = (
+                int(step.get("step")) if isinstance(step.get("step"), int) else None
+            )
+            for field in ("files", "action"):
+                for kind, evidence in _matching_rule_evidence(
+                    step=step_number,
+                    field=field,
+                    value=step.get(field),
+                ):
+                    grouped.setdefault((stage_number, kind), []).append(evidence)
+    selected = _selected_candidate(planning)
+    for row in selected.get("fileStructure") or []:
+        if not isinstance(row, Mapping):
+            continue
+        path = str(row.get("path") or "")
+        stage_number = _stage_for_selected_path(path, stages)
+        for kind, evidence in _matching_rule_evidence(
+            step=None,
+            field="files",
+            value=path,
+        ):
+            grouped.setdefault((stage_number, kind), []).append(evidence)
+    rule_order = {rule.kind: index for index, rule in enumerate(RULES)}
+    return [
+        DesignSurfaceTrigger(stage, kind, tuple(grouped[(stage, kind)]))
+        for stage, kind in sorted(
+            grouped,
+            key=lambda key: (key[0], rule_order[key[1]]),
+        )
+    ]

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -4,7 +4,7 @@ This is a deliberately narrow JSON Schema implementation that supports
 exactly the keywords used by ``schemas/final-report-v1.0.schema.json``:
 
   type, required, properties, additionalProperties, enum, const, pattern,
-  minLength, minItems, maxItems, items, minimum, maximum, $ref ($defs),
+  minLength, minItems, maxItems, uniqueItems, items, minimum, maximum, $ref ($defs),
   oneOf, allOf, if/then/else, contains, not
 
 We do NOT depend on the ``jsonschema`` PyPI package because its
@@ -62,6 +62,32 @@ def _check_type(value: Any, expected: str) -> bool:
     return isinstance(value, _TYPE_PYTHON.get(expected, ()))
 
 
+def _json_schema_equal(left: Any, right: Any) -> bool:
+    if isinstance(left, bool) or isinstance(right, bool):
+        return isinstance(left, bool) and isinstance(right, bool) and left == right
+    if isinstance(left, (int, float)) or isinstance(right, (int, float)):
+        return (
+            isinstance(left, (int, float))
+            and isinstance(right, (int, float))
+            and left == right
+        )
+    if isinstance(left, list) or isinstance(right, list):
+        return (
+            isinstance(left, list)
+            and isinstance(right, list)
+            and len(left) == len(right)
+            and all(_json_schema_equal(a, b) for a, b in zip(left, right))
+        )
+    if isinstance(left, dict) or isinstance(right, dict):
+        return (
+            isinstance(left, dict)
+            and isinstance(right, dict)
+            and left.keys() == right.keys()
+            and all(_json_schema_equal(left[key], right[key]) for key in left)
+        )
+    return type(left) is type(right) and left == right
+
+
 def _resolve_ref(ref: str, root: dict) -> dict:
     """Resolve a ``#/$defs/Name`` style reference against ``root``."""
     if not ref.startswith("#/"):
@@ -165,6 +191,12 @@ class _Validator:
         max_items = schema.get("maxItems")
         if max_items is not None and len(instance) > max_items:
             self._err(path, f"array length {len(instance)} > maxItems {max_items}")
+        if schema.get("uniqueItems") is True and any(
+            _json_schema_equal(item, previous)
+            for index, item in enumerate(instance)
+            for previous in instance[:index]
+        ):
+            self._err(path, "array items are not unique")
         items = schema.get("items")
         if items is not None:
             for i, value in enumerate(instance):

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -14,6 +14,8 @@ from pathlib import Path
 from typing import Any
 
 from . import stage_targets
+from .design_prep import DesignPrepDecision, resolve_design_prep
+from .final_report_paths import final_report_data_path
 from .stage_reconcile import auto_reconcile_best_effort
 
 
@@ -32,6 +34,7 @@ class StageRunClaim:
     worktree_status: str
     worktree_note: str
     started_head_commit: str
+    design_prep_decision: DesignPrepDecision
     concurrent_stages: list[int] = field(default_factory=list)
 
 
@@ -50,6 +53,20 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
     return ImplementationStageError(str(exc))
 
 
+def _resolve_stage_design_prep(plan_path: Path, stage: int) -> DesignPrepDecision:
+    plan_data_path = final_report_data_path(plan_path)
+    if plan_data_path.is_file():
+        return resolve_design_prep(plan_data_path, stage)
+    return DesignPrepDecision(
+        outcome="proceed",
+        effective_items=(),
+        assumptions_to_inject=(),
+        warnings=("legacy-unassessed",),
+        request_paths=(),
+        reason="legacy plan has no design preparation assessment",
+    )
+
+
 def claim_implementation_stage_run(
     inp: Any,
     ctx_stage_map: list[dict[str, Any]],
@@ -87,6 +104,21 @@ def claim_implementation_stage_run(
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc
 
+    design_prep_decision = _resolve_stage_design_prep(
+        Path(inp.approved_plan_path), selected
+    )
+    if design_prep_decision.outcome == "wait_for_input":
+        requests = ", ".join(design_prep_decision.request_paths) or "no request path"
+        raise ImplementationStageError(
+            f"stage {selected} waits for design input: "
+            f"{design_prep_decision.reason}; {requests}"
+        )
+    if design_prep_decision.outcome == "replan":
+        raise ImplementationStageError(
+            f"stage {selected} requires implementation-planning rerun: "
+            f"{design_prep_decision.reason}"
+        )
+
     concurrent_stages = snapshot.concurrent_stage_numbers(
         selected_stage=selected,
     )
@@ -101,6 +133,7 @@ def claim_implementation_stage_run(
             worktree_status=executor_worktree_status,
             worktree_note="",
             started_head_commit=head,
+            design_prep_decision=design_prep_decision,
             concurrent_stages=concurrent_stages,
         )
         _record_stage_run_claim_started(task_key, plan_run_root, claim)
@@ -174,6 +207,7 @@ def claim_implementation_stage_run(
         worktree_status=prov.status,
         worktree_note=prov.note,
         started_head_commit=prov.base_ref,
+        design_prep_decision=design_prep_decision,
         concurrent_stages=concurrent_stages,
     )
     _record_stage_run_claim_started(task_key, plan_run_root, claim)
@@ -216,6 +250,7 @@ def publish_stage_run_claim(
         "Do NOT recompute from `consumers.jsonl`; the runtime already selected "
         "and reserved this stage."
     )
+    ctx["DESIGN_PREP_CONTEXT"] = claim.design_prep_decision.as_prompt_markdown()
     inp.stage = csv
     print(f"selected stages: {csv}", file=sys.stdout)