mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/kernel/base.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+from typing_extensions import TypeAliasType
+
+from mednotes.kernel.errors import ValidationError
+
+JsonValue = TypeAliasType(
+    "JsonValue",
+    str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"],
+)
+_StrictJsonObject = dict[str, JsonValue]
+_StrictJsonArray = list[JsonValue]
+
+JsonObjectAdapter = TypeAdapter(_StrictJsonObject)
+JsonArrayAdapter = TypeAdapter(_StrictJsonArray)
+
+
+def _validated_json_object(value: Any) -> dict[str, Any]:
+    return JsonObjectAdapter.validate_python(value)
+
+
+def _validated_json_array(value: Any) -> list[Any]:
+    return JsonArrayAdapter.validate_python(value)
+
+
+JsonObject = Annotated[dict[str, Any], AfterValidator(_validated_json_object)]
+JsonArray = Annotated[list[Any], AfterValidator(_validated_json_array)]
+
+
+class ContractModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+    def to_payload(self) -> dict[str, Any]:
+        payload = self.model_dump(mode="json", by_alias=True)
+        JsonObjectAdapter.validate_python(payload)
+        return payload
+
+
+def contract_error(exc: PydanticValidationError, *, prefix: str) -> ValidationError:
+    first = exc.errors()[0] if exc.errors() else {}
+    loc = ".".join(str(part) for part in first.get("loc", ())) or "$"
+    msg = str(first.get("msg") or str(exc))
+    return ValidationError(f"{prefix}: {loc}: {msg}")

package/.opencode/mednotes/src/mednotes/kernel/blockers.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pydantic import field_validator, model_validator
+from pydantic_core.core_schema import ValidationInfo
+
+from mednotes.kernel.base import ContractModel
+from mednotes.kernel.workflow import WorkflowDecisionKind
+
+
+def _non_empty(value: str, field_name: str) -> str:
+    cleaned = str(value or "").strip()
+    if not cleaned:
+        raise ValueError(f"{field_name} must be non-empty")
+    return cleaned
+
+
+class BlockerEntryModel(ContractModel):
+    code: str
+    owner_phase: str
+    default_decision: WorkflowDecisionKind
+    safe_to_continue_batch: bool
+    requires_human_packet: bool
+    public_label: str
+    public_explanation: str
+    developer_explanation: str
+    test_fixture: str
+
+    @field_validator("code", "owner_phase", "public_label", "public_explanation", "developer_explanation", "test_fixture")
+    @classmethod
+    def _required_text(cls, value: str, info: ValidationInfo) -> str:
+        return _non_empty(value, str(info.field_name))
+
+    @model_validator(mode="after")
+    def _validate_human_packet_policy(self) -> BlockerEntryModel:
+        if self.default_decision == WorkflowDecisionKind.ASK_HUMAN and not self.requires_human_packet:
+            raise ValueError("requires_human_packet must be true when default_decision is ask_human")
+        if self.default_decision != WorkflowDecisionKind.ASK_HUMAN and self.requires_human_packet:
+            raise ValueError("requires_human_packet is only valid for ask_human blockers")
+        return self

package/.opencode/mednotes/src/mednotes/kernel/effect_executor.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from mednotes.kernel.effects import WorkflowEffect, WorkflowEffectKind, WorkflowEffectResult
+
+
+class MissingWorkflowEffectAdapter(ValueError):
+    """Raised when an FSM emitted an effect that has no official adapter."""
+
+
+@dataclass(frozen=True)
+class WorkflowEffectExecutionContext:
+    dry_run: bool = False
+    environment: dict[str, str] = field(default_factory=dict)
+    artifacts_dir: str = ""
+
+
+class WorkflowEffectAdapter(Protocol):
+    def run(self, effect: WorkflowEffect, context: WorkflowEffectExecutionContext) -> WorkflowEffectResult:
+        """Materialize one already-authorized workflow effect."""
+
+
+@dataclass
+class WorkflowEffectExecutor:
+    adapters: dict[WorkflowEffectKind, WorkflowEffectAdapter]
+    context: WorkflowEffectExecutionContext = field(default_factory=WorkflowEffectExecutionContext)
+
+    def execute(
+        self,
+        effect: WorkflowEffect,
+        *,
+        context: WorkflowEffectExecutionContext | None = None,
+    ) -> WorkflowEffectResult:
+        if not isinstance(effect, WorkflowEffect):
+            raise TypeError("WorkflowEffectExecutor.execute requires WorkflowEffect")
+        adapter = self._adapter_for(effect.kind)
+        return adapter.run(effect, context or self.context)
+
+    def _adapter_for(self, kind: WorkflowEffectKind) -> WorkflowEffectAdapter:
+        match kind:
+            case (
+                WorkflowEffectKind.RUN_SUBWORKFLOW
+                | WorkflowEffectKind.CALL_SPECIALIST_MODEL
+                | WorkflowEffectKind.ASK_HUMAN
+                | WorkflowEffectKind.WAIT_EXTERNAL
+            ):
+                return self._required(kind)
+
+    def _required(self, kind: WorkflowEffectKind) -> WorkflowEffectAdapter:
+        adapter = self.adapters.get(kind)
+        if adapter is None:
+            raise MissingWorkflowEffectAdapter(f"no adapter registered for workflow effect kind: {kind.value}")
+        return adapter

