# Self-update: artifact install, topology migration, journaled transaction **Status:** Draft Epic: `archie-core-hj1t` / GitHub `#804` ("[EPIC] Self-update: artifact install, topology migration, journaled transaction"). The update *contract* (`internal/releaseupdate`: `Catalog.Check`, `Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by this document — it stays a thin Go interface shelling out to `CommandCatalog`/`CommandInstaller`. This document decides what the reference adapter scripts (`scripts/archie-update-{check,install,watchdog}`) and `install.sh` do behind that contract, and settles the one thing the epic's own description got wrong: the dist-zip **is** already attached to GitHub Releases (`.github/workflows/deploy.yml`, `gh release upload`), not Actions-artifact-only. Artifact install is therefore a smaller change than the epic assumed — pointing the installer at an existing asset, not standing up new CI publishing. Topology migration and the journaled transaction are genuinely greenfield: no topology-detection or transaction-journal code exists anywhere in the tree. Out of scope: rewriting the `internal/releaseupdate` Go interfaces themselves, and any UI for triggering updates (channel dispatch, e.g. Telegram `/update`, is unaffected — this only changes what happens once an install is triggered). ## Problem `scripts/archie-update-install:139-160` clones and compiles from source on every update — the only path that exists. `deploy.yml` already publishes a per-platform archive plus (implicitly) checksums as a release asset, so the script not using it is a missed-reuse gap, not a missing-CI gap. `install.sh:414-445` writes only `archied.service` while every shipped deployment profile (`deployments/*.toml`) declares `[services.state]` and `[services.gateway]` sections needing their own units — a fresh install already reproduces the broken single-unit shape `deployment_contract_test.go` doesn't even catch, because that test only checks profile syntax, not installed topology. No code anywhere enumerates which systemd units exist on a host or compares that against what a release requires — the daemon fails at `bootstrap.go`'s `[services.state].target` check with no prior diagnosis. The self-refresh trap is confirmed at `scripts/archie-update-install:195-199`: new adapter copies land on disk but bash keeps executing the in-memory copy, so a pre-flight check added to the script only protects the *next* update. ## Design ### Artifact install (`#804` item 1) **Decision.** `CommandInstaller`'s default script downloads the per-platform archive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check` resolved (the same release `deploy.yml` already publishes to), verifies the checksum, and stages it — it does not clone/compile. Source build (`scripts/archie-update-install`'s current clone+compile body) is kept as an opt-in path selected by an explicit `--from-source` flag or `ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on every-host update is strictly slower and has a larger failure surface than downloading a signed asset that CI already produced. **Call site.** `scripts/archie-update-install` — replace the clone+compile body with a download-and-verify step; move the existing clone+compile body behind the opt-in flag rather than deleting it. `internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged — it already just shells out. **Reuse check.** `deploy.yml` already builds and publishes the archive and uploads it as both an Actions artifact and a release asset; no new CI work is needed, only pointing the installer at what exists. **Testing.** Checksum-verification logic is a shell function, testable with a fixture archive + `SHA256SUMS` pair — add to whatever test harness already covers `scripts/`. Full download-from-real-release is a manual smoke command (document the exact `archie-update-check`/`--dry-run` invocation once built), not `task check`. ### Topology migration (`#804` item 2) **Decision.** Add a topology *observer* to the daemon, not the shell adapter — CLAUDE.md's own "known trap" note says the shell copy is defence in depth only, and the daemon is what "knows the deployment and holds the approved snapshot." The observer inspects which systemd user units exist (`systemctl --user list-unit-files 'archie*.service'` or equivalent) and which config sections are present (`[services.state]`, `[services.gateway]`, UI service config), producing an `ObservedTopology` value with one field per unit: present/absent, and the config sections backing it. Each release's `release.json` (already produced by `deploy.yml` per the artifact-install work above) gains a `required_topology` field naming the units and config sections that release's binaries need. `Catalog.Check` compares observed against required; when the release needs a unit the host doesn't have, the result is not an error — it's a `MigrationPlan` value naming exactly which units and config blocks must be created and in what order (state store → gateway → UI → daemon, per CLAUDE.md's process boundaries), which the installer must apply before installing binaries, or refuse with that plan printed to the operator. **Call site.** New topology-observation code lives in `internal/app/archied/` next to `bootstrap.go` (which already owns the `[services.state]`/`[services.gateway]` checks this reuses), not in `internal/releaseupdate` — the update package consumes the daemon's observation, it doesn't reimplement config parsing. `install.sh:414-445` reads the same `required_topology` declaration (from whichever profile the operator selected) so first-install and self-update stop diverging — this is the fix for the "three docs describe four units, install.sh writes one" gap: one topology source of truth, consumed by both entry points. `deployment_contract_test.go` gains an assertion that each shipped profile's declared topology matches the units `install.sh` would create for it. **Failure mapping.** | condition | contract error | |---|---| | observed topology cannot be determined (systemctl unavailable, non-systemd host) | refuse with "topology unknown" plan naming the manual steps, never guess | | required units missing, migration plan derivable | apply plan before binary install, in dependency order | | required units missing, no derivable plan (e.g. conflicting existing unit) | refuse, print the plan, do not proceed | **Testing.** `ObservedTopology`/`MigrationPlan` comparison logic is pure — table-driven unit tests belong in `task check`. Actual `systemctl` inspection needs a real systemd host; manual smoke test only. ### Journaled transaction (`#804` item 3) **Decision.** Replace `archie-update-install`'s copy-and-trap body with: (1) pre-flight (the existing check, kept), (2) write an intent journal to a path outside every directory the install touches — e.g. `${XDG_STATE_HOME:-~/.local/state}/archie/update.journal` — recording the candidate version, the topology plan (if any), and each binary's current-and-candidate path before touching anything; (3) stage each new binary under a `.new` suffix in the same directory as the live binary, then atomically rename over the live path (`rename(2)` is atomic on the same filesystem — this replaces whatever non-atomic copy the current script uses) rather than overwriting in place; (4) run each replaced binary's existing health/ready check (the same checks `internal/domain/health` already exposes per the health registry pattern, not a new one) against the *candidate*, not a hardcoded default port/binary; (5) hold the process open for a bounded observation window (e.g. 120s) watching for crash-loop before declaring success; (6) on any failure at any stage, roll back using the journal: restore prior binaries via the same atomic rename, restore prior unit files and config if the topology-migration step touched them, and delete the journal only on confirmed rollback completion; (7) on daemon boot, check for a journal file and resume rollback if one exists uncommitted (crash-during -update recovery). A single-writer lock (`flock` on a lock file outside the replaced paths, e.g. next to the journal) prevents two concurrent updates. **Call site.** `scripts/archie-update-install` (journal write, stage-then -rename, lock acquisition), `internal/releaseupdate` package (health-check invocation reusing whatever the health registry already exposes — cite the concrete symbol once located, do not add a second health-check mechanism), and `internal/app/archied` startup (resume-on-boot journal check, next to existing bootstrap sequencing). **Failure mapping.** | condition | contract error | |---|---| | lock held by another update | refuse immediately, name the holder's PID/journal | | health check fails post-switch | automatic rollback within the observation window, journal records the failure reason | | crash mid-transaction, journal present at boot | daemon completes rollback before normal startup, logs it | **Testing.** Stage-then-rename and rollback logic against a fixture directory tree is fully fakeable — `task check`. Real systemd unit start/stop as part of rollback needs a real host; manual smoke command. ### Channel, pinning, automation (`#804` item 4) **Decision.** Add `channel = "stable" | "next" | ""` to whatever config section already governs update behavior (next to `ARCHIE_UPDATE_CHANNEL`'s existing chat-channel field in `internal/releaseupdate/command.go` — name this new field distinctly, e.g. `ReleaseChannel`, to avoid colliding with the existing chat-notification channel of the same word). `Catalog.Check` filters candidate releases by this field before returning the newest match. Runtime image pinning: every shipped profile already pins by digest (`deployments/*.toml` confirmed), so the remaining gap is `scripts/archie-update-install`'s fallback default — it must read the digest from the active profile's config rather than falling back to `:latest` when none is configured; refuse the update (don't silently pull `:latest`) if no digest is resolvable and the profile requires a pinned image. Opt-in auto-update refuses to start when the daemon reports work in flight (reuse whatever "tasks running" signal the daemon already exposes for graceful shutdown — do not add a second in-flight tracker). **Call site.** `internal/config/config.go` (new `ReleaseChannel` field), `internal/releaseupdate` (`Catalog.Check` filtering), `scripts/archie-update-install` (digest resolution, remove `:latest` fallback), daemon shutdown/drain signal (reuse for the auto-update in-flight check). **Testing.** Channel filtering is pure — `task check`. Digest-refusal path is a shell-script unit test against a fixture profile. ## Call site inventory | concern | file | change | |---|---|---| | Update contract (Catalog/Installer interfaces) | `internal/releaseupdate/service.go` | none — already handles this | | Command adapters | `internal/releaseupdate/command.go` | new `ReleaseChannel` field distinct from existing chat-channel field | | Install script body | `scripts/archie-update-install:139-160,170,195-199` | replace clone+compile default with download+verify; add journal, lock, stage-then-rename, digest check | | CI release publishing | `.github/workflows/deploy.yml` | none — already handles this | | Deployment profiles | `deployments/*.toml` | none — already digest-pinned | | First-install unit creation | `install.sh:414-445` | change — consume shared topology declaration | | Topology assertions | `deployment_contract_test.go` | new assertion: profile topology matches install.sh output | | Topology observation | `internal/app/archied/bootstrap.go` (new sibling code) | new | | Resume-on-boot rollback | `internal/app/archied` startup | new | | Health check reuse for candidate verification | `internal/domain/health` | reuse — confirm exact symbol before implementing | ## Execution: multi-agent team breakdown | sub-feature | issue | implementer scope | suggested council lenses | why | |---|---|---|---|---| | Artifact install | item 1 (file if unfiled) | `archie-update-install` download+verify, opt-in source-build flag | `lens-deletionist` | must not leave the clone+compile path as silent default cruft | | Topology migration | item 2 (file if unfiled) | daemon-side observer, `release.json` schema, `install.sh` consumption, contract test | `lens-boundary`, `lens-operator` | boundary: observation belongs in daemon not shell; operator: refusal-with-plan is the whole safety property | | Journaled transaction | item 3 (file if unfiled) | journal format, stage-then-rename, lock, resume-on-boot | `lens-operator`, `lens-maintainer` | operator: crash-mid-update is the core failure mode; maintainer: someone must be able to read a journal file during an incident | | Channel/pinning/automation | item 4 (file if unfiled) | config field, catalog filtering, digest refusal, in-flight guard | `lens-contract` | digest-refusal changes what a config value is allowed to resolve to | ## File and link the beads - The epic's four numbered work items are not yet individual child beads — file one bead per item above, each linking to its matching `##` heading here instead of restating the design, with acceptance criteria drawn from this doc's failure-mapping tables. - Add the suggested lenses to each new issue.