# schemas/lib/workflow.ncl — Workflow contracts
#
# A Workflow composes operations across components, modes, and layers.
# Each step targets one or more component operations (install, update, backup, ...).
# Workflows connect to: FSM dimensions, NATS events, backlog items, action log.
#
# Relationship to DAG:
#   dag.ncl      — L2 server provisioning (SSH, always install, server-bound)
#   workflows/   — L3 service lifecycle (cross-component, any operation, cross-mode)
#
# Usage:
#   let w = import "schemas/lib/workflow.ncl" in
#   { deploy_services | w.WorkflowDef = { id = "...", steps = [...] } }

# Target for a single workflow step — a (component, operation) pair with optional mode override
let _WorkflowStepTarget = {
  component | String,
  operation | String,
  mode      | [| 'taskserv, 'cluster, 'container |] | optional,
} in

# A single step in a workflow — may touch multiple components
let _WorkflowStep = {
  id         | String,
  targets    | Array _WorkflowStepTarget,
  depends_on | Array String | default = [],
  condition  | String | optional,
  on_error   | [| 'Stop, 'Rollback, 'Continue |] | default = 'Stop,
} in

# The structural definition of a workflow: ordered steps with rollback path
let _WorkflowDef = {
  id          | String,
  description | String,
  steps       | Array _WorkflowStep,
  rollback    | Array _WorkflowStep | default = [],
} in

# Operational metadata bundled with a workflow: authorization, NATS, FSM, backlog, triggers
let _WorkflowMetadata = {
  id          | String,
  name        | String,
  description | String,
  tags        | Array String | default = [],

  actors            | Array [| 'Developer, 'Agent, 'CI |] | default = ['Developer],
  requires_approval | Bool | default = false,

  fsm_dimension | String | optional,

  notifications | {
    subject_prefix | String,
    on_start       | Bool | default = true,
    on_step        | Bool | default = true,
    on_complete    | Bool | default = true,
    on_error       | Bool | default = true,
  } | optional,

  backlog_refs  | Array String | default = [],
  procedure_doc | String | optional,
  adr_refs      | Array String | default = [],

  triggers | {
    manual   | Bool | default = true,
    schedule | String | optional,
    on_event | String | optional,
  } | default = {},
} in

{
  WorkflowStepTarget = _WorkflowStepTarget,
  WorkflowStep       = _WorkflowStep,
  WorkflowDef        = _WorkflowDef,
  WorkflowMetadata   = _WorkflowMetadata,

  make_step     = fun data => _WorkflowStep     & data,
  make_workflow = fun data => data | _WorkflowDef,
}