package/.opencode/mednotes/src/mednotes/kernel/effect_intent.py

@@ -0,0 +1,69 @@
+"""Executable workflow effect intents without workflow-result dependencies.
+
+`WorkflowEffect` is the FSM-owned intent that adapters may execute later. It
+must stay independent from `workflow.py` so `state_machine.py` can type
+transition effects without creating a kernel import cycle.
+"""
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import Field, ValidationInfo, field_validator, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject
+
+
+class WorkflowEffectKind(StrEnum):
+    RUN_SUBWORKFLOW = "run_subworkflow"
+    CALL_SPECIALIST_MODEL = "call_specialist_model"
+    ASK_HUMAN = "ask_human"
+    WAIT_EXTERNAL = "wait_external"
+
+
+class WorkflowEffect(ContractModel):
+    """Executable work intent emitted from one stable workflow state."""
+
+    schema_id: str = Field(default="workflow-effect.v1", alias="schema")
+    workflow: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+    effect_id: str = Field(min_length=1)
+    origin_state: str = Field(min_length=1)
+    kind: WorkflowEffectKind
+    target: str = ""
+    payload: JsonObject = Field(default_factory=dict)
+    mutates_resources: bool = Field(default=False, strict=True)
+    no_resource_mutation: bool = Field(default=False, strict=True)
+    rollback_declared: bool = Field(default=False, strict=True)
+    requires_receipt: bool = Field(default=True, strict=True)
+    requires_attestation: bool = Field(default=False, strict=True)
+    model_policy: JsonObject = Field(default_factory=dict)
+    resume_action: str = ""
+    metadata: JsonObject = Field(default_factory=dict)
+
+    @field_validator("workflow", "run_id", "effect_id", "origin_state")
+    @classmethod
+    def _required_text(cls, value: str, info: ValidationInfo) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError(f"{info.field_name} must be non-empty")
+        return cleaned
+
+    @model_validator(mode="after")
+    def _validate_effect_contract(self) -> WorkflowEffect:
+        if (
+            self.kind
+            in {
+                WorkflowEffectKind.RUN_SUBWORKFLOW,
+                WorkflowEffectKind.CALL_SPECIALIST_MODEL,
+                WorkflowEffectKind.WAIT_EXTERNAL,
+            }
+            and not self.target.strip()
+        ):
+            raise ValueError(f"{self.kind} requires target")
+        if self.mutates_resources and self.no_resource_mutation:
+            raise ValueError("mutates_resources cannot be combined with no_resource_mutation")
+        if self.mutates_resources and not self.rollback_declared:
+            raise ValueError("mutates_resources requires rollback_declared")
+        if self.kind == WorkflowEffectKind.CALL_SPECIALIST_MODEL and not self.model_policy:
+            raise ValueError("call_specialist_model requires model_policy")
+        return self

package/.opencode/mednotes/src/mednotes/kernel/effects.py

