mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/publish.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from mednotes.kernel.base import ContractModel
+from mednotes.kernel.workflow import HumanDecisionPacket
+
+
+class PublishManifestNote(ContractModel):
+    taxonomy: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    content_path: str = Field(min_length=1)
+    safe_filename: str | None = None
+
+
+class PublishManifestBatch(ContractModel):
+    raw_file: str = Field(min_length=1)
+    coverage_path: str | None = None
+    note_plan_path: str | None = None
+    raw_files: list[str] = Field(default_factory=list)
+    notes: list[PublishManifestNote] = Field(min_length=1)
+    batch_id: str | None = None
+    run_id: str | None = None
+    note_plan_hash: str | None = None
+    coverage_hash: str | None = None
+    source_artifact_hash: str | None = None
+    human_decision_required: bool | None = None
+    human_decision_packet: HumanDecisionPacket | None = None
+    human_decision_packets: list[HumanDecisionPacket] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def pending_human_decision_is_explicit(self) -> PublishManifestBatch:
+        if self.human_decision_required is True:
+            return self
+        if self.human_decision_packet is not None and self.human_decision_packet.status == "pending":
+            object.__setattr__(self, "human_decision_required", True)
+        if any(packet.status == "pending" for packet in self.human_decision_packets):
+            object.__setattr__(self, "human_decision_required", True)
+        return self
+
+
+class PublishManifest(ContractModel):
+    schema_id: str | None = Field(default=None, alias="schema")
+    human_decision_required: bool | None = None
+    human_decision_packet: HumanDecisionPacket | None = None
+    human_decision_packets: list[HumanDecisionPacket] = Field(default_factory=list)
+    batches: list[PublishManifestBatch] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def manifest_must_have_notes(self) -> PublishManifest:
+        if not self.batches:
+            raise ValueError("publish manifest requires canonical batches[]")
+        if self.human_decision_packet is not None and self.human_decision_packet.status == "pending":
+            object.__setattr__(self, "human_decision_required", True)
+        if any(packet.status == "pending" for packet in self.human_decision_packets):
+            object.__setattr__(self, "human_decision_required", True)
+        return self
+
+    def require_coverage(self) -> None:
+        missing = [batch.raw_file for batch in self.batches if not batch.coverage_path]
+        if missing:
+            raise ValueError(
+                "publish manifest batches require coverage_path when require_coverage=True: "
+                + ", ".join(missing)
+            )
+
+    def pending_human_decision(self) -> bool:
+        if self.human_decision_required is True:
+            return True
+        if self.human_decision_packet is not None and self.human_decision_packet.status == "pending":
+            return True
+        if any(packet.status == "pending" for packet in self.human_decision_packets):
+            return True
+        return any(batch.human_decision_required is True for batch in self.batches)
+
+
+class PublishReceiptItem(ContractModel):
+    path: str = Field(min_length=1)
+    status: Literal["published", "skipped", "blocked"]
+    reason: str | None = None
+
+
+class PublishErrorContext(ContractModel):
+    root_cause: str = Field(min_length=1)
+    affected_artifact: str = Field(min_length=1)
+    error_summary: str = Field(min_length=1)
+    suggested_fix: str = Field(min_length=1)
+    next_action: str = Field(min_length=1)
+    retry_scope: str = Field(min_length=1)
+    phase: str | None = None
+    blocked_reason: str | None = None
+    details: dict[str, object] | None = None
+
+
+class PublishReceipt(ContractModel):
+    schema_id: Literal["medical-notes-workbench.publish-receipt.v1"] = Field(alias="schema")
+    status: Literal["ready_to_publish", "published", "completed_with_link_blockers", "blocked"]
+    batch_id: str = Field(min_length=1)
+    published_count: int = Field(ge=0)
+    skipped_count: int = Field(ge=0)
+    items: list[PublishReceiptItem]
+    next_action: str = ""
+    error_context: PublishErrorContext | None = None
+
+    @model_validator(mode="after")
+    def blocked_requires_error_context(self) -> PublishReceipt:
+        if self.status == "blocked" and self.error_context is None:
+            raise ValueError("blocked publish receipts require error_context")
+        return self

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/raw_coverage.py

