provisioning/schemas/catalog/context.ncl

# Component Context Schema
#
# Declares the ontological layer for a component as deployed in a specific infra.
# Used in infra component configs (e.g. infra/libre-wuji/components/zot.ncl).
#
# Three-layer identity:
#   what — what the component is (from the component manifest; override if needed)
#   how  — how it is deployed here (derived from the settings declared alongside)
#   why  — why it exists in this infra (intent declared by the operator)
#
# Plus governance dimensions that every component deployment must declare:
#   priority, security, supervision, updates.
#
# Usage in a component contract:
#   let Context = import "schemas/catalog/context.ncl" in
#   { MyComponent = { context | Context.ComponentContext | optional, ... } }
#
# Usage in an infra config:
#   context = {
#     how = "K8s Deployment with Hetzner CSI PVC, private Cilium gateway",
#     why = "Central OCI store for lian-build pipeline and cosign distribution",
#     priority = 'critical,
#     security  = { posture = 'private },
#     updates   = { policy = 'pinned, holds = ["cosign-verify"] },
#   }

{
  # ── Priority ────────────────────────────────────────────────────────────────
  # Operational priority of this component in this infra.
  # Drives incident response, update scheduling, and removal decisions.

  ComponentPriority = [|
    'critical,   # infra fails without it — immediate intervention required
    'essential,  # core services degraded without it
    'important,  # significant feature loss without it
    'standard,   # normal services, managed lifecycle
    'optional,   # convenience feature; removable without service impact
  |],

  # ── Security posture ────────────────────────────────────────────────────────

  SecurityPosture = [|
    'public,     # intentionally internet-facing; FIP or public gateway
    'private,    # private network only — VPN or private gateway required
    'internal,   # cluster-internal only; no gateway exposure
    'airgapped,  # no external network access whatsoever
  |],

  # ── Update policy ───────────────────────────────────────────────────────────

  UpdatePolicy = [|
    'pinned,         # manual only — every version bump requires explicit approval
    'semver-patch,   # auto-apply patch releases only (x.y.Z)
    'semver-minor,   # auto-apply minor and patch releases (x.Y.z)
    'rolling-latest, # always track latest — only acceptable for 'optional priority
  |],

  # ── Component Context ───────────────────────────────────────────────────────

  ComponentContext = {

    # Ontological triad — the three questions any operator must be able to answer
    # about any running component.

    what | String | doc "What this component is. Defaults to manifest.description; override when the deployment role narrows the description." | optional,

    how  | String
         | doc "How it is deployed in this infra — mode, storage, gateway, key integrations. Derived from the settings declared alongside this context block.",

    why  | String
         | doc "Why it exists in this infra — the purpose, the gap it fills, the service it enables.",

    # Governance dimensions

    priority | ComponentPriority
             | doc "Operational priority: drives response SLA, update scheduling, and removal policy."
             | default = 'standard,

    security | {
      posture  | SecurityPosture
               | doc "Network exposure posture for all endpoints."
               | default = 'internal,

      tls      | Bool
               | doc "TLS required on all exposed endpoints."
               | default = true,

      concerns | Array String
               | doc "Named security concerns to track — e.g. 'credential-rotation', 'access-policy-audit'."
               | default = [],
    } | default = {},

    supervision | {
      health_check | Bool
                   | doc "Active health check configured and expected to pass."
                   | default = true,

      metrics      | Bool
                   | doc "Prometheus-compatible metrics endpoint exposed."
                   | default = false,

      alerts       | Array String
                   | doc "Alert conditions configured — e.g. '5xx-rate', 'storage-capacity'."
                   | default = [],

      sla_target   | String
                   | doc "SLA availability target — e.g. '99.9%'. Informational."
                   | optional,
    } | default = {},

    updates | {
      policy | UpdatePolicy
             | doc "Version update policy for this component."
             | default = 'pinned,

      window | String
             | doc "Maintenance window — e.g. 'weekends UTC+0'. Informational for scheduling."
             | optional,

      holds  | Array String
             | doc "Gates required before update proceeds — e.g. 'cosign-verify', 'smoke-test', 'backup-verified'."
             | default = [],
    } | default = {},
  },
}