@@ -0,0 +1,160 @@
+"""Framework workflow-effect contracts (pure FSM kernel, domain-agnostic).
+
+WorkflowEffect / WorkflowEffectResult are the generic effect intent + result of
+the FSM kernel. Concrete product payloads live in domain modules; adapters are
+the only layer allowed to materialize those effects in the outside world.
+"""
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import Field, SerializeAsAny, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.effect_intent import WorkflowEffect, WorkflowEffectKind
+from mednotes.kernel.progress import WorkflowProgressEvent
+from mednotes.kernel.workflow import HumanDecisionPacket
+
+__all__ = [
+    "WorkflowEffect",
+    "WorkflowEffectKind",
+    "WorkflowEffectOutcome",
+    "WorkflowEffectResult",
+    "WorkflowEffectStatus",
+    "workflow_effect_blocked_outcome",
+    "workflow_effect_completed_outcome",
+    "workflow_effect_failed_outcome",
+    "workflow_effect_skipped_outcome",
+    "workflow_effect_waiting_agent_outcome",
+    "workflow_effect_waiting_external_outcome",
+    "workflow_effect_waiting_human_outcome",
+    "workflow_effect_warning_outcome",
+]
+
+
+class WorkflowEffectStatus(StrEnum):
+    COMPLETED = "completed"
+    COMPLETED_WITH_WARNINGS = "completed_with_warnings"
+    WAITING_AGENT = "waiting_agent"
+    WAITING_EXTERNAL = "waiting_external"
+    WAITING_HUMAN = "waiting_human"
+    BLOCKED = "blocked"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class WorkflowEffectOutcome(ContractModel):
+    """Generic outcome discriminator for framework-level roundtrips.
+
+    Domain adapters should return stricter outcome models at their own
+    boundary. The kernel only requires a stable `code` field so result envelopes
+    can be serialized without knowing product-specific outcome matrices.
+    """
+
+    code: str = Field(min_length=1)
+    reason_code: str = ""
+
+
+def workflow_effect_completed_outcome() -> WorkflowEffectOutcome:
+    """Factory for framework-only tests and adapters without domain policy."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.completed")
+
+
+def workflow_effect_warning_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level warning outcomes."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.completed_with_warnings", reason_code=reason_code)
+
+
+def workflow_effect_waiting_external_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level resumable external waits."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.waiting_external", reason_code=reason_code)
+
+
+def workflow_effect_waiting_agent_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level executable agent work."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.waiting_agent", reason_code=reason_code)
+
+
+def workflow_effect_waiting_human_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level human-decision waits."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.waiting_human", reason_code=reason_code)
+
+
+def workflow_effect_blocked_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level blocked outcomes."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.blocked", reason_code=reason_code)
+
+
+def workflow_effect_failed_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for framework-level failed outcomes."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.failed", reason_code=reason_code)
+
+
+def workflow_effect_skipped_outcome(*, reason_code: str = "") -> WorkflowEffectOutcome:
+    """Factory for intentionally skipped effects."""
+
+    return WorkflowEffectOutcome(code="workflow_effect.skipped", reason_code=reason_code)
+
+
+class WorkflowEffectResult(ContractModel):
+    """Typed result returned by the adapter that materialized one effect."""
+
+    schema_id: str = Field(default="workflow-effect-result.v1", alias="schema")
+    effect: WorkflowEffect
+    status: WorkflowEffectStatus
+    # Effect outcomes are polymorphic by design: adapters may return a stricter
+    # domain model while the kernel only requires the generic code contract.
+    outcome: SerializeAsAny[WorkflowEffectOutcome | ContractModel]
+    public_summary: str = Field(min_length=1)
+    developer_summary: str = Field(min_length=1)
+    payload: JsonObject = Field(default_factory=dict)
+    receipt: JsonObject | None = None
+    attestation: JsonObject | None = None
+    human_decision_packet: HumanDecisionPacket | None = None
+    error_context: JsonObject = Field(default_factory=dict)
+    progress_events: list[WorkflowProgressEvent] = Field(default_factory=list)
+    next_action: str = ""
+    resume_action: str = ""
+
+    @model_validator(mode="after")
+    def _validate_result_contract(self) -> WorkflowEffectResult:
+        if (
+            self.status
+            in {
+                WorkflowEffectStatus.BLOCKED,
+                WorkflowEffectStatus.FAILED,
+                WorkflowEffectStatus.COMPLETED_WITH_WARNINGS,
+            }
+            and not self.next_action.strip()
+        ):
+            raise ValueError(f"{self.status} requires next_action")
+        if self.status == WorkflowEffectStatus.WAITING_EXTERNAL:
+            if not self.resume_action.strip():
+                raise ValueError("waiting_external effect result requires resume_action")
+            if not self.next_action.strip():
+                object.__setattr__(self, "next_action", self.resume_action)
+        if self.status == WorkflowEffectStatus.WAITING_HUMAN and self.human_decision_packet is None:
+            raise ValueError("waiting_human effect result requires human_decision_packet")
+        outcome_code = getattr(self.outcome, "code", "")
+        if not isinstance(outcome_code, str) or not outcome_code.strip():
+            raise ValueError("effect result outcome requires code")
+        if (
+            self.status in {WorkflowEffectStatus.COMPLETED, WorkflowEffectStatus.COMPLETED_WITH_WARNINGS}
+            and self.effect.requires_receipt
+            and self.receipt is None
+        ):
+            raise ValueError("completed effect result requires receipt")
+        if (
+            self.status in {WorkflowEffectStatus.COMPLETED, WorkflowEffectStatus.COMPLETED_WITH_WARNINGS}
+            and self.effect.requires_attestation
+            and self.attestation is None
+        ):
+            raise ValueError("effect result requires attestation")
+        return self

package/.opencode/mednotes/src/mednotes/kernel/errors.py

@@ -0,0 +1,38 @@
+"""Framework process-exit codes and the typed-error hierarchy.
+
+Domain-agnostic: plain exit codes plus a base exception that carries one. Lives
+in the framework so the FSM kernel can raise/type its errors without importing
+domain facades. Layering rule: framework <- domain <- adapters
+(tools/audit/import_layering.py).
+"""
+from __future__ import annotations
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_VALIDATION = 3
+EXIT_MISSING = 4
+EXIT_IO = 5
+
+
+class MedOpsError(Exception):
+    """Base exception carrying a process exit code."""
+
+    exit_code = EXIT_IO
+
+
+class ValidationError(MedOpsError):
+    exit_code = EXIT_VALIDATION
+
+
+class MissingPathError(MedOpsError):
+    exit_code = EXIT_MISSING
+
+
+class CollisionError(MedOpsError):
+    exit_code = EXIT_VALIDATION
+
+
+class FileWriteError(MedOpsError):
+    """Filesystem write failed after local retry/recovery attempts."""
+
+    exit_code = EXIT_IO

package/.opencode/mednotes/src/mednotes/kernel/fsm_event.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from pydantic import Field
+
+from mednotes.kernel.base import ContractModel, JsonObject
+
+
+class WorkflowEvent(ContractModel):
+    """Base fact consumed by workflow statecharts; domains add typed fields."""
+
+    workflow: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    current_state: str = Field(min_length=1)
+    # Redacted replay/debug material only; FSM decisions must use typed fields.
+    audit_evidence: JsonObject = Field(default_factory=dict)
+
+
+class WorkflowEventLike(Protocol):
+    """Structural event surface required by the StateChart kernel wrapper."""
+
+    @property
+    def workflow(self) -> str: ...
+
+    @property
+    def run_id(self) -> str: ...
+
+    @property
+    def name(self) -> str:
+        ...
+
+    @property
+    def current_state(self) -> str: ...

package/.opencode/mednotes/src/mednotes/kernel/fsm_model.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+from pydantic import Field
+
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.effects import WorkflowEffect
+from mednotes.kernel.fsm_event import WorkflowEventLike
+from mednotes.kernel.fsm_transition_result import WorkflowTransitionResult
+
+
+class WorkflowModel(ContractModel):
+    """Persisted workflow state used directly as python-statemachine carrier."""
+
+    STATECHART_STATE_FIELD: ClassVar[str] = "state"
+
+    workflow: str = Field(min_length=1)
+    run_id: str = Field(min_length=1)
+    # Public persisted state is the single mutable StateChart carrier.
+    state: str = Field(min_length=1)
+    # Events are typed before sending; the persisted log stores JSON evidence
+    # so WorkflowModel can rehydrate without importing every domain union.
+    event_log: list[JsonObject] = Field(default_factory=list)
+    transition_log: list[WorkflowTransitionResult] = Field(default_factory=list)
+    last_transition: WorkflowTransitionResult | None = None
+    pending_effects: list[WorkflowEffect] = Field(default_factory=list)
+
+    @classmethod
+    def start(cls, *, workflow: str, run_id: str, initial_state: str) -> WorkflowModel:
+        return cls(workflow=workflow, run_id=run_id, state=initial_state)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Allow python-statemachine's transient empty carrier during microsteps."""
+
+        if name == self.STATECHART_STATE_FIELD and value is None:
+            object.__setattr__(self, name, value)
+            return
+        super().__setattr__(name, value)
+
+    def record_event(self, event: WorkflowEventLike) -> None:
+        if not isinstance(event, ContractModel):
+            raise TypeError("workflow events must be Pydantic contract models")
+        if event.workflow != self.workflow or event.run_id != self.run_id:
+            raise ValueError("event belongs to a different workflow run")
+        self.event_log.append(event.to_payload())
+
+    def record_transition(self, transition: WorkflowTransitionResult) -> None:
+        if transition.workflow != self.workflow or transition.run_id != self.run_id:
+            raise ValueError("transition belongs to a different workflow run")
+        if self.state != transition.to_state:
+            raise ValueError("machine state does not match transition target")
+        object.__setattr__(self, "last_transition", transition)
+        object.__setattr__(self, "pending_effects", list(transition.effects))
+        self.transition_log.append(transition)

