mesh-contracts/seats/node-service-manager/seat.json

{
  "format": 1,
  "seat": "node-service-manager",
  "scope": "node",
  "grain": "seat-list",
  "decision": "novox/hq ADR 0177",
  "verbs": [
    {
      "name": "units",
      "description": "The units the service manager knows in a scope, each with its load, active and sub state; narrowed to a pattern when asked.",
      "replaces": [
        "systemctl list-units"
      ],
      "input": {
        "properties": {
          "pattern": {
            "description": "a glob the unit's name must match (optional)",
            "type": "string"
          },
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "status",
      "description": "One unit as the service manager sees it now: its states, whether it starts at boot, its main process, and whether the mesh declares it.",
      "replaces": [
        "systemctl status",
        "systemctl is-active"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "start",
      "description": "Start one unit. For a unit the mesh declares, the answer says the host will restore what its declaration says at the next apply.",
      "replaces": [
        "systemctl start"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "stop",
      "description": "Stop one unit; for a mesh-declared unit the answer says the host will restore its declared state.",
      "replaces": [
        "systemctl stop"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "restart",
      "description": "Restart one unit.",
      "replaces": [
        "systemctl restart"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "enable",
      "description": "Make one unit start at boot (or at the account's login, in user scope).",
      "replaces": [
        "systemctl enable"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "disable",
      "description": "Stop one unit starting at boot (or at login, in user scope).",
      "replaces": [
        "systemctl disable"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "journal",
      "description": "The last lines of one unit's journal (at most 2000), in a time window and narrowed to a priority and to lines holding a text when asked. A secret the unit printed is shown as [redacted: \u003cwhat it was\u003e].",
      "replaces": [
        "journalctl"
      ],
      "input": {
        "properties": {
          "lines": {
            "description": "how many lines from the end of what matches (default 100, at most 2000)",
            "type": "string"
          },
          "match": {
            "description": "only the lines holding this text, as written — a fixed string, not a pattern (optional)",
            "type": "string"
          },
          "priority": {
            "description": "only entries this severe or more: 0-7 or emerg, alert, crit, err, warning, notice, info, debug (optional)",
            "type": "string"
          },
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "since": {
            "description": "the window's start: an RFC 3339 time (2026-10-07T09:30:00Z) or relative to now (-30min, -2h, yesterday) (optional)",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          },
          "until": {
            "description": "the window's end, in the same forms (optional; now when absent)",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "failed",
      "description": "Every failed unit on this machine, in the system manager and in the operator account's; a manager that does not answer is reported with its error, never as nothing failed.",
      "optional": true,
      "replaces": [
        "systemctl --failed"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" or \"user\": only that manager (both when absent)",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "reset-failed",
      "description": "Clear one unit's failed record in its manager — its failed state and its start-limit count — and answer its state after. It removes no file and starts nothing.",
      "replaces": [
        "systemctl reset-failed"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "wanted-by",
      "description": "What wants, requires or triggers one unit, read-only: the manager's reverse dependencies (WantedBy, RequiredBy, UpheldBy, BoundBy, TriggeredBy and the rest) and every enable link naming it in the scope's configuration directories (*.wants, *.requires, *.upholds), each with where it points and whether it dangles — the account's own directory included in user scope.",
      "replaces": [
        "systemctl list-dependencies --reverse",
        "systemctl show -p WantedBy",
        "ls ~/.config/systemd/user/*.wants"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      }
    },
    {
      "name": "unlink-dangling",
      "description": "Remove the dangling enable links named for one unit — links in a *.wants, *.requires or *.upholds directory of the account's or the machine's own configuration whose target does not exist, which `disable` leaves once the unit's file is gone — on the person's word: `why` is required. Each is recorded (its path, its target, the reason) before it is removed, and the manager reloaded; a link whose target exists, or one a package, a generator or the runtime placed, is left and said.",
      "replaces": [
        "rm ~/.config/systemd/user/*.wants/\u003cunit\u003e",
        "unlink /etc/systemd/system/*.wants/\u003cunit\u003e"
      ],
      "input": {
        "properties": {
          "scope": {
            "description": "\"system\" (the default) or \"user\": the operator account's own manager",
            "type": "string"
          },
          "unit": {
            "description": "the unit's name, as the service manager knows it",
            "type": "string"
          },
          "why": {
            "description": "the person's reason for removing the links, kept in the record",
            "type": "string"
          }
        },
        "required": [
          "unit",
          "why"
        ],
        "type": "object"
      }
    }
  ]
}