docs: UPGRADE.md — escalas 1.11/2.3, dead-package remediation, Mongo 3.2 ceiling, 3.x blockers

UPGRADE.md

@@ -78,14 +78,129 @@ resolves to `8.x`, which is too new for Meteor's 7-style helper layout — pin t
 
 REST smoke test: **byte-identical to baseline.** ✅
 
+### Escala 2 — 1.8.3 → 1.11 (version resolution only)
+
+```bash
+meteor update --release 1.11
+```
+
+Resolution reached 1.11 (`ecmascript` 0.14.3, `mongo` 1.10.0, `npm-mongo`
+**3.8.0** — still Mongo-3.2-compatible, `accounts-*` 1.x, `email` 2.0). But this
+release surfaced the two big blockers below. The app was ultimately driven to
+**2.3** (see next section); 1.11 was a transit point, not a landing.
+
+### Escala 3 — → Meteor 2.3  ✅ green (builds + runs against Mongo 3.2, smoke byte-identical)
+
+`.meteor/release = METEOR@2.3`. `npm-mongo` **3.9.0** (mongodb driver 3.x) — the
+last driver line that still speaks to a Mongo 3.2 server. Core bumps:
+`accounts-*` 2.0, `ecmascript` 0.15.2, `mongo` 1.12.0, HMR added.
+
+This escala was dominated by **dead Atmosphere packages** (the plan's #1 risk).
+Root causes and fixes, in the order they were hit:
+
+1. **`arkham:comments-ui` — no Meteor 2.x build.** The vendored local package
+   used `Npm.depends`, and rebuilding a *local* package's npm deps crashes
+   meteor-tool ≥1.11 on this host (`node_contextify.cc … Assertion
+   args[1]->IsString()` → SIGABRT; reproducible with any `Npm.depends`, even
+   `is-number`). Switching to the Atmosphere isopack avoided the local rebuild
+   but the package is abandoned: its newest 2.x-solvable version (0.2.15) pins
+   `accounts-password@1.0.1`, conflicting with Meteor 2.0's accounts-password 2.0.
+   **Decision (user-approved): reimplement comments as a small React feature**
+   (`imports/api/Comments/*`, `imports/ui/components/Comments/CommentsBox.js`),
+   dropping the package entirely. Fire-page comments only (the sole usage), with
+   likes/dislikes, image/YouTube embed, owner edit/remove, and the
+   "email other commenters" side-effect preserved. Comment text is now rendered
+   as **safe plain text** (+ media embed) instead of markdown-to-HTML — a small
+   scope reduction and a security improvement (no raw-HTML injection of user
+   content). The old local fork is preserved in its nested git repo
+   (commit `4761da9`).
+
+2. **`coffeescript@1.0.17` build plugin — crashes the build.** The same
+   `node_contextify` assertion fired at *build start* on this host whenever the
+   coffeescript compiler plugin loaded. It was pulled transitively by the dead
+   **test stack** (`meteortesting:mocha`, `practicalmeteor:chai`,
+   `xolvio:cleaner`) and by the old auto-downgraded `nimble:restivus@0.6.6`
+   (which needs `iron:router`). Removing those removed coffeescript and
+   unblocked the build. A trivial `meteor create` app builds fine on the same
+   tool, confirming the crash is package-specific, not a broken tool.
+
+3. **`nimble:restivus` — the REST API package — pins `accounts-password@1.3.3`**
+   (incompatible with 2.x) and is CoffeeScript (needs the crashing plugin).
+   **Vendored** as `packages/nimble-restivus`: the `.coffee` sources were
+   precompiled to plain JS (`lib/restivus-all.js`, single translation unit so
+   the `Auth`/`Route`/`Restivus` classes share scope; `Restivus` left
+   un-`var`'d so Meteor's `api.export` picks it up), and `package.js` loosens
+   `accounts-password` to 2.x and drops the coffeescript dependency. This also
+   let restivus resolve to 0.8.12 (json-routes based), which **removed the whole
+   `iron:router` stack**. REST behavior unchanged (smoke byte-identical).
+
+4. **`maximum:server-transform` (unused) removal** broke
+   `Meteor.publishTransformed` in `FalsePositives/server/publications.js`; no
+   transform was actually configured, so replaced with plain `Meteor.publish`.
+
+5. **`fourseven:scss` 4.5.4 → 4.14.1** — `node-sass@4.5.3` won't build on node 12
+   (Meteor ≥1.9); 4.14.1 uses a node-12-compatible node-sass with prebuilt
+   binaries. (Meteor 1.8 built it on node 8.) `4.15.0` needs ecmascript ≥ 0.15.1
+   → too new for 1.11.
+
+6. **`less`, `markdown` removed** — no `.less`/`.md` source files; their build
+   plugins were dead weight.
+
+### ⚠️ Local build-host caveat
+
+Meteor-tool's bundled node (12.x/14.x) SIGABRTs (`node_contextify` assertion) on
+this machine (kernel 6.12) when certain old build plugins load — this is an
+environment interaction, not a code defect (the deploy host built these fine
+historically). It was fully worked around by removing the dead build plugins
+above. If a future escala hits it again, build in a container matching the
+deploy target (Debian) rather than on this host.
+
+## Escala ceiling vs Mongo 3.2
+
+Meteor bumps the bundled `mongodb` Node driver to **4.x at Meteor 2.5**, which
+drops support for servers **< 3.6**. Production's rsmain is **Mongo 3.2**.
+Therefore the highest Meteor that can talk to the current production DB is
+**~2.4** (npm-mongo/driver 3.x). The smoke test runs against a real `mongo:3.2`,
+so the exact ceiling is verified empirically: it stays green through 2.3;
+2.5+ is expected to fail at connection time. **Landing target: highest 2.x that
+keeps the smoke test green against Mongo 3.2.**
+
+## 🚧 3.x — blocked (do not run `meteor update --release 3.x`)
+
+Two independent blockers, both external/coordination:
+1. **MongoDB 3.2 → ≥ 4.4.** Meteor 3's driver requires it. Shared Comunes infra
+   (rsmain) — coordinate the DB upgrade in a separate phase. This *also* gates
+   Meteor 2.5+.
+2. **Notifications cutover.** The old notif code is already removed from this
+   branch; production must not run this build until `tcef-notifications` is
+   emitting in prod.
+
+When Mongo is ≥ 4.4 and the notifications service is live in prod, the remaining
+3.x work is: `meteor update --release 3.x`, finish the async/await migration of
+server code (collections/methods/publications `*Async`, no Fibers), React 18
+render root, and re-run the smoke test.
+
 ## Dependency debt (tracked, to resolve in the noted escala)
 
 | Dep | From | Target | Status |
 |---|---|---|---|
-| React / react-dom | 16.0 | 18 | pending (escala 1.11) |
-| raven / flowkey:raven | 2.4 | @sentry/node + @sentry/react | pending — DSN off until GlitchTip/Sentry back |
+| React / react-dom | 16.0 | 18 | **debt** — deferred; ancient react-* libs (react-bootstrap 0.31, reactstrap 5-alpha, react-leaflet 1.8) break on 18. React 16 works through Meteor 2.x/3.x. Own front-end project. |
+| Server async/await | Fibers | `*Async` APIs | **pending** — prep for 3.x; 2.x still runs on Fibers so not yet required. |
+| raven / flowkey:raven | 2.4 | @sentry/node + @sentry/react | debt — DSN off until GlitchTip/Sentry back (sentry.comunes.org dead → harmless boot-log timeout noise) |
 | nodemailer | 4 | 6+ | pending |
-| Babel | 7 beta | 7 stable | pending (first escala that allows) |
-| i18next | 10 | current | evaluate cost; pin + note as debt if it breaks a lot |
-| Leaflet | 1.3.1 | current | evaluate cost; pin + note as debt if it breaks a lot |
+| Babel | 7 beta | 7 stable | ✅ done (escala 1) |
+| i18next | 10 | current | debt — pin; not on the critical path |
+| Leaflet | 1.3.1 | current | debt — pin; not on the critical path |
+| arkham:comments-ui | 1.4.x | — | ✅ replaced with in-repo React feature |
+| nimble:restivus | Atmosphere | vendored | ✅ local precompiled package, accounts-password 2.x |
+| maximum:server-transform, meteorhacks:zones, less, markdown, test stack | — | — | ✅ removed (dead/unused) |
+| fourseven:scss | 4.5.4 | 4.14.1 | ✅ node-12 compatible |
 | node-gcm | 1.0.2 | — | ✅ removed (dead API, moved to microservice) |
+
+### Comments React feature — verification note
+
+The server builds and the REST smoke test is green, and the client bundle
+compiles, but the comments UI itself is **not exercised by the smoke test**
+(it's not part of the Flutter REST contract). It needs manual staging
+verification: on a fire archive page — logged-in post/edit/remove, like/dislike,
+and image/YouTube embed.