mednotes-opencode 0.1.0

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/fix_wiki/fix_wiki_plan.py

@@ -0,0 +1,306 @@
+"""Master plan builder for the fix-wiki workflow."""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from pydantic import Field
+
+from mednotes.domains.wiki.batch_state import file_sha256
+from mednotes.domains.wiki.capabilities.notes.note_iter import iter_notes
+from mednotes.domains.wiki.flows.fix_wiki.fix_wiki_problem import FixWikiProblem
+from mednotes.kernel.base import ContractModel, JsonObject, JsonObjectAdapter
+
+FIX_WIKI_PLAN_SCHEMA = "medical-notes-workbench.fix-wiki-plan.v1"
+ORDERED_FIX_WIKI_PHASES = (
+    "preflight",
+    "inventory",
+    "vocabulary_bootstrap",
+    "vocabulary_map_diagnosis",
+    "style_yaml",
+    "provenance_backfill",
+    "hygiene",
+    "duplicates",
+    "taxonomy",
+    "linker",
+    "final_validation",
+)
+
+
+class FixWikiSnapshotFile(ContractModel):
+    """Stable note identity used to detect stale fix-wiki plans before apply."""
+
+    path: str
+    hash: str
+
+
+class FixWikiTaxonomyPlanItem(ContractModel):
+    """Projection of taxonomy plan rows; only `source` drives phase scope."""
+
+    action: str = ""
+    source: str = ""
+    destination: str = ""
+    reason: str = ""
+    blocked_reason: str = ""
+
+
+class FixWikiPhase(ContractModel):
+    """Single public phase row in the preview/apply plan."""
+
+    phase: str
+    status: str = "ready"
+    can_apply: bool = True
+    blocked_reason: str = ""
+    requires_decision: str = ""
+    requires_human: bool = False
+    affected_paths: list[str] = Field(default_factory=list)
+    planned_artifacts: list[str] = Field(default_factory=list)
+    rollback_strategy: str = ""
+
+
+class FixWikiPlan(ContractModel):
+    """Typed root plan; `plan_hash` is calculated from its serialized payload."""
+
+    schema_id: str = Field(default=FIX_WIKI_PLAN_SCHEMA, alias="schema")
+    run_id: str
+    wiki_dir: str
+    snapshot_hash: str
+    snapshot_files: list[FixWikiSnapshotFile] = Field(default_factory=list)
+    context_packet_hashes: JsonObject = Field(default_factory=dict)
+    git: JsonObject = Field(default_factory=dict)
+    vocabulary_map_hash: str = ""
+    phase_order: list[str]
+    plan_hash: str = ""
+    status: str
+    problems: list[FixWikiProblem] = Field(default_factory=list)
+    fix_wiki_problems: list[FixWikiProblem] = Field(default_factory=list)
+    deferred_work_items: list[JsonObject] = Field(default_factory=list)
+    phases: list[FixWikiPhase] = Field(default_factory=list)
+    blockers: list[FixWikiProblem] = Field(default_factory=list)
+    warnings: list[FixWikiProblem] = Field(default_factory=list)
+
+
+def _vocabulary_blocked_reason(status: str) -> str:
+    if status == "blocked_pending":
+        return "vocabulary_semantic_ingestion_pending"
+    if status == "blocked_human":
+        return "vocabulary_map_blocked"
+    return ""
+
+
+def _phase(
+    name: str,
+    *,
+    status: str = "ready",
+    can_apply: bool = True,
+    blocked_reason: str = "",
+    requires_decision: str = "",
+    requires_human: bool = False,
+    affected_paths: list[str] | None = None,
+    planned_artifacts: list[str] | None = None,
+    rollback_strategy: str = "",
+) -> FixWikiPhase:
+    return FixWikiPhase(
+        phase=name,
+        status=status,
+        can_apply=can_apply,
+        blocked_reason=blocked_reason,
+        requires_decision=requires_decision,
+        requires_human=requires_human,
+        affected_paths=affected_paths or [],
+        planned_artifacts=planned_artifacts or [],
+        rollback_strategy=rollback_strategy,
+    )
+
+
+def _hash_plan(payload: JsonObject) -> str:
+    stable = {key: value for key, value in payload.items() if key != "plan_hash"}
+    encoded = json.dumps(stable, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def collect_fix_wiki_snapshot_files(wiki_dir: Path) -> list[JsonObject]:
+    files: list[JsonObject] = []
+    for path in iter_notes(wiki_dir) if wiki_dir.exists() else []:
+        snapshot_file = FixWikiSnapshotFile(
+            path=path.relative_to(wiki_dir).as_posix(),
+            hash="sha256:" + file_sha256(path),
+        )
+        files.append(snapshot_file.to_payload())
+    return files
+
+
+def fix_wiki_snapshot_hash(wiki_dir: Path) -> str:
+    encoded = json.dumps(
+        collect_fix_wiki_snapshot_files(wiki_dir),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def _context_packet_hashes(context_packets: JsonObject | None) -> JsonObject:
+    hashes: JsonObject = {}
+    for key, value in sorted((context_packets or {}).items()):
+        path = Path(str(value))
+        if path.is_file():
+            hashes[key] = "sha256:" + file_sha256(path)
+    return JsonObjectAdapter.validate_python(hashes)
+
+
+def validate_fix_wiki_plan_snapshot(plan: object, wiki_dir: Path) -> JsonObject:
+    typed_plan = FixWikiPlan.model_validate(plan)
+    expected = typed_plan.snapshot_hash
+    actual = fix_wiki_snapshot_hash(wiki_dir)
+    if expected and expected != actual:
+        return JsonObjectAdapter.validate_python(
+            {
+                "status": "blocked",
+                "blocked_reason": "stale_fix_wiki_plan",
+                "expected_snapshot_hash": expected,
+                "actual_snapshot_hash": actual,
+                "next_action": "Rodar /mednotes:fix-wiki novamente para gerar um plano atualizado antes de aplicar.",
+            }
+        )
+    return JsonObjectAdapter.validate_python(
+        {
+            "status": "ready",
+            "blocked_reason": "",
+            "expected_snapshot_hash": expected,
+            "actual_snapshot_hash": actual,
+        }
+    )
+
+
+def _problem_items(problems: Sequence[object]) -> list[FixWikiProblem]:
+    return [FixWikiProblem.model_validate(problem) for problem in problems]
+
+
+def _taxonomy_items(items: Sequence[object]) -> list[FixWikiTaxonomyPlanItem]:
+    return [FixWikiTaxonomyPlanItem.model_validate(item) for item in items]
+
+
+def _json_object_list(items: Sequence[JsonObject] | None) -> list[JsonObject]:
+    return [JsonObjectAdapter.validate_python(item) for item in (items or [])]
+
+
+def build_fix_wiki_plan(
+    *,
+    run_id: str,
+    wiki_dir: Path,
+    snapshot_hash: str,
+    vocabulary_status: str,
+    problems: Sequence[object],
+    taxonomy_operations: Sequence[object],
+    taxonomy_blocked: Sequence[object],
+    taxonomy_decision_approved: bool,
+    snapshot_files: Sequence[JsonObject] | None = None,
+    context_packets: JsonObject | None = None,
+    git_state: JsonObject | None = None,
+    vocabulary_map_hash: str = "",
+    deferred_work_items: Sequence[JsonObject] | None = None,
+) -> JsonObject:
+    problem_items = _problem_items(problems)
+    taxonomy_operation_items = _taxonomy_items(taxonomy_operations)
+    taxonomy_blocked_items = _taxonomy_items(taxonomy_blocked)
+    vocabulary_reason = _vocabulary_blocked_reason(vocabulary_status)
+    context_artifacts = sorted(
+        {
+            problem.context_packet
+            for problem in problem_items
+            if problem.context_packet
+        }
+    )
+    taxonomy_artifacts = (
+        ["taxonomy-plan.json", *context_artifacts]
+        if taxonomy_operation_items or taxonomy_blocked_items
+        else context_artifacts
+    )
+
+    taxonomy_status = "ready"
+    taxonomy_can_apply = True
+    taxonomy_blocked_reason = ""
+    taxonomy_requires_decision = ""
+    taxonomy_requires_human = False
+    if taxonomy_blocked_items:
+        taxonomy_status = "blocked"
+        taxonomy_can_apply = False
+        taxonomy_blocked_reason = "taxonomy_plan_blocked"
+    elif taxonomy_operation_items and not taxonomy_decision_approved:
+        taxonomy_status = "needs_decision"
+        taxonomy_can_apply = False
+        taxonomy_blocked_reason = "taxonomy_decision_required"
+        taxonomy_requires_decision = "approve_taxonomy_moves"
+        taxonomy_requires_human = True
+
+    phases = [
+        _phase("preflight"),
+        _phase("inventory"),
+        _phase("vocabulary_bootstrap"),
+        _phase("vocabulary_map_diagnosis", status=vocabulary_status or "skipped", blocked_reason=vocabulary_reason),
+        _phase("style_yaml"),
+        _phase("provenance_backfill"),
+        _phase("hygiene"),
+        _phase(
+            "duplicates",
+            status="blocked" if vocabulary_status == "blocked_human" else "ready",
+            can_apply=vocabulary_status != "blocked_human",
+            blocked_reason="vocabulary_map_blocked" if vocabulary_status == "blocked_human" else "",
+        ),
+        _phase(
+            "taxonomy",
+            status=taxonomy_status,
+            can_apply=taxonomy_can_apply,
+            blocked_reason=taxonomy_blocked_reason,
+            requires_decision=taxonomy_requires_decision,
+            requires_human=taxonomy_requires_human,
+            affected_paths=[
+                item.source
+                for item in [*taxonomy_operation_items, *taxonomy_blocked_items]
+                if item.source
+            ],
+            planned_artifacts=taxonomy_artifacts,
+            rollback_strategy="taxonomy_receipt" if taxonomy_operation_items else "",
+        ),
+        _phase(
+            "linker",
+            status="blocked" if vocabulary_reason else "ready",
+            can_apply=not bool(vocabulary_reason),
+            blocked_reason=vocabulary_reason,
+            planned_artifacts=["link-trigger-context.json", "link-diagnosis.json"],
+            rollback_strategy="link-run-receipt",
+        ),
+        _phase("final_validation", can_apply=False),
+    ]
+
+    if taxonomy_blocked_items or vocabulary_status == "blocked_human":
+        status = "blocked"
+    elif any(problem.decision_required for problem in problem_items) or taxonomy_status == "needs_decision":
+        status = "needs_decision"
+    elif vocabulary_status == "blocked_pending":
+        status = "blocked"
+    else:
+        status = "ready"
+
+    plan = FixWikiPlan(
+        run_id=run_id,
+        wiki_dir=str(wiki_dir),
+        snapshot_hash=snapshot_hash,
+        snapshot_files=[FixWikiSnapshotFile.model_validate(item) for item in (snapshot_files or [])],
+        context_packet_hashes=_context_packet_hashes(context_packets),
+        git=JsonObjectAdapter.validate_python(git_state or {}),
+        vocabulary_map_hash=vocabulary_map_hash,
+        phase_order=list(ORDERED_FIX_WIKI_PHASES),
+        status=status,
+        problems=problem_items,
+        fix_wiki_problems=problem_items,
+        deferred_work_items=_json_object_list(deferred_work_items),
+        phases=phases,
+        blockers=[problem for problem in problem_items if problem.status == "blocked"],
+        warnings=[problem for problem in problem_items if problem.severity == "low"],
+    )
+    plan.plan_hash = _hash_plan(plan.to_payload())
+    return plan.to_payload()

package/.opencode/mednotes/src/mednotes/domains/wiki/flows/fix_wiki/fix_wiki_primary_objective.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from mednotes.domains.wiki.contracts.agent_report import (
+    FixWikiGraphStatus,
+    FixWikiObjectiveStatus,
+    FixWikiPrimaryObjectiveSummary,
+    FixWikiRelatedNotesStatus,
+)
+from mednotes.kernel.base import JsonObject, JsonObjectAdapter, JsonValue
+
+_INTERNAL_RELATED_NOTES_SKIP_REASONS = {
+    "linker_not_run",
+    "not_needed",
+    "no_link_trigger",
+    "no_related_notes_changes",
+}
+
+
+class _ObjectiveModel(BaseModel):
+    # These are partial typed lenses over larger payloads: unknown keys are
+    # ignored, but known operational fields remain strict and cannot be
+    # fabricated through Pydantic coercion.
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, strict=True)
+
+
+class _ObjectiveCounts(_ObjectiveModel):
+    mutated_files: int = 0
+    written_files: int = 0
+
+
+class _ObjectiveProgress(_ObjectiveModel):
+    status: str = ""
+    counts: _ObjectiveCounts | None = None
+
+    @field_validator("counts", mode="before")
+    @classmethod
+    def _empty_counts(cls, value: object) -> object:
+        return value if isinstance(value, dict) else None
+
+
+class _ObjectiveReceipt(_ObjectiveModel):
+    status: str = ""
+
+
+class _ObjectiveApplyContext(_ObjectiveModel):
+    vault_changed_file_count: int = 0
+    written_count: int = 0
+
+
+class _ObjectiveGraph(_ObjectiveModel):
+    error_count: int = 0
+    blocker_count: int = 0
+    blockers: JsonValue = 0
+
+
+class _ObjectiveFinalValidation(_ObjectiveModel):
+    graph: _ObjectiveGraph | None = None
+
+
+class _ObjectiveGraphAudit(_ObjectiveModel):
+    error_count: int = 0
+
+
+class _ObjectiveRelatedNotesSync(_ObjectiveModel):
+    status: str = ""
+    blocked_reason: str = ""
+    skipped_reason: str = ""
+    applied_note_count: int = 0
+
+
+class _ObjectiveLinkerApply(_ObjectiveModel):
+    related_notes_sync: _ObjectiveRelatedNotesSync | None = None
+
+
+class _ObjectiveRelatedRecoveryState(_ObjectiveModel):
+    status: str = ""
+    blocked_reason: str = ""
+    remaining_count: int = 0
+    total_note_count: int = 0
+    fresh_record_count: int = 0
+    partial_record_count: int = 0
+
+
+class _ObjectiveDiagnostic(_ObjectiveModel):
+    apply: _ObjectiveApplyContext | None = None
+    final_validation: _ObjectiveFinalValidation | None = None
+    graph_audit_before_linker: _ObjectiveGraphAudit | None = None
+    graph_error_count_before_linker: int | None = None
+    related_notes_recovery_state: _ObjectiveRelatedRecoveryState | None = None
+    related_notes_sync: _ObjectiveRelatedNotesSync | None = None
+    related_notes_applied: bool = False
+    linker_apply: _ObjectiveLinkerApply | None = None
+
+    @field_validator(
+        "apply",
+        "final_validation",
+        "graph_audit_before_linker",
+        "related_notes_recovery_state",
+        "related_notes_sync",
+        "linker_apply",
+        mode="before",
+    )
+    @classmethod
+    def _empty_optional_object(cls, value: object) -> object:
+        return value if isinstance(value, dict) else None
+
+
+class _FixWikiObjectivePayload(_ObjectiveModel):
+    schema_id: str = Field(default="", alias="schema")
+    workflow: str = ""
+    progress_view_model: _ObjectiveProgress | None = None
+    receipt: _ObjectiveReceipt | None = None
+    diagnostic_context: _ObjectiveDiagnostic | None = None
+
+
+def fix_wiki_primary_objective_summary(payload: JsonObject) -> FixWikiPrimaryObjectiveSummary | None:
+    payload = JsonObjectAdapter.validate_python(payload)
+    root = _FixWikiObjectivePayload.model_validate(payload)
+    if not _is_fix_wiki_payload(root):
+        return None
+
+    progress = root.progress_view_model or _ObjectiveProgress()
+    receipt = root.receipt or _ObjectiveReceipt()
+    diagnostic = root.diagnostic_context or _ObjectiveDiagnostic()
+    status = _first_status(progress.status, receipt.status)
+
+    mutation_count, written_count = _mutation_counts(
+        progress=progress,
+        diagnostic=diagnostic,
+    )
+    graph_status, graph_summary = _graph_outcome(diagnostic=diagnostic)
+    related_status, related_summary = _related_notes_outcome(diagnostic=diagnostic)
+    wiki_fixed, wiki_summary = _wiki_outcome(status=status, graph_status=graph_status, related_status=related_status)
+
+    return FixWikiPrimaryObjectiveSummary(
+        wiki_fixed=wiki_fixed,
+        wiki_summary=wiki_summary,
+        mutation_count=mutation_count,
+        written_count=written_count,
+        mutation_summary=_mutation_summary(mutation_count=mutation_count, written_count=written_count),
+        graph_status=graph_status,
+        graph_summary=graph_summary,
+        related_notes_status=related_status,
+        related_notes_summary=related_summary,
+    )
+
+
+def _is_fix_wiki_payload(payload: _FixWikiObjectivePayload) -> bool:
+    return payload.workflow == "/mednotes:fix-wiki" or payload.schema_id == "medical-notes-workbench.fix-wiki-fsm-result.v1"
+
+
+def _mutation_counts(
+    *,
+    progress: _ObjectiveProgress,
+    diagnostic: _ObjectiveDiagnostic,
+) -> tuple[int, int]:
+    mutation_count = (
+        _as_int((progress.counts or _ObjectiveCounts()).mutated_files)
+        or _as_int((diagnostic.apply or _ObjectiveApplyContext()).vault_changed_file_count)
+    )
+    written_count = (
+        _as_int((progress.counts or _ObjectiveCounts()).written_files)
+        or _as_int((diagnostic.apply or _ObjectiveApplyContext()).written_count)
+    )
+    return mutation_count, written_count
+
+
+def _mutation_summary(*, mutation_count: int, written_count: int) -> str:
+    if mutation_count == 0 and written_count == 0:
+        return "Nenhum arquivo da Wiki foi alterado nesta etapa."
+    if mutation_count == written_count:
+        return f"{mutation_count} arquivo(s) da Wiki alterado(s)."
+    return f"{mutation_count} arquivo(s) da Wiki mudaram; {written_count} arquivo(s) foram gravados pelo reparo automático."
+
+
+def _graph_outcome(
+    *,
+    diagnostic: _ObjectiveDiagnostic,
+) -> tuple[FixWikiGraphStatus, str]:
+    final_validation = diagnostic.final_validation or _ObjectiveFinalValidation()
+    graph = final_validation.graph
+    if graph is None and diagnostic.graph_error_count_before_linker is None and diagnostic.graph_audit_before_linker is None:
+        return "unknown", "O payload não trouxe comparação suficiente do grafo."
+    graph = graph or _ObjectiveGraph()
+    after_errors = _as_int(graph.error_count)
+    after_blockers = _as_int(graph.blocker_count or graph.blockers)
+    if diagnostic.graph_error_count_before_linker is not None:
+        before_errors = _optional_int(diagnostic.graph_error_count_before_linker)
+    elif diagnostic.graph_audit_before_linker is not None:
+        before_errors = _optional_int(diagnostic.graph_audit_before_linker.error_count)
+    else:
+        before_errors = None
+
+    if before_errors is not None:
+        if after_errors < before_errors:
+            return "improved", f"O grafo melhorou: {before_errors} erro(s) antes, {after_errors} depois."
+        if after_errors > before_errors:
+            return "worse", f"O grafo piorou: {before_errors} erro(s) antes, {after_errors} depois."
+        if after_errors == 0:
+            return "clean", "O grafo terminou sem erros."
+        return "unchanged", f"O grafo não melhorou: permaneceu com {after_errors} erro(s)."
+
+    if after_errors == 0 and after_blockers == 0:
+        return "clean", "O grafo terminou sem bloqueios."
+    if after_errors or after_blockers:
+        count = after_blockers or after_errors
+        return "blocked", f"O grafo ainda tem {count} bloqueio(s)."
+    return "unknown", "O payload não trouxe comparação suficiente do grafo."
+
+
+def _related_notes_outcome(
+    *,
+    diagnostic: _ObjectiveDiagnostic,
+) -> tuple[FixWikiRelatedNotesStatus, str]:
+    recovery_state = diagnostic.related_notes_recovery_state or _ObjectiveRelatedRecoveryState()
+    related_sync = diagnostic.related_notes_sync or _ObjectiveRelatedNotesSync()
+    linker_apply = diagnostic.linker_apply or _ObjectiveLinkerApply()
+    linker_related = linker_apply.related_notes_sync or _ObjectiveRelatedNotesSync()
+    if not _related_notes_sync_has_signal(related_sync) and _related_notes_sync_has_signal(linker_related):
+        related_sync = linker_related
+
+    remaining = _as_int(recovery_state.remaining_count)
+    total = _as_int(recovery_state.total_note_count)
+    fresh = _as_int(recovery_state.fresh_record_count or recovery_state.partial_record_count)
+    recovery_reason = recovery_state.blocked_reason
+    if recovery_state.status == "waiting_for_retry" or remaining:
+        reason = "cota externa" if "quota" in recovery_reason or "cota" in recovery_reason else "condição externa"
+        count = f" ({fresh}/{total}, faltam {remaining})" if total else ""
+        return "pending", f"Notas Relacionadas ficou pendente por {reason}{count}."
+
+    if related_sync.status == "completed" or diagnostic.related_notes_applied is True:
+        applied = _as_int(related_sync.applied_note_count)
+        if applied:
+            return "updated", f"Notas Relacionadas foi atualizado em {applied} nota(s)."
+        return "updated", "Notas Relacionadas foi atualizado."
+
+    blocked_reason = related_sync.blocked_reason
+    if related_sync.status == "blocked" or blocked_reason:
+        return "blocked", f"Notas Relacionadas ficou bloqueado: {blocked_reason or 'bloqueio não especificado'}."
+
+    skipped_reason = related_sync.skipped_reason
+    if related_sync.status == "skipped" or skipped_reason:
+        reason = _public_related_notes_skip_reason(skipped_reason)
+        return "skipped", f"Notas Relacionadas não foi alterado: {reason}."
+
+    return "unknown", "O payload não confirmou atualização de Notas Relacionadas."
+
+
+def _public_related_notes_skip_reason(value: str) -> str:
+    """Translate internal skip codes before they reach agent-facing reports."""
+
+    if not value:
+        return "fora do escopo desta etapa"
+    if value.strip().casefold() in _INTERNAL_RELATED_NOTES_SKIP_REASONS:
+        return "fora do escopo desta etapa"
+    return value
+
+
+def _wiki_outcome(
+    *,
+    status: str,
+    graph_status: FixWikiGraphStatus,
+    related_status: FixWikiRelatedNotesStatus,
+) -> tuple[FixWikiObjectiveStatus, str]:
+    if status == "completed":
+        return "yes", "Sim, o fix-wiki concluiu a correção da Wiki."
+    if status == "completed_with_warnings":
+        return "partial", "A Wiki foi corrigida com avisos pendentes."
+    if status == "waiting_external":
+        return "waiting_external", "A Wiki ficou parcialmente corrigida e aguarda uma condição externa."
+    if status == "waiting_agent":
+        return "waiting_agent", "A Wiki ficou parcialmente corrigida e aguarda continuação assistida pelo agente."
+    if status == "failed":
+        return "failed", "Não, o fix-wiki falhou antes de concluir."
+    if status in {"blocked", "waiting_human"}:
+        return "no", "Não, o fix-wiki ainda não concluiu a correção da Wiki."
+    if graph_status in {"clean", "improved"} and related_status == "updated":
+        return "yes", "Sim, os sinais principais indicam Wiki corrigida."
+    return "unknown", "O payload não permite confirmar se o fix-wiki concluiu a Wiki."
+
+
+def _related_notes_sync_has_signal(sync: _ObjectiveRelatedNotesSync) -> bool:
+    return bool(sync.status or sync.blocked_reason or sync.skipped_reason or sync.applied_note_count)
+
+
+def _first_status(*sources: str) -> str:
+    for value in sources:
+        if value:
+            return value
+    return ""
+
+
+def _as_int(value: object) -> int:
+    if value is None:
+        return 0
+    if isinstance(value, bool):
+        raise ValueError("numeric fix-wiki fields must be numbers, not booleans")
+    if isinstance(value, str):
+        raise ValueError("numeric fix-wiki fields must be numbers, not strings")
+    if isinstance(value, int | float):
+        return max(0, int(value))
+    raise ValueError("numeric fix-wiki fields must be numbers")
+
+
+def _optional_int(value: object) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError("numeric fix-wiki fields must be numbers, not booleans")
+    if isinstance(value, str):
+        raise ValueError("numeric fix-wiki fields must be numbers, not strings")
+    if isinstance(value, int | float):
+        return max(0, int(value))
+    raise ValueError("numeric fix-wiki fields must be numbers")