Installer

Fields

This section documents version 4 of the protocol (_v is the constant "4"). Each message has its own table listing the payload’s field name, its JSON type, whether it is required, and what it means. Where a field only accepts a fixed set of values, the values are listed and explained under that field.

Message model

The Installer protocol puts the install verbs of dvi-cli on the wire. The resident agent is the consumer: it performs the operation and answers. There is no auth on the wire, ever; the CLI’s --auth-token is a CLI-only convenience.

Every message extends a base envelope, named by its x-base: JSON_Msg for a request, JSON_Ack for the acknowledgement, JSON_Eff for an effect. The base’s own fields, among them the ok verdict and the _cause back-reference of an ack, are documented on the JSON_Msg page and not repeated here. The message kind is inferred from which payload key is present.

Message Base Payload key dvi-cli Purpose

JSON_MsgDoInstall

JSON_Msg

do-install

i

Install a product from an install-spec.

JSON_MsgUninstall

JSON_Msg

un-install

ui

Uninstall an installed package, optionally with its user data.

JSON_MsgDoLoad

JSON_Msg

do-load

l

Load, that is run, an installed product.

JSON_MsgQueryInstall

JSON_Msg

query-install

qi, ql, qo

Query install state: installed, loaded or outdated.

JSON_AckInstall

JSON_Ack

ack

The one acknowledgement. Answers every request, and NACKs a failed outdated query.

JSON_EffQueryInstall

JSON_Eff

query-outdated

The effect that answers a successful outdated query.

State broadcasts, failure acks back: a request is answered by JSON_AckInstall, except a successful outdated query, which is answered by JSON_EffQueryInstall.

