Call this once when no existing run matches the work. The Engine creates the evaluator
    contract, measures its baseline, and refuses an unbounded budget.

    Returns: {"run_id": str, "contract": dict} plus any Engine feasibility fields, or
    {"error": true, "kind": str, "message": str}.

    Mistake to avoid: never leave max_evals, wall_clock_s, and max_cost_usd all unset.
    

    Call this before join_run and reread it whenever the metric, gate, target, or budget is
    unclear. Treat every returned contract field as law for the life of the run.

    Returns: {"goal", "domain", "metric", "maximize", "baseline", "target", "gate",
    "budget", "descriptors", "feasibility", "plateau_n"}, or the standard error dict.

    Mistake to avoid: never infer or rewrite the metric, gate, target, or budget.
    

    Call this after get_contract and before the first next_parent call. Pass a useful runtime
    label such as claude-code, codex, or a local worker identifier.

    Returns: {"island": int}, or {"error": true, "kind": str, "message": str}.

    Mistake to avoid: never invent an island number or reuse another worker's assignment.
    

    Call this at the start of every worker cycle. Read the parent files, every inspiration,
    every discovery, the operator hint, and any crossover parent before editing.

    Returns: {"parent": Program fields, "parent_files": {path: content}, "inspirations":
    [{"program": Program fields, "scores": dict, "files_excerpt": {path: content}}],
    "discoveries": [str], "operator_hint": str|null, "parent_sample_seq": int, and
    optional "crossover_parent" and "crossover_files"}, or the standard error dict.

    Mistake to avoid: never mutate before reading inspirations and discoveries.
    

    Call this once after producing one mutation from the current parent bundle. Echo its
    parent_sample_seq, use the selected or suggested operator, and explain reasoning in notes.

    Returns: {"program_id": str, "gate_passed": bool, "scores": dict, "fitness": number,
    "archive_improved": bool, "best_fitness": number, "plateau": bool,
    "budget_remaining": dict}, or the standard error dict.

    Mistake to avoid: never modify content outside EVOLVE-BLOCK markers. The Engine rejects it.
    

    Call this at checkpoints or after closure when you need the current leaders. The Engine
    owns ranking and returns its program records in best-first order.

    Returns: list[dict] containing up to k ranked program records, or the standard error dict.

    Mistake to avoid: never call a candidate best without using this measured ranking.
    

    Call this when explaining how a strong program was reached or when choosing which prior
    operators and changes deserve closer study.

    Returns: list[dict] of recorded lineage nodes for program_id, or the standard error dict.

    Mistake to avoid: never reconstruct ancestry from memory or filenames.
    

    Call this before a mutation when the parent bundle needs broader evidence or when a query
    can focus the search on a failure, operator, or implementation technique.

    Returns: list[dict] of discovery records matching domain and query, or the standard error
    dict.

    Mistake to avoid: never treat a discovery as proof for the current child until it is
    measured by submit_child.
    

    Call this after every submit_child and at the end of every cycle summary. Stop requesting
    parents when status says the run is closed.

    Returns: {"status": str, "curve": [[eval_idx, best_fitness]], "plateau": bool,
    "budget_remaining": dict, "islands": object, "artifacts": {"gif": path|null,
    "poster": path|null, "dashboard": path|null}}, or the standard error dict.

    Mistake to avoid: never omit the artifact paths or continue after a closed status.