felhom-controller/REPORT.md

REPORT — v0.257.0: the app catalog can speak English (R-560, slice 5 Part A)

2026-09-20 · main 60f0a86 · image gitea.dooplex.hu/admin/felhom-controller:0.257.0 · live on demo-hp guest 9201. MinAgent 0.131.0, unchanged.

What this release does

An app's customer-facing text lives in the catalog's .felhom.yml and was Hungarian only. This release lets the same file carry an English twin in an i18n: {en: …} sibling block, and makes the dashboard read it when the household is on English.

Architecture document read first and named here: felhom.eu/documentation/architecture/10-localisation.md — §1 (the Hungarian must not move), §4 (fallback), §5 (the gates), §7 (the catalog's copy model, which this release turns from a proposal into a measured fact), §11 ruling 7 (app names are not translated).

The five properties, and why each is load-bearing

1. For("hu") is the parsed struct with I18n cleared, and nothing else. Deep-compared against all 53 real catalog files, copied into internal/stacks/testdata/catalog/. LocalizeStacks returns the INPUT SLICE for Hungarian rather than a copy, so nothing on the Hungarian path is even touched. §1 holds by construction, then measured live.
2. Fallback is field by field, and blank counts as absent. A half-translated app is a legal, shippable state — that is what makes fifty apps pushable a batch at a time.
3. The three prose lists replace WHOLE; every other list is matched by its own key — env_var, option value, match_group, target, path. Position matching mistranslates silently the first time a Hungarian field is inserted above another, and the page still looks right.
4. For never writes through. The metadata is the stack manager's and is shared by concurrent requests; an in-place merge would put one household's language on another's page.
5. An older controller ignores the block. LoadMetadata uses non-strict yaml.Unmarshal — this repo constructs no yaml.Decoder at all, so there is no KnownFields anywhere to turn strict. Proven live below.

Where a page may read catalog copy

Four templates carry catalog copy — dashboard.html (the app rows' second line), stacks.html (the Apps list), app_info.html (the app page, including the data-folder cards) and deploy.html. A fifth, app_export.html, reads .Stack.Meta.Subdomain, which is configuration.

Five handler sites feed them, and each now goes through LocalizeStacks / LocalizeStackPtr / meta.For(lang): the dashboard, the Apps list, the deploy page, the app page — and the logs page, which today shows only the app's NAME and is routed through the same call anyway, because the next person to add a line to logs.html should not have to notice that this one page was the exception. Two producers sit in packages that have no request and therefore no language — the integration rows (internal/integrations) and the initial-credentials note (internal/stacks/initialcreds.go); both are re-taken from the localised metadata in the handler, identical bytes for Hungarian.

TestNoDirectMetaCopyReadOnPages parses every non-test file in internal/web and fails on any x.Meta.<copy-field> read that is not in a named, reasoned allow-list (three entries today, all appDetailHandler's localised found). What it cannot do, stated in the test: it reads source, so it cannot tell a localised receiver from an unlocalised one. It catches the ARRIVAL of a new copy read, which is when a human has to think — that is the whole claim made for it.

Tests, and the red-proofs

test	red-proof (each seen to fail, then reverted)
TestMetaForHuIsIdentity (53 real files)	a copy field mutated inside For's hu branch — FAILED naming 53 apps
TestDeployFieldsMatchedByKey	deploy fields matched by position — FAILED, "Second field" landed on FIRST
TestEmptyEnglishFallsBack	a blank English string allowed to win — FAILED
TestForDoesNotMutateTheReceiver	the defensive copy removed — FAILED, showing the written-through strings
TestOverlayMatches… (optional_config)	groups matched by position — FAILED
TestOverlayMatches… (integrations)	integrations matched by position — FAILED
TestOverlayMatches… (data paths)	data paths matched by position — FAILED
TestLocalizeStacksLeavesHungarianSliceAlone	I18n left on the value handed to the page — FAILED
TestNoDirectMetaCopyReadOnPages	_ = st.Meta.Description added to logsHandler — FAILED naming file and field

Two of the nine convicted a hollow TEST rather than the code, and that is the finding worth keeping.

• TestForDoesNotMutateTheReceiver first did the obvious thing: copy the struct, call For, DeepEqual the copy against the original. A struct copy shares its slices' backing arrays, so a write through out.DeployFields[i].Label changes BOTH sides and the compare passes. It passed a deliberately broken merge. It now snapshots the concrete strings before the call.
• The optional-config / integrations / data-path fixture first carried ONE entry per list. With one entry, position and key agree, and a position-matching implementation passes. It passed. The fixture now carries two entries per list with only the second translated.

Full suite, vet and build green; controller_gates.py green (17 gates).

Live proof — endpoint level, and that is stated because it matters

No browser exists on DooPlex. Every page was fetched with curl from inside guest 9201 at the controller's container address, with the customer Host header and a real logged-in session: the same handlers and the same templates a browser drives, with only the drawing skipped.

• demo-hp, 0.257.0. With the catalog pilot synced, /apps/privatebin, /apps/paperless-ngx, /apps/romm, /stacks and two deploy pages render the English catalog text on ?lang=en.
• The Hungarian did not move. The same seven pages in Hungarian, before and after the catalog push, are byte-identical apart from the per-session CSRF token: equal raw byte counts (43 253 / 41 532 / 41 547 / 147 121 / 74 326 / 70 290) and equal hashes once the token is normalised.
• demo-felhom, 0.255.0 — the old-controller check. With the block synced onto that box (confirmed positively: the sync named the three apps, and the block is in both the cache and the stack copy), its pages hash identically before and after, and its log carries no parse warning — in a 93-line window that contains the sync's own lines, so the absence is evidence and not a dead log.

Evidence: felhom.eu/documentation/audits/i18n-slice5-2026-09-20/.

What is still Hungarian on an English app page

Measured with an accent scan AND an ASCII-folded stem scan, both with a positive and a negative control. Three things, and the first is correct:

1. the language picker's own „Magyar" button — a picker names each language in its own tongue;
2. the update badge „Naprakész" and its tooltip — R-589. Slice 1 listed it (§2.3); slice 2 was the slice that was to take it, and closed without it;
3. the data-folder card's consequence sentence — R-590. This one makes a promise about the customer's files, and the label above it is already English, so the line reads half and half.

The Apps LIST also shows fifty Hungarian descriptions — those are the apps nobody has translated yet.

Gaps filed

R-589 (the update badge) · R-590 (the data-folder promise) · R-591 (Stack.Copy() deep-copies five Meta fields and not the new I18n map — safe today because nothing mutates an overlay, which is exactly why it is worth a row) · R-592 (three defects inside the new catalog gate, each found by its own decoy).

Needs the operator

Raise the fleet floor to 0.257.0. Until then only demo-hp can read an English app block at all; every other box keeps showing Hungarian app text to an English household. Nothing breaks if it waits.

Teardown

Nothing installed or removed on any box; no app deployed. Guest 9201 on demo-hp was restarted onto the new image, which is the deploy. The staged password file and the capture scripts were shredded from both Proxmox hosts and both guests. Both boxes left on Hungarian.