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 |
|---|---|---|---|---|
|
|
|
|
Install a product from an install-spec. |
|
|
|
|
Uninstall an installed package, optionally with its user data. |
|
|
|
|
Load, that is run, an installed product. |
|
|
|
|
Query install state: installed, loaded or outdated. |
|
|
|
The one acknowledgement. Answers every request, and NACKs a failed outdated query. |
|
|
|
|
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 |
|---|---|---|---|
|
string |
yes |
The protocol version key: the constant |
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 |
|---|---|---|---|
|
object |
yes |
An install-spec of the |
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 |
|---|---|---|---|
|
object |
yes |
An install-ref: the installed package. Absent |
|
boolean |
no |
Also remove the user 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 |
|---|---|---|---|
|
object |
yes |
An install-ref: the installed package. Absent |
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 |
|---|---|---|---|
|
|
an install-ref |
JSON_AckInstall, with |
|
|
an install-ref |
JSON_AckInstall, whose |
|
|
an install-spec |
JSON_EffQueryInstall on success; JSON_AckInstall with |
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 |
|---|---|---|---|
|
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 |
|
no |
Explains an |
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 |
|---|---|---|---|
|
string |
no |
The installed version. Absent means not installed. |
|
string |
yes |
The exact version the signature’s channel resolves to at the registry now. |
|
integer |
no |
The sign of the agent’s semver comparison of
|
error
The failure companion of the base JSON_Ack’s `ok flag. The whole object is absent on ok: true.
| Field | Type | Required | Description |
|---|---|---|---|
|
integer |
no |
Machine-readable, mirroring the exit codes of
|
|
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"
}
}
}
Related schemas
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 |
|---|---|---|
|
An install-spec of the |
|
|
An install-ref: the package |
|
|
The base envelopes the messages extend: |