@trac3r/oh-my-god 2.2.11

package/runtime/forge_contracts.py

@@ -0,0 +1,519 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from pathlib import Path
+from time import monotonic
+from typing import cast
+
+from lab.policies import validate_job_request
+from runtime.domain_packs import DOMAIN_PACKS, get_domain_pack_contract
+from runtime.forge_domains import canonical_domain_for, get_all_canonical_domains, is_valid_domain
+from runtime.runtime_contracts import read_defense_state, read_session_health
+
+FORGE_STAGE_ORDER: tuple[str, ...] = (
+    "data_prepare",
+    "synthetic_refine",
+    "train_distill",
+    "evaluate",
+    "regression_test",
+)
+
+DEFAULT_STAGE_TIMEOUT_MS: dict[str, int] = {
+    "data_prepare": 5_000,
+    "synthetic_refine": 5_000,
+    "train_distill": 5_000,
+    "evaluate": 5_000,
+    "regression_test": 5_000,
+}
+
+AXOLOTL_LIVE_MODES: tuple[str, ...] = (
+    "preflight",
+    "live_sft",
+    "live_grpo",
+    "live_gdpo",
+)
+
+AXOLOTL_SEARCH_POLICY: dict[str, object] = {
+    "max_trials": 6,
+    "space": {
+        "learning_rate": [1e-5, 3e-5, 1e-4],
+        "batch_size": [4, 8],
+        "lora_rank": [8, 16, 32],
+        "grad_accum": [1, 2, 4],
+    },
+}
+
+OPERATION_ORCHESTRATION_PROFILES: dict[str, dict[str, object]] = {
+    "add": {
+        "mode": "incremental_extension",
+        "priority": "scope_safeguards",
+        "required_checks": ["schema_alignment", "backward_compatibility"],
+    },
+    "edit": {
+        "mode": "targeted_refinement",
+        "priority": "change_precision",
+        "required_checks": ["delta_scope", "regression_surface"],
+    },
+    "delete": {
+        "mode": "controlled_removal",
+        "priority": "safety_first",
+        "required_checks": ["dependency_impact", "rollback_path"],
+    },
+    "unknown": {
+        "mode": "bounded_execution",
+        "priority": "contract_defaults",
+        "required_checks": ["domain_contract"],
+    },
+}
+
+
+def _normalize_required_checks(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(check) for check in value if isinstance(check, str)]
+
+
+ADAPTER_REGISTRY: dict[str, dict[str, object]] = {
+    "axolotl": {
+        "kind": "training",
+        "module": "axolotl",
+        "hook": "lab.axolotl_adapter.run",
+        "specialist": "training-architect",
+        "modes": list(AXOLOTL_LIVE_MODES),
+        "default_mode": "live_sft",
+        "rl_sidecar_required": {
+            "live_grpo": True,
+            "live_gdpo": True,
+        },
+        "search_policy": dict(AXOLOTL_SEARCH_POLICY),
+    },
+    "pybullet": {
+        "kind": "simulator",
+        "module": "pybullet",
+        "hook": "lab.pybullet_adapter.run",
+        "specialist": "simulator-engineer",
+        "primary": True,
+    },
+    "gazebo": {
+        "kind": "simulator",
+        "module": "gazebo",
+        "hook": "lab.gazebo_adapter.run",
+        "specialist": "simulator-engineer",
+        "primary": False,
+    },
+    "isaac_gym": {
+        "kind": "simulator",
+        "module": "isaacgym",
+        "hook": "lab.isaac_gym_adapter.run",
+        "specialist": "simulator-engineer",
+        "primary": False,
+    },
+}
+
+
+def load_forge_mvp() -> dict[str, object]:
+    return {
+        "axolotl_hook": "lab.axolotl_adapter.run",
+        "pybullet_hook": "lab.pybullet_adapter.run",
+        "labs_only": True,
+        "job_schema": {
+            "required": ["dataset", "base_model", "target_metric"],
+            "dataset_required": ["name", "license", "source"],
+            "base_model_required": ["name", "source", "allow_distill"],
+            "optional": ["simulated_metric", "evaluation_notes", "simulator_backend", "require_backend"],
+        },
+        "evaluation_schema": {
+            "required": ["status", "stage", "evaluation_report", "published"],
+            "report_required": ["created_at", "metric", "target_metric", "passed", "notes"],
+            "artifact": "forge-evaluation-evidence",
+        },
+        "specialist_dispatch": {
+            "axolotl": ["dataset", "base_model", "target_metric"],
+            "pybullet": ["dataset", "target_metric", "simulated_metric"],
+            "forge-cybersecurity": ["dataset", "base_model", "target_metric", "evaluation_notes"],
+        },
+        "stage_aliases": {
+            "security_review": "regression_test",
+            "threat_model": "evaluate",
+        },
+        "operation_orchestration": {
+            intent: {
+                "mode": str(profile.get("mode", "bounded_execution")),
+                "priority": str(profile.get("priority", "contract_defaults")),
+                "required_checks": _normalize_required_checks(profile.get("required_checks")),
+            }
+            for intent, profile in OPERATION_ORCHESTRATION_PROFILES.items()
+        },
+        "specialist_contracts": {
+            "forge-cybersecurity": {
+                "labs_only": True,
+                "allowed_domains": ["cybersecurity"],
+                "evidence_profile": "security-audit",
+                "proof_backed_dispatch": True,
+                "stage_alias": "regression_test",
+                "evidence_outputs": {
+                    "sarif": ".omg/evidence/security-*.sarif",
+                    "sbom": ".omg/evidence/sbom-*.cdx.json",
+                    "license": ".omg/evidence/license-*.json",
+                    "security_json": ".omg/evidence/security-*.json",
+                },
+                "reuses_scanner": "runtime.security_check",
+            },
+            "music-omr": {
+                "labs_only": True,
+                "allowed_domains": ["music-omr"],
+                "evidence_profile": "music-omr",
+                "proof_backed_dispatch": True,
+                "stage_alias": "regression_test",
+                "evidence_outputs": {
+                    "omr_json": ".omg/evidence/music-omr-*.json",
+                },
+                "reuses_scanner": "runtime.music_omr_testbed",
+            },
+        },
+        "domain_evidence_profiles": {
+            "vision": "forge-vision",
+            "robotics": "forge-run",
+            "algorithms": "transposition-flow",
+            "health": "health-flow",
+            "cybersecurity": "security-audit",
+        },
+        "adapter_registry": dict(ADAPTER_REGISTRY),
+        "axolotl_search_policy": dict(AXOLOTL_SEARCH_POLICY),
+        "canonical_domains": get_all_canonical_domains(),
+        "evidence_output_path": ".omg/evidence/forge-<run_id>.json",
+        "starter_templates": {
+            "vision-agent": {
+                "domain": "vision-agent",
+                "specialists": ["data-curator", "training-architect", "simulator-engineer"],
+                "dataset": {"name": "vision-agent", "license": "apache-2.0", "source": "internal-curated"},
+                "base_model": {"name": "distill-base-v1", "source": "approved-registry", "allow_distill": True},
+                "target_metric": 0.8,
+            },
+            "robotics": {
+                "domain": "robotics",
+                "specialists": ["training-architect", "simulator-engineer"],
+                "dataset": {"name": "robotics", "license": "apache-2.0", "source": "internal-curated"},
+                "base_model": {"name": "distill-base-v1", "source": "approved-registry", "allow_distill": True},
+                "target_metric": 0.8,
+            },
+            "algorithms": {
+                "domain": "algorithms",
+                "specialists": ["training-architect"],
+                "dataset": {"name": "algorithms", "license": "apache-2.0", "source": "internal-curated"},
+                "base_model": {"name": "distill-base-v1", "source": "approved-registry", "allow_distill": True},
+                "target_metric": 0.8,
+            },
+            "health": {
+                "domain": "health",
+                "specialists": ["data-curator", "training-architect"],
+                "dataset": {"name": "health", "license": "apache-2.0", "source": "internal-curated"},
+                "base_model": {"name": "distill-base-v1", "source": "approved-registry", "allow_distill": True},
+                "target_metric": 0.8,
+            },
+            "cybersecurity": {
+                "domain": "cybersecurity",
+                "specialists": ["forge-cybersecurity"],
+                "dataset": {"name": "cybersecurity", "license": "apache-2.0", "source": "internal-curated"},
+                "base_model": {"name": "distill-base-v1", "source": "approved-registry", "allow_distill": True},
+                "target_metric": 0.8,
+            },
+        },
+    }
+
+
+def validate_forge_job(job: dict[str, object]) -> tuple[bool, str]:
+    domain = job.get("domain")
+    if not domain or not str(domain).strip():
+        return False, "domain missing: forge run requires an explicit canonical domain (e.g. 'vision', 'robotics')"
+    if not is_valid_domain(str(domain)):
+        valid = sorted(get_all_canonical_domains())
+        return False, f"unknown domain: {domain!r}. Valid domains: {valid}"
+    job["domain"] = canonical_domain_for(str(domain))
+
+    ok, reason = validate_job_request(job)
+    if not ok:
+        return False, reason
+
+    dataset = job.get("dataset")
+    base_model = job.get("base_model")
+
+    if not isinstance(dataset, dict):
+        return False, "dataset block missing"
+    if not isinstance(base_model, dict):
+        return False, "base_model block missing"
+
+    dataset_block = cast(dict[str, object], dataset)
+    base_model_block = cast(dict[str, object], base_model)
+
+    if not str(dataset_block.get("name", "")).strip():
+        return False, "dataset.name missing"
+    if not str(base_model_block.get("name", "")).strip():
+        return False, "base_model.name missing"
+
+    target_metric = job.get("target_metric")
+    if target_metric is None:
+        return False, "target_metric missing or invalid"
+    try:
+        _ = float(str(target_metric))
+    except (TypeError, ValueError):
+        return False, "target_metric missing or invalid"
+
+    return True, "ok"
+
+
+def read_stage_runtime_snapshots(project_dir: str, run_id: str) -> tuple[dict[str, object], dict[str, object]]:
+    defense_payload = read_defense_state(project_dir, run_id=run_id, compat=True)
+    health_payload = read_session_health(project_dir, run_id=run_id, compat=True)
+    defense_snapshot: dict[str, object] = {}
+    session_health_snapshot: dict[str, object] = {}
+    if isinstance(defense_payload, dict):
+        defense_snapshot = cast(dict[str, object], dict(defense_payload))
+    if isinstance(health_payload, dict):
+        session_health_snapshot = cast(dict[str, object], dict(health_payload))
+    return defense_snapshot, session_health_snapshot
+
+
+def resolve_stage_timeout_ms(job: Mapping[str, object], stage: str) -> int:
+    timeout_value: object | None = None
+    stage_timeouts = job.get("stage_timeouts_ms")
+    if isinstance(stage_timeouts, Mapping):
+        timeout_value = stage_timeouts.get(stage)
+    if timeout_value is None:
+        timeout_value = DEFAULT_STAGE_TIMEOUT_MS.get(stage, 5_000)
+
+    if isinstance(timeout_value, bool):
+        return DEFAULT_STAGE_TIMEOUT_MS.get(stage, 5_000)
+    if isinstance(timeout_value, int):
+        parsed = timeout_value
+    elif isinstance(timeout_value, float):
+        parsed = int(timeout_value)
+    elif isinstance(timeout_value, str):
+        try:
+            parsed = int(timeout_value)
+        except ValueError:
+            return DEFAULT_STAGE_TIMEOUT_MS.get(stage, 5_000)
+    else:
+        return DEFAULT_STAGE_TIMEOUT_MS.get(stage, 5_000)
+    return max(0, parsed)
+
+
+def build_stage_evidence(
+    *,
+    stage: str,
+    run_id: str,
+    status: str,
+    started_at_ms: float,
+    defense_snapshot: Mapping[str, object],
+    session_health_snapshot: Mapping[str, object],
+    artifacts: list[str],
+    adapter_evidence: list[dict[str, object]] | None = None,
+) -> dict[str, object]:
+    duration_ms = max(0, int((monotonic() - started_at_ms) * 1000))
+    result: dict[str, object] = {
+        "stage": stage,
+        "run_id": run_id,
+        "status": status,
+        "duration_ms": duration_ms,
+        "defense_snapshot": dict(defense_snapshot),
+        "session_health_snapshot": dict(session_health_snapshot),
+        "artifacts": list(artifacts),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    if adapter_evidence is not None:
+        result["adapter_evidence"] = list(adapter_evidence)
+    return result
+
+
+def build_forge_evidence(
+    project_dir: str,
+    run_id: str,
+    job: Mapping[str, object],
+    result: Mapping[str, object],
+    *,
+    stage_evidence: list[Mapping[str, object]] | None = None,
+) -> str:
+    out_path = Path(project_dir) / ".omg" / "evidence" / f"forge-{run_id}.json"
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    domain = str(job.get("domain", "")).strip()
+    specialists_raw = job.get("specialists")
+    specialist_str = ",".join(str(s) for s in specialists_raw) if isinstance(specialists_raw, list) else ""
+
+    merged_stage_evidence: list[Mapping[str, object]] = []
+    if stage_evidence is not None:
+        merged_stage_evidence = list(stage_evidence)
+    else:
+        existing_stage_evidence = result.get("stage_evidence")
+        if isinstance(existing_stage_evidence, list):
+            merged_stage_evidence = [
+                cast(Mapping[str, object], item)
+                for item in existing_stage_evidence
+                if isinstance(item, Mapping)
+            ]
+
+    job_dict = dict(job)
+    base_model_name = "unknown"
+    base_model_raw = job.get("base_model")
+    if isinstance(base_model_raw, Mapping):
+        base_model_name = str(base_model_raw.get("name", "unknown"))
+
+    evaluation_metric = 0.0
+    evaluation_report = result.get("evaluation_report")
+    if isinstance(evaluation_report, Mapping):
+        metric_raw = evaluation_report.get("metric", 0.0)
+        if isinstance(metric_raw, bool):
+            evaluation_metric = 0.0
+        elif isinstance(metric_raw, (int, float)):
+            evaluation_metric = float(metric_raw)
+        elif isinstance(metric_raw, str):
+            try:
+                evaluation_metric = float(metric_raw)
+            except ValueError:
+                evaluation_metric = 0.0
+
+    target_metric = 0.0
+    target_metric_raw = job.get("target_metric", 0.0)
+    if isinstance(target_metric_raw, bool):
+        target_metric = 0.0
+    elif isinstance(target_metric_raw, (int, float)):
+        target_metric = float(target_metric_raw)
+    elif isinstance(target_metric_raw, str):
+        try:
+            target_metric = float(target_metric_raw)
+        except ValueError:
+            target_metric = 0.0
+
+    context_checksum = hashlib.sha256(json.dumps(job_dict, sort_keys=True).encode()).hexdigest()
+    domain_pack = get_domain_pack_contract(domain) if domain in DOMAIN_PACKS else {}
+    artifact_contracts = _resolve_artifact_contracts(
+        run_id=run_id,
+        result=result,
+        evaluation_metric=evaluation_metric,
+        target_metric=target_metric,
+        base_model_name=base_model_name,
+    )
+    payload = {
+        "schema": "ForgeMVPEvidence",
+        "schema_version": "1.0.0",
+        "run_id": run_id,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "labs_only": True,
+        "proof_backed": True,
+        "specialist": specialist_str,
+        "domain": domain,
+        "contract": load_forge_mvp(),
+        "job": job,
+        "result": result,
+        "status": result.get("status", "unknown"),
+        "evaluation_report": result.get("evaluation_report"),
+        "stages": result.get("stages", []),
+        "stage_evidence": merged_stage_evidence,
+        "causal_chain": {
+            "lock_id": "",
+            "waiver_artifact_path": str(out_path),
+            "delta_summary": {"forge_run": run_id, "domain": domain, "specialist": specialist_str},
+            "verification_status": str(result.get("status", "unknown")),
+        },
+        "context_checksum": context_checksum,
+        "profile_version": "forge-run-v1",
+        "intent_gate_version": "1.0.0",
+        "domain_pack": domain_pack,
+        "artifact_contracts": artifact_contracts,
+    }
+
+    if domain == "cybersecurity":
+        evidence_dir = out_path.parent
+        security_links: list[str] = []
+        for pattern in ("security-*.json", "security-*.sarif"):
+            security_links.extend(
+                f".omg/evidence/{p.name}" for p in sorted(evidence_dir.glob(pattern))
+            )
+        payload["security_evidence_links"] = security_links if security_links else [
+            ".omg/evidence/security-*.json",
+            ".omg/evidence/security-*.sarif",
+        ]
+
+    tmp_path = out_path.with_name(f"{out_path.name}.tmp")
+    _ = tmp_path.write_text(json.dumps(payload, indent=2, ensure_ascii=True), encoding="utf-8")
+    _ = os.rename(tmp_path, out_path)
+    return str(out_path)
+
+
+def _resolve_artifact_contracts(
+    *,
+    run_id: str,
+    result: Mapping[str, object],
+    evaluation_metric: float,
+    target_metric: float,
+    base_model_name: str,
+) -> dict[str, object]:
+    result_contracts = result.get("artifact_contracts")
+    if isinstance(result_contracts, Mapping):
+        normalized = {str(key): value for key, value in result_contracts.items()}
+        if "dataset_lineage" not in normalized:
+            normalized["dataset_lineage"] = {
+                "standard": "Croissant-1.1",
+                "path": f".omg/evidence/forge-lineage-{run_id}.json",
+                "status": "pending_verification",
+                "lineage_hash": hashlib.sha256(f"lineage-{run_id}".encode()).hexdigest(),
+                "deterministic_metadata": True,
+            }
+        if "model_card" not in normalized:
+            normalized["model_card"] = {
+                "standard": "HuggingFace-ModelCard",
+                "path": f".omg/evidence/forge-model-card-{run_id}.md",
+                "status": "pending_verification",
+                "model_id": f"forge-model-{run_id}",
+                "base_model": base_model_name,
+            }
+        if "checkpoint_hash" not in normalized:
+            normalized["checkpoint_hash"] = {
+                "standard": "OpenSSF-OMS",
+                "path": f".omg/evidence/forge-checkpoint-{run_id}.json",
+                "status": "pending_verification",
+                "sha256": hashlib.sha256(f"checkpoint-{run_id}".encode()).hexdigest(),
+                "algorithm": "sha256",
+            }
+        return normalized
+
+    return {
+        "dataset_lineage": {
+            "standard": "Croissant-1.1",
+            "path": f".omg/evidence/forge-lineage-{run_id}.json",
+            "status": "pending_verification",
+            "lineage_hash": hashlib.sha256(f"lineage-{run_id}".encode()).hexdigest(),
+            "deterministic_metadata": True,
+        },
+        "model_card": {
+            "standard": "HuggingFace-ModelCard",
+            "path": f".omg/evidence/forge-model-card-{run_id}.md",
+            "status": "pending_verification",
+            "model_id": f"forge-model-{run_id}",
+            "base_model": base_model_name,
+        },
+        "checkpoint_hash": {
+            "standard": "OpenSSF-OMS",
+            "path": f".omg/evidence/forge-checkpoint-{run_id}.json",
+            "status": "pending_verification",
+            "sha256": hashlib.sha256(f"checkpoint-{run_id}".encode()).hexdigest(),
+            "algorithm": "sha256",
+        },
+        "regression_scoreboard": {
+            "standard": "lm-eval",
+            "path": f".omg/evidence/forge-scoreboard-{run_id}.json",
+            "status": "insufficient_evidence",
+            "score": evaluation_metric,
+            "target": target_metric,
+        },
+        "promotion_decision": {
+            "status": "pending",
+            "decision_id": f"dec-{run_id}",
+            "reason": "promotion requires passing regression scoreboard and human review for health domain",
+            "replay_required": True,
+        },
+    }

package/runtime/forge_domains.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+CANONICAL_DOMAINS: dict[str, dict[str, Any]] = {
+    "vision": {
+        "canonical_id": "vision",
+        "aliases": ["vision-agent"],
+        "display_label": "Vision Agent",
+        "starter_template_id": "vision-agent",
+    },
+    "robotics": {
+        "canonical_id": "robotics",
+        "aliases": [],
+        "display_label": "Robotics",
+        "starter_template_id": "robotics",
+    },
+    "algorithms": {
+        "canonical_id": "algorithms",
+        "aliases": [],
+        "display_label": "Algorithms",
+        "starter_template_id": "algorithms",
+    },
+    "health": {
+        "canonical_id": "health",
+        "aliases": [],
+        "display_label": "Health",
+        "starter_template_id": "health",
+    },
+    "cybersecurity": {
+        "canonical_id": "cybersecurity",
+        "aliases": [],
+        "display_label": "Cybersecurity",
+        "starter_template_id": "cybersecurity",
+    },
+}
+
+# Build reverse alias map: alias -> canonical_id
+_ALIAS_MAP: dict[str, str] = {}
+for _canonical_id, _entry in CANONICAL_DOMAINS.items():
+    _ALIAS_MAP[_canonical_id] = _canonical_id
+    for _alias in _entry["aliases"]:
+        _ALIAS_MAP[_alias] = _canonical_id
+
+
+def canonical_domain_for(name: str) -> str:
+    """Resolve a domain name or alias to its canonical domain ID.
+
+    Raises ValueError for unknown domains.
+    """
+    normalized = str(name or "").strip().lower()
+    if normalized not in _ALIAS_MAP:
+        raise ValueError(
+            f"Unknown domain: {name!r}. Valid domains: {sorted(CANONICAL_DOMAINS.keys())}"
+        )
+    return _ALIAS_MAP[normalized]
+
+
+def is_valid_domain(name: str) -> bool:
+    """Return True if name is a canonical domain ID or a known alias."""
+    normalized = str(name or "").strip().lower()
+    return normalized in _ALIAS_MAP
+
+
+def get_all_canonical_domains() -> list[str]:
+    """Return list of all canonical domain IDs."""
+    return list(CANONICAL_DOMAINS.keys())

package/runtime/forge_run_id.py

@@ -0,0 +1,86 @@
+"""Canonical run identity generation and validation for Forge."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+
+
+DETERMINISM_VERSION = "forge-determinism-v1"
+DETERMINISM_SCOPE = "same-hardware"
+_TEMPERATURE_LOCK = {
+    "critical_model_paths": 0.0,
+    "critical_tool_paths": 0.0,
+}
+
+
+def generate_run_id() -> str:
+    """Generate a compact UTC timestamp-based run ID.
+    
+    Format: YYYYMMDDTHHMMSSfffffZ (e.g., 20260309T143022123456Z)
+    
+    Returns:
+        str: Compact UTC format run ID.
+    """
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+
+
+def derive_run_seed(run_id: str) -> int:
+    is_valid, reason = validate_run_id(run_id)
+    if not is_valid:
+        raise ValueError(f"invalid run_id for deterministic seed derivation: {reason}")
+
+    digest = hashlib.sha256(run_id.encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], byteorder="big", signed=False)
+
+
+def build_deterministic_contract(run_id: str) -> dict[str, object]:
+    return {
+        "seed": derive_run_seed(run_id),
+        "temperature_lock": dict(_TEMPERATURE_LOCK),
+        "determinism_version": DETERMINISM_VERSION,
+        "determinism_scope": DETERMINISM_SCOPE,
+    }
+
+
+def validate_run_id(run_id: str) -> tuple[bool, str]:
+    """Validate run ID format and constraints.
+    
+    Valid run IDs:
+    - Non-empty
+    - Alphanumeric + hyphens only (no spaces, special chars)
+    - Max 128 characters
+    
+    Args:
+        run_id: The run ID to validate.
+        
+    Returns:
+        tuple[bool, str]: (is_valid, reason). If valid, reason is empty string.
+    """
+    if not run_id:
+        return False, "run_id must be non-empty"
+    
+    if len(run_id) > 128:
+        return False, f"run_id exceeds 128 characters: {len(run_id)}"
+    
+    # Allow alphanumeric and hyphens only
+    if not all(c.isalnum() or c == "-" for c in run_id):
+        return False, "run_id must contain only alphanumeric characters and hyphens"
+    
+    return True, ""
+
+
+def normalize_run_id(run_id: str | None) -> str:
+    """Normalize run ID: use provided if valid, else generate new one.
+    
+    Args:
+        run_id: Optional run ID. If None or invalid, a new one is generated.
+        
+    Returns:
+        str: Valid run ID (either the provided one or a newly generated one).
+    """
+    if run_id:
+        is_valid, _ = validate_run_id(run_id)
+        if is_valid:
+            return run_id
+    
+    return generate_run_id()