provisioning/schemas/lib/integration_mode_manifest.ncl

# schemas/lib/integration_mode_manifest.ncl
#
# Integration Mode manifest schema for the federated integration-modes protocol.
# Each participant project declares an IntegrationMode in its own reflection/modes/.
#
# Invariants enforced at contract evaluation time:
#   1. kind must be 'integration (not 'standard — prevents mode files landing in wrong catalog)
#   2. domains_used must be non-empty (every integration mode must declare its domain deps)
#   3. direction='bidirectional requires at least one step with id starting "report-"
#   4. direction='event_emitter requires at least one step with id starting "emit-"
#   5. All step depends_on references resolve to existing step ids (inherited from ontoref pattern)
#
# Embedding rationale: ontoref v0.1.0 has no domain command group and no OCI surface.
# This schema is a local embedded subset; upstreaming is deferred per ADR-042.

let oci = import "./integration/oci_artifact_format.ncl" in

let _direction = [| 'inbound, 'outbound, 'bidirectional, 'event_emitter |] in

# Typed reference to a domain artifact in the OCI registry.
let _DomainRef = {
  id      | String
          | doc "Domain identifier — must match the id in the DomainArtifact pushed to the registry",
  version | String
          | doc "Semver constraint, e.g. '>=0.1.0, <0.2.0'",
  registry | String | optional
           | doc "Override registry base; defaults to reg.librecloud.online/domains",
} in

let _Dependency = {
  step | String,
} in

let _OnError = {
  strategy | [| 'Stop, 'Continue, 'Retry |] | default = 'Stop,
} in

# A single step in an integration mode. Extends ontoref _ActionStep with an
# optional invocation descriptor (absent for manual/human steps).
let _IntegrationStep = {
  id         | String,
  action     | String,
  depends_on | Array _Dependency | default = [],
  actor      | [| 'Human, 'Agent, 'Both |] | default = 'Agent,
  invocation | oci.Invocation | optional
             | doc "How to invoke the step binary. Absent for human-only steps.",
  on_error   | _OnError | default = { strategy = 'Stop },
  verify     | String | optional,
  note       | String | optional,
} in

# Base shape validated before cross-field checks.
let _IntegrationModeBase = {
  id           | String,
  kind         | [| 'integration |],
  direction    | _direction,
  trigger      | String,
  participant  | String
              | doc "Project/workspace that owns this mode — e.g. 'lian-build'",
  domains_used | Array _DomainRef,
  steps        | Array _IntegrationStep,
  preconditions  | Array String | default = [],
  postconditions | Array String | default = [],
  description    | String | optional,
} in

# Full contract: structural + cross-field invariants.
let _IntegrationMode =
  std.contract.custom (fun label value =>
    let validated = value | _IntegrationModeBase in
    let steps     = validated.steps in
    let ids       = steps |> std.array.map (fun s => s.id) 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

    # Uniqueness accumulator — folds to a record of seen ids, blames on duplicate.
    let unique_acc = ids |> std.array.fold_left (fun acc id =>
      if std.record.has_field id acc.seen then
        std.contract.blame_with_message
          "IntegrationMode '%{validated.id}': duplicate step id '%{id}'"
          label
      else
        { seen = acc.seen & { "%{id}" = true }, ok = true }
    ) { seen = {}, ok = true } in

    if std.array.length validated.domains_used == 0 then
      std.contract.blame_with_message
        "IntegrationMode '%{validated.id}': domains_used must be non-empty — declare every domain this mode depends on"
        label
    else if validated.direction == 'bidirectional
         && !(ids |> std.array.any (fun i => std.string.is_match "^report-" i)) then
      std.contract.blame_with_message
        "IntegrationMode '%{validated.id}' direction=bidirectional: requires at least one step with id starting 'report-'"
        label
    else if validated.direction == 'event_emitter
         && !(ids |> std.array.any (fun i => std.string.is_match "^emit-" i)) then
      std.contract.blame_with_message
        "IntegrationMode '%{validated.id}' direction=event_emitter: requires at least one step with id starting 'emit-'"
        label
    else if std.array.length bad_refs > 0 then
      std.contract.blame_with_message
        "IntegrationMode '%{validated.id}' has invalid depends_on: %{std.string.join ", " bad_refs}"
        label
    else
      # Force uniqueness check evaluation before returning.
      let _ = unique_acc in
      'Ok validated
  ) in

{
  DomainRef       = _DomainRef,
  IntegrationStep = _IntegrationStep,
  IntegrationMode = _IntegrationMode,
}