Module Ir.Schedule_outcome

type phase =
  1. | Transform
  2. | Hardware_limits
  3. | Backend_codegen
  4. | Backend_compile
  5. | Launch
  6. | Sync
val sexp_of_phase : phase -> Sexplib0.Sexp.t
val compare_phase : phase -> phase -> int
val equal_phase : phase -> phase -> bool
type resource =
  1. | Workgroup_threads
  2. | Workgroup_memory
  3. | Thread_scratch
val sexp_of_resource : resource -> Sexplib0.Sexp.t
val compare_resource : resource -> resource -> int
val equal_resource : resource -> resource -> bool
type severity =
  1. | Expected
  2. | Compiler_bug
val sexp_of_severity : severity -> Sexplib0.Sexp.t
val compare_severity : severity -> severity -> int
val equal_severity : severity -> severity -> bool
type execution_effect =
  1. | No_device_writes
  2. | Writes_may_have_occurred
val sexp_of_execution_effect : execution_effect -> Sexplib0.Sexp.t
val compare_execution_effect : execution_effect -> execution_effect -> int
val equal_execution_effect : execution_effect -> execution_effect -> bool
type cause =
  1. | Illegal_schedule of {
    1. check : string;
    2. detail : string;
    }
  2. | Unsupported of {
    1. feature : string;
    2. detail : string;
    }
  3. | Resource_exceeded of {
    1. resource : resource;
    2. requested : int;
    3. limit : int option;
    4. detail : string;
    }
  4. | Backend_rejected of {
    1. backend : string;
    2. stage : string;
    3. severity : severity;
    4. detail : string;
    }
  5. | Unclassified of {
    1. phase : phase;
    2. exn_constructor : string;
    3. detail : string;
    }
  6. | Seed_evicted of {
    1. family : string;
    2. detail : string;
    }
    (*

    A detected seed site the search declined to propose because a candidate-volume cap bound (gh-ocannl-541): the site was reachable and ranked, and lost only to the cap. Recorded in the decline census so a previously-proposed site that stops being proposed leaves a signal instead of vanishing. family names the seed family (e.g. "split_reduce").

    *)
  7. | Not_dispatched of {
    1. origin : string;
    2. detail : string;
    }
    (*

    A candidate the search refused to run on a GPU backend because it binds no hardware dimension (gh-ocannl-532): the whole routine would execute in one work-item. Nothing is wrong with the candidate — the backend's execution model is what rejects it — but it is a decline like any other, and leaving it out of the census made a GPU search that timed one candidate indistinguishable from one whose candidates all failed (gh-ocannl-543). origin names where the refusal happened: "baseline" (the serial baseline), "candidate" (a compiled candidate that degenerated to a serial form), or "beam_move" (a menu move pruned before compile because it provably cannot parallelize an already unparallelized incumbent).

    *)
val sexp_of_cause : cause -> Sexplib0.Sexp.t
val equal_cause : cause -> cause -> bool
type rejection_key =
  1. | Illegal_schedule_key of string
  2. | Unsupported_key of string
  3. | Resource_exceeded_key of resource
  4. | Backend_rejected_key of string * string * severity
  5. | Unclassified_key of phase * string
  6. | Seed_evicted_key of string
  7. | Not_dispatched_key of string
val sexp_of_rejection_key : rejection_key -> Sexplib0.Sexp.t
val compare_rejection_key : rejection_key -> rejection_key -> int
val equal_rejection_key : rejection_key -> rejection_key -> bool
val key_of_cause : cause -> rejection_key
val detail_of_cause : cause -> string
val exception_of_cause : cause -> exn
type fatal = {
  1. exn : exn;
  2. backtrace : Stdlib.Printexc.raw_backtrace;
  3. phase : phase;
  4. candidate : string option;
}
type classified_cause = {
  1. phase : phase;
  2. cause : cause;
  3. execution_effect : execution_effect;
}

phase is where the failure was raised, not where the enclosing protect was installed: a narrow tag or a preserved cause reports its own phase, and a backend classifier's answer is pinned to the phase it was handed. This is what lets a report say whether a candidate died at link, at launch, or at sync.

val sexp_of_classified_cause : classified_cause -> Sexplib0.Sexp.t
val equal_classified_cause : classified_cause -> classified_cause -> bool
type failure =
  1. | Classified of classified_cause
  2. | Fatal of fatal
type 'a outcome = ('a, failure) Stdlib.Result.t
val fatal_of_classified : ?candidate:string -> classified_cause -> fatal

Escalates a classified rejection that cannot be contained after all — a launch failure whose execution effect is Writes_may_have_occurred, with no API to restore the damaged lineage. The cause is rendered into its public exception; the backtrace is the escalation site, since the original raise was already contained.

exception Cause_at of phase * cause
exception Raised_at of phase * exn * Stdlib.Printexc.raw_backtrace
type provenance =
  1. | Candidate
  2. | Cache_replay
  3. | Advisory
  4. | User_schedule
val sexp_of_provenance : provenance -> Sexplib0.Sexp.t
val compare_provenance : provenance -> provenance -> int
val equal_provenance : provenance -> provenance -> bool
val protect : ?strict:bool -> classify_backend:(phase -> exn -> classified_cause option) -> provenance:provenance -> phase:phase -> ?candidate:string -> (unit -> 'a) -> 'a outcome

Runs a phase boundary while preserving typed causes and raw backtraces. strict is exposed for policy tests; production callers should omit it and use strict_failure_classification.

val tag : phase -> (unit -> 'a) -> 'a

Tags an exception with the narrow phase where it was raised, preserving its raw backtrace. Existing typed transport exceptions pass through unchanged.

val raise_cause : cause -> _

Renders a typed internal cause using the exception contract of the existing public APIs.

val raise_failure : failure -> _

Re-raises a fatal failure with its original backtrace, or renders a classified cause.