Each message is published under its own $id (under https://root-interface.se/protocols/Definitions/), named as in the table. The shared definitions _v and error live under the schema id installer.

Common to every message

Field Type Required Description

Installer

string

yes

The protocol version key: the constant "4". Every Installer message carries it, whatever its kind.

JSON_MsgDoInstall

Install a product. The payload carries the install signature under install-spec: the same install-spec the catalog carries, loosely bound. Its package, registry and pins express what dvi-cli spells as i <pkg> [--version|--tag] [--sha2]; no pins means the consumer’s platform channel.

The agent answers with JSON_AckInstall: the resolved install-ref, or ok: false plus a reason. The installed agent’s own heartbeat independently confirms it alive.

Fields of the do-install payload:

Field Type Required Description

install-spec

object

yes

An install-spec of the registry method. Validated against the InstallSpec schema, not here; see Related schemas.

JSON_MsgUninstall

Uninstall an installed package, as dvi-cli spells ui <pkg> [--version <x.y.z>] [--data]. The request goes over an install-ref; an absent version means all of the package’s versions, which are implicitly unloaded first.

There is no --everything on the wire, by design: removing IOI wholesale is a hands-on-the-machine act, not a message.

Fields of the un-install payload:

Field Type Required Description

installed

object

yes

An install-ref: the installed package. Absent version means all its versions.

data

boolean

no

Also remove the user data (--data).

JSON_MsgDoLoad

Load, that is run, an installed product, as dvi-cli spells l <pkg>. The request goes over an install-ref; an absent version means the installed one. For a self-contained IPSME agent this registers and starts it in the OS launcher. For a vendor app it launches the recorded program, one-shot: on Windows the DisplayIcon exe, on macOS the placed .app.

Answered by JSON_AckInstall: ok: true means loaded or launched, ok: false comes with an error. The counterpart read is JSON_MsgQueryInstall with q: loaded. Unload is its own affair.

Fields of the do-load payload:

Field Type Required Description

installed

object

yes

An install-ref: the installed package. Absent version means the installed one.

JSON_MsgQueryInstall

Query install state: the query verbs of dvi-cli on the wire, discriminated by q. The local queries, installed and loaded, go over an install-ref: what is there. The outdated query goes over the install signature itself: would this install-spec install something newer than what is installed? The same resolution rules as install decide the judging channel: the pins' exact versions, else the consumer’s platform dist-tag.

The query-install payload is a discriminated union on q:

q dvi-cli Goes over Answered by

installed

qi

an install-ref

JSON_AckInstall, with installed set to the installed version.

loaded

ql

an install-ref

JSON_AckInstall, whose ok is the answer: loaded means ok: true.

outdated

qo

an install-spec

JSON_EffQueryInstall on success; JSON_AckInstall with ok: false on failure.

Local state: installed, loaded

Field Type Required Description

q

string

yes

Which local query. One of:

  • installed: is it there, and at which version.

  • loaded: is it loaded.

installed

object

yes

An install-ref: the package to look at.

outdated

Field Type Required Description

q

string

yes

The constant outdated.

install-spec

object

yes

An install-spec of the registry method. The CLI-only conveniences, --tag as an arbitrary channel and a --registry override, do not travel: the signature is the channel and carries its own registry.

JSON_AckInstall

The Installer’s one ack. It answers JSON_MsgDoInstall, JSON_MsgUninstall, JSON_MsgDoLoad and JSON_MsgQueryInstall with q of installed or loaded, and it NACKs a failed outdated query. Causation rides in the base JSON_Ack’s `_cause; which request is being answered is read from there. The base’s ok flag is the verdict, and for a loaded query it is the answer.

A successful outdated query is answered by JSON_EffQueryInstall instead: state broadcasts, failure acks back.

Fields of the ack payload, on top of the base’s ok:

Field Type Required Description

installed

object

no

The install-ref that is there. For an install: the package plus the exact version the channel resolved, since the request’s signature may only have named a channel. For an installed query: the installed version.

error

error

no

Explains an ok: false. The whole object is absent on ok: true.

JSON_EffQueryInstall

Answers a successful outdated query with the staleness judgment as an effect: installed, the version that is there, against wanted, the exact version the signature’s channel resolves to. For a pinned signature that is the store’s blessing; for an unpinned one, the platform dist-tag. It is deliberately not latest: the signature may well want something older than what is installed.

The affordance is derived, never stated: a mismatch is installed differing from wanted, and its direction is relation, the agent’s semver comparison. The agent is the one semver arbiter; consumers never compare versions themselves. Which package is being judged is not duplicated here: the base’s _cause carries the original query-install, signature included. A failed outdated query NACKs back as JSON_AckInstall with ok: false instead.

Fields of the query-outdated payload:

Field Type Required Description

installed

string

no

The installed version. Absent means not installed.

wanted

string

yes

The exact version the signature’s channel resolves to at the registry now.

relation

integer

no

The sign of the agent’s semver comparison of installed against wanted. Present exactly when installed is: the relation to an absent thing is moot. One of:

  • -1: installed is older; an upgrade would move forward.

  • 0: the same version.

  • 1: installed is newer; the signature wants a downgrade.

error

The failure companion of the base JSON_Ack’s `ok flag. The whole object is absent on ok: true.

Field Type Required Description

code

integer

no

Machine-readable, mirroring the exit codes of dvi-cli. The schema does not enumerate it; the codes today:

  • 1: the operation failed.

  • 2: the healthy-negative class: not installed, nothing removed, outdated.

reason

string

no

A terse, human-readable why: a fail-closed pin mismatch, no pin for the consumer’s platform, registry unreachable, and so on.

Schema

{
  "$id": "https://root-interface.se/protocols/Definitions/Installer",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/installer": {
      "$id": "https://root-interface.se/protocols/Definitions/installer",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": {
          "const": "4"
        },
        "error": {
          "$comment": "the failure companion of the base JSON_Ack's ok flag -- the WHOLE object absent on ok:true: `code` = machine-readable, mirroring dvi-cli's exit codes (1 = the operation failed, 2 = the healthy-negative class: not installed / nothing removed / outdated), `reason` = terse human-readable why (fail-closed pin mismatch, no pin for the consumer's platform, registry unreachable, ...)",
          "type": "object",
          "properties": {
            "code": { "type": "integer" },
            "reason": { "type": "string" }
          }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/JSON_MsgDoInstall": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_MsgDoInstall",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "install a product -- the payload carries the SIG under `install-spec` (the same install-spec the catalog carries, loosely bound): pkg/registry/pins express what dvi-cli spells as `i <pkg> [--version|--tag] [--sha2]`; no pins = the consumer's platform channel. The resident agent is the consumer; it answers with JSON_AckInstall (the resolved ref, or ok:false + reason), and the installed agent's own heartbeat independently confirms it ALIVE. No auth on the wire, ever (--auth-token is a CLI-only convenience).",
      "type": "object",
      "required": [ "do-install", "Installer" ],
      "properties": {
        "do-install": { 
          "type": "object",
          "required": [ "install-spec" ],
          "properties": {
            "install-spec": { "$comment": "install-spec-registry", "type": "object" }
          }
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/Definitions/JSON_MsgUninstall": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_MsgUninstall",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "uninstall -- dvi-cli `ui <pkg> [--version <x.y.z>] [--data]`: an install-ref (the installed pkg; absent version = ALL its versions -- implicitly unloads first). NO `--everything` on the wire by design: removing IOI wholesale is a hands-on-the-machine act, not a message.",
      "type": "object",
      "required": [ "un-install", "Installer" ],
      "properties": {
        "un-install": {
          "type": "object",
          "required": [ "installed" ],
          "properties": {
            "installed": { "$comment": "install-ref", "type": "object" },
            "data": { "$comment": "also remove the user data (--data)", "type": "boolean" }
          }
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/Definitions/JSON_MsgDoLoad": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_MsgDoLoad",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "load (RUN) an installed product -- an install-ref (the installed pkg; absent version = the installed one). For a self-contained IPSME agent this REGISTERS + STARTS it in the OS launcher (dvi-cli `l <pkg>`); for a vendor app it LAUNCHES the recorded program (one-shot; win: the DisplayIcon exe, mac: the placed .app). Answered by JSON_AckInstall (ok:true = loaded/launched; ok:false + error). The counterpart READ is JSON_MsgQueryInstall q:loaded; unload is its own affair.",
      "type": "object",
      "required": [ "do-load", "Installer" ],
      "properties": {
        "do-load": {
          "type": "object",
          "required": [ "installed" ],
          "properties": {
            "installed": { "$comment": "install-ref", "type": "object" }
          }
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/Definitions/JSON_AckInstall": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_AckInstall",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "the Installer's ONE ack -- answers JSON_Msg{Do/Un}Install / JSON_MsgDoLoad AND JSON_MsgQueryInstall q:installed/loaded, and NACKS a failed q:outdated (causation rides in the base JSON_Ack's _cause; WHICH request is being answered is read from there). The base's ok flag IS the verdict -- for ql it IS the answer (loaded = ok:true). Optionally: `installed` = the install-ref that IS there (Do: pkg + the EXACT version the channel resolved -- the request's sig may only have named a channel; qi: the installed version); `error` {code, reason} explains an ok:false. (A SUCCESSFUL q:outdated is answered by JSON_EffQueryInstall instead -- state broadcasts, failure acks back.)",
      "type": "object",
      "required": [ "ack", "Installer" ],
      "properties": {
        "ack": {
          "type": "object",
          "properties": {
            "installed": { "$comment": "install-ref", "type": "object" }, 
            "error": { "$ref": "installer#/definitions/error" }
          }
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Ack"
    },
    "https://root-interface.se/protocols/Definitions/JSON_MsgQueryInstall": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_MsgQueryInstall",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "query install state -- dvi-cli's query verbs on the wire, discriminated by `q`: LOCAL queries (`installed` = qi, `loaded` = ql) go over an install-ref (what IS there); `outdated` (qo) goes over the SIG itself (would this install-spec install something newer than what's installed? -- the same resolution rules as install decide the judging channel: the pins' exact versions, else the consumer's platform dist-tag).",
      "type": "object",
      "required": [ "query-install", "Installer" ],
      "properties": {
        "query-install": {
          "oneOf": [
            {
              "$comment": "installed (qi) / loaded (ql): local state, over an install-ref",
              "type": "object",
              "required": [ "q", "installed" ],
              "properties": {
                "q": { "enum": [ "installed", "loaded" ] },
                "installed": { "$comment": "install-ref", "type": "object" }
              }
            },
            {
              "$comment": "outdated (qo): over the registry SIG (install-spec-registry). CLI-only conveniences (--tag as an arbitrary channel, --registry override) do NOT travel -- the sig IS the channel and carries its own registry.",
              "type": "object",
              "required": [ "q", "install-spec" ],
              "properties": {
                "q": { "const": "outdated" },
                "install-spec": { "$comment": "install-spec-registry", "type": "object" }
              }
            }
          ]
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Msg"
    },
    "https://root-interface.se/protocols/Definitions/JSON_EffQueryInstall": {
      "$id": "https://root-interface.se/protocols/Definitions/JSON_EffQueryInstall",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "answers a SUCCESSFUL JSON_MsgQueryInstall q:outdated: the staleness judgment as an EFFECT -- `installed` (the version that IS there; ABSENT = not installed) vs `wanted` (the exact version the sig's channel resolves to: the STORE's blessing for a pinned sig, the platform dist-tag for an unpinned one -- deliberately NOT `latest`: the sig may well want something older than what is installed). The affordance is DERIVED, never stated: mismatch = installed != wanted, and its DIRECTION is `relation` -- the arbiter's semver comparison (the ONE semver arbiter is the agent; consumers never compare versions themselves). WHICH pkg is being judged is NOT duplicated here (OAOO): the base's _cause carries the original query-install, sig included. A FAILED q:outdated (channel unresolvable, registry unreachable) NACKS back as JSON_AckInstall ok:false instead; installed/loaded queries are answered with JSON_AckInstall either way.",
      "type": "object",
      "required": [ "query-outdated", "Installer" ],
      "properties": {
        "query-outdated": {
          "type": "object",
          "required": [ "wanted" ],
          "properties": {
            "installed": { "$comment": "the installed version; ABSENT = not installed", "type": "string" },
            "wanted": { "$comment": "the exact version the sig's channel resolves to at the registry now", "type": "string" },
            "relation": { "$comment": "sign of the agent's semver compare of installed vs wanted: -1 installed older (an upgrade would move forward), 0 same, 1 installed newer (the sig wants a DOWNGRADE). PRESENT exactly when `installed` is -- the relation to an absent thing is moot", "enum": [ -1, 0, 1 ] }
          }
        },
        "Installer": { "$ref": "installer#/definitions/_v" }
      },
      "x-base": "JSON_Eff"
    }
  }
}

The payload objects are left opaque in this schema because iface-gen embeds one schema per header. Consumers validate them against their own schema.

Field Schema Shape

do-install.install-spec, query-install.install-spec

schema_InstallSpec

An install-spec of the registry method: how to get and verify a thing. The same spec the catalog carries in a product’s install-spec.

un-install.installed, do-load.installed, query-install.installed, ack.installed

schema_InstallSpec

An install-ref: the package name plus an optional exact version.

x-base

JSON_Msg

The base envelopes the messages extend: JSON_Msg, JSON_Ack and JSON_Eff.