@@ -0,0 +1,217 @@
+"""Typed raw-coverage contracts for process-chats publish boundaries.
+
+The raw coverage file is authored outside the publish adapter, so JSON is
+allowed at the file boundary only. Once loaded, coverage decisions and publish
+counts must read these Pydantic models instead of loose dictionaries.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import ConfigDict, Field, StrictBool, StrictStr, model_validator
+
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+
+RAW_COVERAGE_SCHEMA = "medical-notes-workbench.raw-coverage.v1"
+CoverageAction = Literal["planned_meaning", "not_a_note"]
+RawCoverageSourceStatus = Literal["covered", "already_covered", "not_relevant"]
+
+
+class RawCoverageItem(ContractModel):
+    """One exhaustive coverage decision for material in a raw chat."""
+
+    id: StrictStr = Field(min_length=1)
+    action: CoverageAction
+    title: StrictStr | None = None
+    staged_title: StrictStr | None = None
+    meaning_claim: JsonObject | None = None
+    reason_code: StrictStr | None = None
+    reason: StrictStr | None = None
+    status: StrictStr | None = None
+    detail: StrictStr | None = None
+    coverage: JsonObject | None = None
+
+    @model_validator(mode="after")
+    def validate_coverage_payload(self) -> RawCoverageItem:
+        if self.action == "planned_meaning":
+            if not (self.title or self.staged_title):
+                raise ValueError("planned_meaning coverage items require title or staged_title")
+        elif self.action == "not_a_note" and not self.reason:
+            raise ValueError("not_a_note coverage items require reason")
+        return self
+
+    @property
+    def planned_title(self) -> str:
+        return (self.staged_title or self.title or "").strip()
+
+
+class RawCoverageSource(ContractModel):
+    """Per-raw provenance statement for multi-source process-chats coverage."""
+
+    raw_file: StrictStr = Field(min_length=1)
+    status: RawCoverageSourceStatus
+    target_title: StrictStr = ""
+    target_section: StrictStr = ""
+    new_information_summary: StrictStr = ""
+    reference_added: StrictStr = ""
+    reason: StrictStr = ""
+    existing_title: StrictStr = ""
+
+    @model_validator(mode="after")
+    def validate_status_payload(self) -> RawCoverageSource:
+        if self.status == "covered":
+            missing = [
+                field
+                for field in (
+                    "target_title",
+                    "target_section",
+                    "new_information_summary",
+                    "reference_added",
+                )
+                if not getattr(self, field).strip()
+            ]
+            if missing:
+                raise ValueError(f"covered source requires {', '.join(missing)}")
+        elif self.status in {"already_covered", "not_relevant"} and not self.reason.strip():
+            raise ValueError(f"{self.status} source requires reason")
+        return self
+
+    def compact_payload(self) -> JsonObject:
+        payload = self.model_dump(mode="json", exclude_defaults=True)
+        return JsonObjectAdapter.validate_python(payload)
+
+
+class RawCoverage(ContractModel):
+    """Canonical raw-coverage inventory consumed by publish and validation."""
+
+    schema_id: Literal["medical-notes-workbench.raw-coverage.v1"] = Field(alias="schema")
+    raw_file: StrictStr = Field(min_length=1)
+    exhaustive: Literal[True]
+    items: list[RawCoverageItem] = Field(min_length=1)
+    raw_files: list[StrictStr] = Field(default_factory=list)
+    sources: list[RawCoverageSource] = Field(default_factory=list)
+    batch_id: StrictStr | None = None
+    run_id: StrictStr | None = None
+    note_plan_hash: StrictStr | None = None
+    coverage_hash: StrictStr | None = None
+    source_artifact_hash: StrictStr | None = None
+
+
+class RawCoverageSummary(ContractModel):
+    """Typed summary projected from a validated raw coverage inventory."""
+
+    schema_id: Literal["medical-notes-workbench.raw-coverage.v1"] = Field(
+        default=RAW_COVERAGE_SCHEMA,
+        alias="schema",
+    )
+    status: Literal["", "valid"] = ""
+    coverage_path: StrictStr = ""
+    coverage_hash: StrictStr = ""
+    raw_file: StrictStr = ""
+    raw_files: list[StrictStr] = Field(default_factory=list)
+    multi_source: StrictBool = False
+    source_count: int = Field(default=0, ge=0, strict=True)
+    exhaustive: StrictBool = False
+    item_count: int = Field(default=0, ge=0, strict=True)
+    planned_meaning_count: int = Field(default=0, ge=0, strict=True)
+    not_a_note_count: int = Field(default=0, ge=0, strict=True)
+    staged_note_count: int = Field(default=0, ge=0, strict=True)
+    raw_file_count: int = Field(default=0, ge=0, strict=True)
+    covered_count: int = Field(default=0, ge=0, strict=True)
+    sources: list[RawCoverageSource] = Field(default_factory=list)
+    source_status_counts: dict[str, int] = Field(default_factory=dict)
+    coverage_hashes: list[StrictStr] = Field(default_factory=list)
+    batch_id: StrictStr = ""
+    run_id: StrictStr = ""
+    note_plan_hash: StrictStr = ""
+    source_artifact_hash: StrictStr = ""
+    note_plan_source_count: int = Field(default=0, ge=0, strict=True)
+    note_plan_hashes: dict[str, str] = Field(default_factory=dict)
+    note_plan_item_count: int = Field(default=0, ge=0, strict=True)
+    note_plan_planned_meaning_count: int = Field(default=0, ge=0, strict=True)
+    note_plan_attach_count: int = Field(default=0, ge=0, strict=True)
+    note_plan_not_a_note_count: int = Field(default=0, ge=0, strict=True)
+    note_plan_needs_context_count: int = Field(default=0, ge=0, strict=True)
+
+    def to_payload(self) -> JsonObject:
+        payload = self.model_dump(mode="json", by_alias=True)
+        if self.sources:
+            payload["sources"] = [source.compact_payload() for source in self.sources]
+        else:
+            payload.pop("sources", None)
+        payload = {key: value for key, value in payload.items() if value not in ("", [], {})}
+        for key in (
+            "multi_source",
+            "source_count",
+            "exhaustive",
+            "item_count",
+            "planned_meaning_count",
+            "not_a_note_count",
+            "staged_note_count",
+            "raw_file_count",
+            "covered_count",
+        ):
+            payload[key] = getattr(self, key)
+        return JsonObjectAdapter.validate_python(payload)
+
+
+class RawCoveragePlanBatch(ContractModel):
+    """Typed lens over publish's planned-batch projection."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, validate_assignment=True)
+
+    raw_file: StrictStr = ""
+    raw_files: list[StrictStr] = Field(default_factory=list)
+    coverage: RawCoverageSummary | None = None
+
+
+def coverage_summary_from_batches(plan: Sequence[RawCoveragePlanBatch]) -> RawCoverageSummary:
+    """Aggregate validated planned batches without reading raw dictionaries."""
+
+    raw_files: list[str] = []
+    seen_raw_files: set[str] = set()
+    source_status_counts: Counter[str] = Counter()
+    coverage_hashes: list[str] = []
+    item_count = 0
+    planned_meaning_count = 0
+    not_a_note_count = 0
+    staged_note_count = 0
+    source_count = 0
+
+    for batch in plan:
+        batch_raw_files = batch.raw_files or ([batch.raw_file] if batch.raw_file else [])
+        for raw_file in batch_raw_files:
+            raw_file_text = raw_file.strip()
+            if raw_file_text and raw_file_text not in seen_raw_files:
+                seen_raw_files.add(raw_file_text)
+                raw_files.append(raw_file_text)
+        if batch.coverage is None:
+            continue
+        coverage = batch.coverage
+        if coverage.coverage_hash:
+            coverage_hashes.append(coverage.coverage_hash)
+        item_count += coverage.item_count
+        planned_meaning_count += coverage.planned_meaning_count
+        not_a_note_count += coverage.not_a_note_count
+        staged_note_count += coverage.staged_note_count
+        source_count += coverage.source_count
+        source_status_counts.update(coverage.source_status_counts)
+
+    return RawCoverageSummary(
+        status="valid" if plan else "",
+        raw_files=raw_files,
+        multi_source=len(raw_files) > 1,
+        source_count=source_count or len(raw_files),
+        exhaustive=bool(plan),
+        item_count=item_count,
+        planned_meaning_count=planned_meaning_count,
+        not_a_note_count=not_a_note_count,
+        staged_note_count=staged_note_count,
+        raw_file_count=len(raw_files),
+        covered_count=len(raw_files),
+        source_status_counts=dict(source_status_counts),
+        coverage_hash=coverage_hashes[0] if len(coverage_hashes) == 1 else "",
+        coverage_hashes=coverage_hashes,
+    )

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/related_notes.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import ConfigDict, Field, field_validator
+
+from mednotes.kernel.base import ContractModel
+
+RelatedNotesEmbeddingProfileId = Literal["clean_v1", "raw_v1", "legacy_v0"]
+RelatedNotesRepresentationHashBasis = Literal["profile_cleaned_markdown", "raw_markdown", "legacy_hybrid_markdown"]
+
+_SHA256_PATTERN = r"^sha256:[0-9a-f]{64}$"
+
+
+def _validate_relative_posix_path(value: str) -> str:
+    text = value.strip()
+    if (
+        not text or text.startswith(("/", "../")) or "\\" in text or "//" in text or any(part in {"", ".", ".."} for part in text.split("/"))
+    ):
+        raise ValueError("path must be a wiki-relative POSIX path")
+    return text
+
+
+class RelatedNotesExportPlugin(ContractModel):
+    name: Literal["related-notes-obsidian"]
+    version: str = Field(min_length=1)
+
+
+class RelatedNotesExportModel(ContractModel):
+    provider: str | None = None
+    embedding_model: str = Field(min_length=1)
+    dimension: int | None = Field(default=None, gt=0)
+    embedding_profile_id: RelatedNotesEmbeddingProfileId
+    embedding_profile_version: Literal[1]
+    representation_hash_basis: RelatedNotesRepresentationHashBasis
+
+
+class RelatedNotesExportNote(ContractModel):
+    path: str = Field(min_length=1)
+    title: str = Field(min_length=1)
+    content_hash: str = Field(pattern=_SHA256_PATTERN)
+
+    @field_validator("path")
+    @classmethod
+    def path_must_be_relative_posix(cls, value: str) -> str:
+        return _validate_relative_posix_path(value)
+
+
+class RelatedNotesExportEdge(ContractModel):
+    source_path: str = Field(min_length=1)
+    target_path: str = Field(min_length=1)
+    score: float = Field(ge=0.0, le=1.0)
+    rank: int = Field(ge=1)
+    source: Literal["related-notes-obsidian"] = "related-notes-obsidian"
+
+    @field_validator("source_path", "target_path")
+    @classmethod
+    def path_must_be_relative_posix(cls, value: str) -> str:
+        return _validate_relative_posix_path(value)
+
+
+class RelatedNotesExport(ContractModel):
+    schema_: Literal["medical-notes-workbench.related-notes-export.v1"] = Field(
+        alias="schema",
+        serialization_alias="schema",
+    )
+    generated_at: datetime
+    vault_root: str = Field(min_length=1)
+    plugin: RelatedNotesExportPlugin
+    model_info: RelatedNotesExportModel = Field(alias="model", serialization_alias="model")
+    score_scale: Literal["0_to_1"]
+    notes: list[RelatedNotesExportNote]
+    edges: list[RelatedNotesExportEdge]
+
+    @field_validator("generated_at")
+    @classmethod
+    def generated_at_must_be_timezone_aware(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("generated_at must include timezone")
+        return value
+
+
+class RelatedNotesHashMigrationModel(ContractModel):
+    """Minimal model slice needed to decide legacy hash migration."""
+
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    embedding_profile_id: RelatedNotesEmbeddingProfileId
+
+
+class RelatedNotesHashMigrationExport(ContractModel):
+    """Typed migration boundary for historical plugin exports.
+
+    Older plugin exports may lack metadata required by the full public export
+    contract. Hash migration only needs the schema, profile and per-note hashes,
+    so this closed decision lens avoids raw dict reads without rejecting valid
+    legacy migration inputs.
+    """
+
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    schema_: Literal["medical-notes-workbench.related-notes-export.v1"] = Field(
+        alias="schema",
+        serialization_alias="schema",
+    )
+    model_info: RelatedNotesHashMigrationModel = Field(alias="model", serialization_alias="model")
+    notes: list[RelatedNotesExportNote]
+
+
+class RelatedNotesHeadlessExportSummary(ContractModel):
+    schema_: str | None = Field(default=None, alias="schema", serialization_alias="schema")
+    status: str = ""
+    phase: str = ""
+    blocked_reason: str = ""
+    detail: str = ""
+    export_path: str = ""
+    index_path: str = ""
+    wiki_dir: str = ""
+    note_count: int = Field(default=0, ge=0)
+    edge_count: int = Field(default=0, ge=0)
+    record_count: int = Field(default=0, ge=0)
+    total_note_count: int = Field(default=0, ge=0)
+    fresh_record_count: int = Field(default=0, ge=0)
+    stale_record_count: int = Field(default=0, ge=0)
+    remaining_count: int = Field(default=0, ge=0)
+    partial_record_count: int = Field(default=0, ge=0)
+    embedded_count: int = Field(default=0, ge=0)
+    reused_count: int = Field(default=0, ge=0)
+    embedding_model: str = ""
+    embedding_profile_id: str = ""
+    embedding_request_delay_ms: int = Field(default=0, ge=0)
+    embedding_transient_retry_count: int = Field(default=0, ge=0)
+    related_notes_limit: int = Field(default=0, ge=0)
+    next_retry_after_seconds: int | None = Field(default=None, ge=0)
+    resume_supported: bool = False

package/.opencode/mednotes/src/mednotes/domains/wiki/contracts/related_notes_headless.py

@@ -0,0 +1,153 @@
+"""Typed boundaries for the headless Related Notes adapter.
+
+The headless adapter reads Obsidian plugin JSON, a vector index and Gemini HTTP
+responses. Those payloads are external data; workflow decisions must use these
+models before checking status, currentness, vectors, counts or retry details.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field, StrictFloat, StrictInt, StrictStr
+
+from mednotes.kernel.base import ContractModel, JsonObject
+
+RELATED_NOTES_HASH_MIGRATION_CACHE_SCHEMA = "medical-notes-workbench.related-notes-hash-migration-cache.v1"
+
+
+class RelatedNotesHashMigrationCache(ContractModel):
+    """Persisted cache entry for the clean_v1 hash migration shortcut."""
+
+    schema_: Literal["medical-notes-workbench.related-notes-hash-migration-cache.v1"] = Field(
+        alias="schema",
+        serialization_alias="schema",
+    )
+    identity: JsonObject
+    status: Literal[
+        "no_legacy_clean_v1_hashes",
+        "migrated_clean_v1_hashes",
+        "legacy_clean_v1_vectors_missing",
+    ]
+    migrated_note_count: int = Field(default=0, ge=0)
+    skipped_note_count: int = Field(default=0, ge=0)
+
+
+class RelatedNotesHeadlessSettings(ContractModel):
+    """Strict subset of plugin settings that drives embedding/relation policy."""
+
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    gemini_api_key: str = Field(default="", alias="geminiApiKey", serialization_alias="geminiApiKey")
+    default_embedding_profile: str = Field(
+        default="",
+        alias="defaultEmbeddingProfile",
+        serialization_alias="defaultEmbeddingProfile",
+    )
+    related_notes_limit: int | None = Field(
+        default=None,
+        alias="relatedNotesLimit",
+        serialization_alias="relatedNotesLimit",
+    )
+    embedding_request_delay_ms: int | float | None = Field(
+        default=None,
+        alias="embeddingRequestDelayMs",
+        serialization_alias="embeddingRequestDelayMs",
+    )
+
+
+class RelatedNotesVectorRecord(ContractModel):
+    """One plugin vector-index record after validation."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    path: StrictStr = ""
+    title: StrictStr = ""
+    folder: StrictStr = ""
+    preview: StrictStr = ""
+    raw_content_hash: StrictStr = Field(default="", alias="rawContentHash", serialization_alias="rawContentHash")
+    representation_hash: StrictStr = Field(
+        default="",
+        alias="representationHash",
+        serialization_alias="representationHash",
+    )
+    content_hash: StrictStr = Field(default="", alias="contentHash", serialization_alias="contentHash")
+    mtime: StrictInt = 0
+    embedding_model: StrictStr = Field(default="", alias="embeddingModel", serialization_alias="embeddingModel")
+    embedding_profile: StrictStr = Field(default="", alias="embeddingProfile", serialization_alias="embeddingProfile")
+    embedding_profile_version: StrictInt = Field(
+        default=0,
+        alias="embeddingProfileVersion",
+        serialization_alias="embeddingProfileVersion",
+    )
+    vector: list[StrictFloat] = Field(default_factory=list, min_length=1)
+    updated_at: StrictInt = Field(default=0, alias="updatedAt", serialization_alias="updatedAt")
+
+
+class RelatedNotesVectorProfile(ContractModel):
+    """A profile bucket from the plugin vector index."""
+
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    records: dict[str, RelatedNotesVectorRecord] = Field(default_factory=dict)
+
+
+class RelatedNotesVectorIndex(ContractModel):
+    """Validated vector index with typed records per profile."""
+
+    model_config = ConfigDict(extra="ignore", strict=True)
+
+    profiles: dict[str, RelatedNotesVectorProfile] = Field(default_factory=dict)
+
+    def records_for_profile(self, profile_id: str) -> dict[str, RelatedNotesVectorRecord]:
+        profile = self.profiles[profile_id] if profile_id in self.profiles else RelatedNotesVectorProfile()
+        return dict(profile.records)
+
+    def other_profiles_payload(self, profile_id: str) -> JsonObject:
+        return {
+            key: value.to_payload()
+            for key, value in self.profiles.items()
+            if key != profile_id
+        }
+
+
+class GeminiEmbedding(ContractModel):
+    """Gemini embedding vector payload."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    values: list[float]
+
+
+class GeminiEmbeddingResponse(ContractModel):
+    """Single Gemini embedding response."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    embedding: GeminiEmbedding
+
+
+class GeminiBatchEmbeddingResponse(ContractModel):
+    """Batch Gemini embedding response."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    embeddings: list[GeminiEmbedding]
+
+
+class GeminiError(ContractModel):
+    """Error object returned by Gemini HTTP APIs."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    code: int | str = ""
+    status: str = ""
+    message: str = ""
+
+
+class GeminiErrorResponse(ContractModel):
+    """Typed Gemini error wrapper used only for redacted diagnostics."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    error: GeminiError | None = None