Files
archie/docs/prds/self-update-transaction.md
T
sam e832b8ef0c docs(prds): normalise statuses and remove writing dated to its own day
Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
2026-09-22 00:38:35 +10:00

222 lines
13 KiB
Markdown

# 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" | "<exact-version-pin>"`
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.