Installer contract

The problem

A request comes from the shell, from the application, or from a remote authority. Someone is there to answer a question, or nobody is. The machine has nothing installed, or an installation K manages, or one mid-upgrade, or one that predates K, or one that cannot start. Only the shell can reach a machine whose application is down, and a repair, unlike an upgrade, cannot be rolled back. Most installers answer the common cells of that space and improvise the rest, and the improvised cells are where machines get stuck.

Three things the installer reads

Every run starts by reading three things, in this order, and acts only on what it read. Nothing else is guessed.

1. Presence, from the environment and the terminal. Attended means a person can be asked and can see the result. Decided once, before anything else: an explicit CI or *_NON_INTERACTIVE=1 means unattended; otherwise a terminal means attended: stdin or /dev/tty, the console on Windows. It decides who consents and whether anything is asked.
2. The world, from the installation on disk. Five of them: fresh, nothing installed; adopted, a binary installed before K; managed, a stable slot K keeps; upgrading, unfinished K work in the journal; broken, records K cannot read or cannot settle. Read after unfinished work is settled, so upgrading is never mistaken for anything else. It decides which action runs: install, adopt and upgrade, upgrade, or repair.
3. The product's answer, from the product itself, to two questions. Is a service running? Yes when a live process of the installed binary answers the probe, or at least exists. What must the user still do? A step such as "run app login", or nothing; set up means nothing. Asked after the world is read and before anything is stopped, and remembered on disk so recovery answers the same way. Running decides how the readback is taken; the next step decides what happens after an install and what the line says.

Who can do what, where

The interface

What a person or a script sees. Names are the reference implementation's; the shape is the contract.

curl -fsSL https://example.com/install.sh | sh                                # attended: resolve, show, ask
curl -fsSL https://example.com/install.sh | sh -s -- --channel alpha          # attended, another channel
CI=1 curl -fsSL https://example.com/install.sh | sh                           # unattended: the channel's current release, no questions
curl -fsSL https://example.com/install.sh | sh -s -- --version 2.3.0 --yes    # this version, no questions
curl -fsSL https://example.com/install.sh | sh -s -- repair --version 2.3.0 --yes   # only a broken machine accepts this
irm https://example.com/install.ps1 | iex                                     # Windows: the same, from PowerShell

Every run prints one line on stdout and exits 0, 1 or 2. What was settled first, if anything, goes to stderr. Details go to the receipt file, not the terminal.

The rules

Request

1. Every entry hands the installer the same request: an id, an exact version and recorded consent. It selects nothing else: no code, no commands, no URLs.
2. A channel is resolved to one version before anything changes, and the receipt records that version, never the channel. Attended, the person sees the version and answers; unattended, the channel's current release is the target and the invocation is the consent.
3. Every run has an operation id, and the same id with the same target replays the first receipt and touches nothing. The id is the installer's: a launcher that must be able to repeat a request names it through the environment, a person never sees it. A new attempt is a new id.

Presence

1. Presence is decided once, before anything else, as defined above. Nothing later re-decides it: a run that started attended may ask at any point, a run that started unattended never does.
2. An entry may collect consent attended and then run the installer unattended. self upgrade does exactly this: it asks in the application, then launches the same bootstrap non-interactively with the version and the consent in the request.
3. Unattended, nothing prompts. Running the installer is the consent to whatever the machine needs, repair included, and the receipt records who ran it and what was done; --yes only matters attended, where it skips the question. Putting the install directory on PATH is part of installing and happens either way; the line says so. Another manager's copy is never removed.

Lock and settle

1. One installer per state directory, under K's lock. Another live owner is held, exit 2. Liveness is decided by the lock protocol, never by age.
2. Every run finishes unfinished K work first, whatever was asked, and reports what it settled alongside its own outcome. This is recovery, not repair; it needs no network and no consent.
3. K's journal and receipts are its working memory for one transaction. Nothing outside that transaction depends on them, so they are never the user's problem: records K cannot read, or cannot settle, make the machine broken, and broken is repaired in the same run. A K that once wrote something a later K cannot read must not strand the machine, and there is no exit code for "come back later".

Worlds

