docs(installer): record Phase 3 — the patch tier as built #92

wtclaude · 2026-08-05T00:59:25Z

wtclaude commented

2026-08-05 00:59:25 +00:00

What & why

The docs half of the installer's patch tier. PLAN.md gains a "Phase 3 as built" section, and the sections the implementation touched are brought in line with what shipped rather than left describing what was planned.

PLAN.md

§2.2.1 — the engine is fully native, and rung 1 no longer says git apply. §1 chose the release-tarball model precisely so there would be no git on the shard host, and rung 2 needs a native applier regardless; rung 1 keeps its stronger verdict and shares rung 2's write path. On the real files this is not academic — the shipped patches are CRLF while two of their three targets are LF, so git apply refuses patches the installer places correctly.

§7.0 documents patch_tier in the overlay manifest. Which patches form one unit, which companion follows which, whether a core rebuild is needed, and what declining costs are none of them derivable from a diff — so the release declares them, and adding a patch regenerates release metadata rather than requiring an installer release. That is the rule §7.1 already applies to the bundle.

§2.2 gains the pre-image cache (patches/originals/) and the widened patch cache — every patch the tier evaluated, not only those that applied, because the refusal message names that path as the file to apply by hand.

§2.2.1 gains the second, per-feature level of the all-or-nothing rule — the two vendor-sale patches are one unit, so a patch that could have been placed is held back when a sibling cannot be, and the run says that rather than reporting it applied.

INSTALL.md

The illustrated tier output is replaced with the real thing, copied from a live run — including that the line numbers shown are where each hunk was found in your file, not in stock ServUO.
The status banner now says install is complete; what remains is doctor/update/uninstall.
§3's path tables list patches/originals/, and the uninstall row points at it as the thing to diff a revert against.
Appendix A2 names the line-ending trap that makes git apply refuse a patch whose target region is visibly untouched — and says the installer's own tier does not have it.

How it was tested

Prose only. Every claim in the new "as built" section is one the paired PRs demonstrate: the rung-1 result on the real EventSink.cs, the byte-identical install.json across three runs, the refusal that writes nothing, and the two consent paths on a non-57.4 tree.

Paired with:

RunicGateway/installer#6 — the tier
RunicGateway/servuo-plugins#10 — the metadata §7.0 now documents

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why The docs half of the installer's patch tier. `PLAN.md` gains a **"Phase 3 as built"** section, and the sections the implementation touched are brought in line with what shipped rather than left describing what was planned. ### PLAN.md **§2.2.1 — the engine is fully native, and rung 1 no longer says `git apply`.** §1 chose the release-tarball model precisely so there would be **no git on the shard host**, and rung 2 needs a native applier regardless; rung 1 keeps its stronger verdict and shares rung 2's write path. On the real files this is not academic — the shipped patches are CRLF while two of their three targets are LF, so `git apply` refuses patches the installer places correctly. **§7.0 documents `patch_tier` in the overlay manifest.** Which patches form one unit, which companion follows which, whether a core rebuild is needed, and what declining costs are none of them derivable from a diff — so the release declares them, and adding a patch regenerates release metadata rather than requiring an installer release. That is the rule §7.1 already applies to the bundle. **§2.2 gains** the pre-image cache (`patches/originals/`) and the widened patch cache — every patch the tier *evaluated*, not only those that applied, because the refusal message names that path as the file to apply by hand. **§2.2.1 gains the second, per-feature level of the all-or-nothing rule** — the two vendor-sale patches are one unit, so a patch that *could* have been placed is held back when a sibling cannot be, and the run says that rather than reporting it applied. ### INSTALL.md - The illustrated tier output is replaced with **the real thing**, copied from a live run — including that the line numbers shown are where each hunk was found in *your* file, not in stock ServUO. - The status banner now says `install` is complete; what remains is `doctor`/`update`/`uninstall`. - §3's path tables list `patches/originals/`, and the uninstall row points at it as the thing to diff a revert against. - Appendix A2 names the **line-ending trap** that makes `git apply` refuse a patch whose target region is visibly untouched — and says the installer's own tier does not have it. ## How it was tested Prose only. Every claim in the new "as built" section is one the paired PRs demonstrate: the rung-1 result on the real `EventSink.cs`, the byte-identical `install.json` across three runs, the refusal that writes nothing, and the two consent paths on a non-57.4 tree. Paired with: - RunicGateway/installer#6 — the tier - RunicGateway/servuo-plugins#10 — the metadata §7.0 now documents ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-05 00:59:27 +00:00

docs(installer): record Phase 3 — the patch tier as built 42e6f3a0cb

PLAN.md gains a "Phase 3 as built" section covering the decisions the plan had
left open, and §2.2, §2.2.1 and §7.0 are brought in line with what shipped:

* The engine is fully native. §2.2.1 wrote rung 1 as "apply verbatim with
  git apply", but §1 chose the release tarball so there would be no git on the
  shard host, and rung 2 needs a native applier anyway. Rung 1 keeps its
  stronger verdict and shares rung 2's write path. On the real files this is
  not academic — the shipped patches are CRLF and two of their three targets
  are LF, so git apply refuses patches the installer places correctly.

* §7.0 documents `patch_tier` in the overlay manifest. Which patches form one
  unit, which companion follows which, whether a core rebuild is needed and
  what declining costs are not derivable from a diff, so the release declares
  them and adding a patch regenerates metadata rather than an installer.

* §2.2 gains the pre-image cache and the widened patch cache, and §2.2.1 gains
  the second, per-feature level of the all-or-nothing rule.

INSTALL.md's illustrated tier output is replaced with the real thing, the
status banner now says `install` is complete, §3's path tables list
patches/originals/, and Appendix A2 names the line-ending trap that makes
git apply refuse a patch whose region is visibly untouched.

Refs: RunicGateway/installer#6, RunicGateway/servuo-plugins#10

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/installer

2026-08-05 00:59:57 +00:00

feat(installer): implement Phase 3 — the patch tier #6

wtclaude referenced this pull request from RunicGateway/servuo-plugins

2026-08-05 01:00:14 +00:00

feat(patches): declare the patch tier in tier.json and the manifest #10

whitlocktech merged commit 706b450828 into main

2026-08-05 01:07:51 +00:00

whitlocktech deleted branch docs/installer-phase3

2026-08-05 01:07:51 +00:00

whitlocktech referenced this issue from a commit

2026-08-05 01:07:53 +00:00