package/.opencode/mednotes/src/mednotes/kernel/fsm_transition_result.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import Field, StrictStr, ValidationInfo, field_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject
+from mednotes.kernel.effects import WorkflowEffect, WorkflowEffectKind
+from mednotes.kernel.workflow import HumanDecisionPacket, WorkflowDecision
+
+
+class WorkflowTransitionResult(ContractModel):
+    """Typed result returned by a real StateChart transition callback."""
+
+    workflow: StrictStr = Field(min_length=1)
+    run_id: StrictStr = Field(min_length=1)
+    from_state: StrictStr = Field(min_length=1)
+    to_state: StrictStr = Field(min_length=1)
+    trigger: StrictStr = Field(min_length=1)
+    reason_code: StrictStr = Field(min_length=1)
+    effects: list[WorkflowEffect] = Field(default_factory=list)
+    decision: WorkflowDecision | None = None
+    human_decision_packet: HumanDecisionPacket | None = None
+    resume_action: str = ""
+    # Redacted/debug-only evidence; categories and effects are validated from typed fields.
+    audit_evidence: JsonObject = Field(default_factory=dict)
+
+    @field_validator("workflow", "run_id", "from_state", "to_state", "trigger", "reason_code")
+    @classmethod
+    def _required_text(cls, value: str, info: ValidationInfo) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError(f"{info.field_name} must be non-empty")
+        return cleaned
+
+
+def validate_transition_result(
+    transition: WorkflowTransitionResult,
+    *,
+    category_for_state: Callable[[str], object],
+) -> WorkflowTransitionResult:
+    """Validate category-dependent contracts without importing domain state maps."""
+
+    for effect in transition.effects:
+        if effect.origin_state != transition.to_state:
+            raise ValueError("effect origin_state must match transition target")
+
+    category = _category_value(category_for_state(transition.to_state))
+    match category:
+        case "waiting_agent":
+            if not transition.effects:
+                raise ValueError("waiting_agent transition requires at least one workflow effect")
+        case "waiting_human":
+            if transition.human_decision_packet is None:
+                raise ValueError("waiting_human transition requires human_decision_packet")
+            if not _has_effect_kind(transition, WorkflowEffectKind.ASK_HUMAN):
+                raise ValueError("waiting_human transition requires ask_human effect")
+        case "waiting_external":
+            if not transition.resume_action.strip():
+                raise ValueError("waiting_external transition requires resume_action")
+            if not _has_effect_kind(transition, WorkflowEffectKind.WAIT_EXTERNAL):
+                raise ValueError("waiting_external transition requires wait_external effect")
+        case "blocked" | "failed":
+            if transition.decision is None:
+                raise ValueError(f"{category} transition requires decision")
+    return transition
+
+
+def _category_value(category: object) -> str:
+    value = getattr(category, "value", category)
+    return str(value)
+
+
+def _has_effect_kind(transition: WorkflowTransitionResult, kind: WorkflowEffectKind) -> bool:
+    return any(effect.kind == kind for effect in transition.effects)