1. After settling, the installer reads the machine once: a readable stable slot is managed; a service installed before K is adopted by seeding stable from its running executable; unresolved recovery, a corrupt slot or a dead lock owner is broken; nothing is fresh.
2. Managed and adopted are K's transaction, with rollback. Fresh is verify, seed stable, publish, self-check, then the product's first setup when attended: no transaction, no rollback, nothing to restore. Broken is repaired the same way, and the run says so.
3. An installation owned by another manager, such as a package manager, is held, exit 2. The line says where it is and how to remove it. The installer never removes it.
4. A target older than what is installed is held, exit 2, unless the request says the downgrade is intended. Refusing to downgrade is not success.

The product's answer

1. Running is read before anything is stopped, and remembered for recovery. A running service is stopped and must come back as a live service. A service that was not running is not started by an upgrade; the candidate is run for its version instead. The user's choice to have it stopped is kept.
2. The next step is read from the product without a running service, so it works on a machine nobody has logged into. Not set up and attended, a fresh install runs first setup and then starts. Not set up and unattended, nothing is started and the line names the step. An upgrade never runs first setup; it repeats the step if the product still names one.
3. First setup runs on the terminal, not on stdin: under curl | sh the shell has consumed the script by the time the installer runs, so stdin is at its end, and the product is given the terminal to ask on. A setup that is declined or fails leaves a usable installation, not a failed one.
4. Neither answer changes what is verified: bytes, platform, self-reported version, then a process of the new bytes. They change only which process answers, and what the line says.
5. The product's own commands are asked first, and the installer decides for itself when they are not enough. A service that does not answer but whose process exists counts as running. A stop that returns while the process lives is finished by the installer: terminate, wait, then kill. The rule is identity, not pid: a process is touched only when its executable is provably the installed binary, never by a bare pid or a name, and the receipt says it was done.

Verify

1. The release authority and the byte store are different trust domains. When both describe the target, their sha256 and size must agree before any download.
2. Bytes are verified against the manifest, after decompression if compressed, and again after staging. The staged executable must match the host platform and must report the requested version when asked. Any mismatch fails before any change, exit 1.
3. Downloads fail before anything changes; recovery needs none. Credentials for a private source come from the environment; attended, missing ones are asked for.

Repair

1. Repair is what a broken machine gets, and only a broken machine: a failed upgrade never escalates to it, and on a machine that can be upgraded a repair request is held. Attended, it is asked about once like any other action, naming what will be quarantined. Unattended, running the installer is the consent, as for everything else.
2. Settle first. Never under a live lock. Quarantine K's state by one atomic rename; delete nothing; never touch data outside the slots. An unresponsive service is stopped the same way as anywhere else: by the product's command, then by the installer, by identity.
3. Install and probe exactly as an upgrade would, then bootstrapStable, so the next upgrade is a normal transaction. No rollback; the receipt says repaired, never promoted, and names the quarantine, the version and the approver. What repair must keep is the normative repair boundary.

Report

1. Success is read back from a process of the new bytes, never inferred. An accepted request, a finished download, a replaced file: none of these is success.
2. What the readback reaches depends on what was running. A service that was running is stopped and must come back as a live service reporting the requested version, a pid and a new start id. Where nothing runs, because nobody has set the product up yet, the candidate itself is run and must answer as the requested version; every run is a new process, so the start id is new. The line says which: Upgraded 2.2.1 → 2.3.0. It is running. against Upgraded 2.2.1 → 2.3.0. Next: run app login.
3. Installed means usable, not running: the bytes are in place and answer as the version. Running is claimed only when the service was started and read back, after first setup or because it was running before. The product names the next step when there is one, and the line repeats it.
4. Every run ends in one printed line and one exit code: 0 upgraded, installed or up to date, 1 failed or rolled back, 2 not done. The line says what happened, what did not change, and what to do next, in the user's words.
5. The line is the same attended and unattended. Only who acts on it differs: a person, or the caller. The installer never retries the same target on its own.

What each outcome prints

The line is in the user's words. Slots, journals, receipts, operation ids and quarantines are how the installer works, not what it says; they live in the receipt file. A path is fine when the user may need it, such as where an old installation was kept.