122 lines
4.9 KiB
Text
122 lines
4.9 KiB
Text
# 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,
|
|
}
|