ontoref/reflection/schema.ncl

let _Dependency = {
  step      | String,
  kind      | [| 'Always, 'OnSuccess, 'OnFailure |] | default = 'Always,
  condition | String | optional,
} in

let _OnError = {
  strategy   | [| 'Stop, 'Continue, 'Retry, 'Fallback, 'Branch |],
  target     | String | optional,
  on_success | String | optional,
  max        | Number | default = 3,
  backoff_s  | Number | default = 5,
} in

# ── Guard ────────────────────────────────────────────────────────────────────
# Executable pre-flight check that runs BEFORE any step in the mode.
# If a guard fails, the mode prints the reason and aborts — preventing agents
# and humans from executing procedures that violate active constraints.
# Guards turn silent constraint violations into loud, early blocks.
#
# Pattern: Active Partner (#1 from Augmented Coding Patterns)
# "Explicitly grant permission and encourage AI to push back."
# Guards are the mechanism by which the protocol pushes back.
#
# cmd:    shell command that exits 0 = pass, non-zero = blocked
# reason: human-readable explanation shown when the guard blocks
# severity: 'Block aborts execution, 'Warn prints warning but continues
let _Guard = {
  id       | String,
  cmd      | String,
  reason   | String,
  severity | [| 'Block, 'Warn |] | default = 'Block,
} in

# ── Converge ─────────────────────────────────────────────────────────────────
# Post-execution convergence check for iterative modes.
# After all steps complete, the executor evaluates the condition command.
# If it exits non-zero, the mode re-executes (failed steps or all steps)
# up to max_iterations times.
#
# Pattern: Refinement Loop (#36 from Augmented Coding Patterns)
# "Each iteration removes a layer of noise, making the next layer visible."
#
# condition:      shell command — exit 0 = converged, non-zero = iterate again
# max_iterations: upper bound on re-execution cycles (prevents infinite loops)
# strategy:       'RetryFailed re-runs only steps that failed or were blocked;
#                 'RetryAll re-runs the entire DAG from scratch
let _Converge = {
  condition      | String,
  max_iterations | Number                          | default = 3,
  strategy       | [| 'RetryFailed, 'RetryAll |]   | default = 'RetryFailed,
} in

let _ActionStep = fun ActionContract => {
  id         | String,
  action     | ActionContract,
  depends_on | Array _Dependency | default = [],
  cmd        | String | optional,
  actor      | [| 'Human, 'Agent, 'Both |] | default = 'Both,
  on_error   | _OnError | default = { strategy = 'Stop },
  verify     | String | optional,
  note       | String | optional,
} in

let _ModeBase = fun ActionContract => {
  id             | String,
  trigger        | String,
  preconditions  | Array String | default = [],
  guards         | Array _Guard | default = [],
  steps          | Array (_ActionStep ActionContract),
  postconditions | Array String | default = [],
  converge       | _Converge | optional,
} in

# DAG-validated Mode contract:
#   1. structural contract via _ModeBase
#   2. step ID uniqueness within the mode
#   3. referential integrity — all depends_on.step reference an existing id
# Cycle detection is a separate Rust-side pass (ontoref-reflection::dag::validate).
let _Mode = fun ActionContract =>
  std.contract.custom (fun label value =>
    let validated = value | (_ModeBase ActionContract) in
    let steps     = validated.steps in
    let ids       = steps |> std.array.map (fun s => s.id) in

    let _after_unique = ids |> std.array.fold_left (fun acc id =>
      if std.record.has_field id acc.seen then
        std.contract.blame_with_message
          "Mode '%{validated.id}': duplicate step id '%{id}'"
          label
      else
        { seen = acc.seen & { "%{id}" = true }, ok = true }
    ) { seen = {}, ok = true } in

    let bad_refs = steps |> std.array.flat_map (fun step =>
      step.depends_on
        |> std.array.filter (fun dep =>
            !(ids |> std.array.any (fun i => i == dep.step))
          )
        |> std.array.map (fun dep =>
            "step '%{step.id}' depends_on unknown '%{dep.step}'"
          )
    ) in

    if std.array.length bad_refs > 0 then
      std.contract.blame_with_message
        "Mode '%{validated.id}' has invalid depends_on: %{std.string.join ", " bad_refs}"
        label
    else
      'Ok validated
  )
in

{
  Dependency  = _Dependency,
  OnError     = _OnError,
  Guard       = _Guard,
  Converge    = _Converge,
  ActionStep  = _ActionStep,
  Mode        = _Mode,
}