docs(UPGRADE): Meteor 3.1 + Mongo 7 REST smoke green; reproduce steps + remaining web-UI TODO

UPGRADE.md

@@ -1,4 +1,4 @@
-# Meteor upgrade — 1.6.1.1 → 2.x (→ 3.x blocked)
+# Meteor upgrade — 1.6.1.1 → 2.5 (Mongo 3.2) → 3.1 (Mongo 7, on `meteor3-wip`)
 
 Incremental, verified upgrade of `todos-contra-el-fuego-web`. Branch:
 `meteor3-upgrade` (base `tcef-master`). Local commits only — no push until
@@ -182,20 +182,57 @@ So **Meteor 2.5 is the highest release that runs against the production Mongo
 smoke byte-identical. Going past 2.5 (to 2.16 or 3.x) is gated on upgrading the
 shared rsmain replica set to Mongo ≥ 4.4 first — the same DB blocker as 3.x.
 
-## 🚧 3.x — blocked (do not run `meteor update --release 3.x`)
+## ✅ Meteor 3.1 + MongoDB 7 — REST smoke GREEN (branch `meteor3-wip`)
 
-Two independent blockers, both external/coordination:
+**The 3.x jump works end-to-end for the REST/Flutter contract.** On branch
-1. **MongoDB 3.2 → ≥ 4.4.** Meteor 3's driver requires it. Shared Comunes infra
+`meteor3-wip`, the web runs on **Meteor 3.1** (Node 22, async/await, no Fibers)
-   (rsmain) — coordinate the DB upgrade in a separate phase. This *also* gates
+against a **dockerized MongoDB 7** (npm-mongo 6.10 / mongodb driver 6), and the
-   Meteor 2.5+.
+REST smoke test is **byte-identical to the 1.6.1.1 baseline** (all 12 endpoints).
-2. **Notifications cutover.** The old notif code is already removed from this
+This is the "mongo superior" decision realized: give fuegos its own Mongo 7
-   branch; production must not run this build until `tcef-notifications` is
+instead of the shared rsmain 3.2 — which is what unblocks Meteor 3's driver.
-   emitting in prod.
 
-When Mongo is ≥ 4.4 and the notifications service is live in prod, the remaining
+`meteor3-upgrade` stays at the deployable **Meteor 2.5** (Mongo 3.2). The 3.x
-3.x work is: `meteor update --release 3.x`, finish the async/await migration of
+work lives on `meteor3-wip` until (a) production Mongo is migrated to 7 and
-server code (collections/methods/publications `*Async`, no Fibers), React 18
+(b) the web-UI async migration below is finished.
-render root, and re-run the smoke test.
+
+### Reproduce the 3.1 dev stack
+```bash
+docker run -d --name tcef-mongo7 -p 27019:27019 mongo:7 --replSet rs0 --port 27019 --bind_ip_all
+docker exec tcef-mongo7 mongosh --port 27019 --quiet --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"localhost:27019"}]})'
+# mark migrations current so historical (still-sync) up() bodies don't run:
+docker exec tcef-mongo7 mongosh --port 27019 fuegos --quiet --eval 'db.migrations.replaceOne({_id:"control"},{_id:"control",version:18,locked:false},{upsert:true})'
+export MONGO_URL="mongodb://localhost:27019/fuegos?replicaSet=rs0"
+export NODE_OPTIONS="--dns-result-order=ipv4first --no-network-family-autoselection"  # reach warehouse.meteor.com on Node 22
+meteor --settings settings-development.json --port 3100
+MONGO_CONTAINER=tcef-mongo7 MONGO_SHELL=mongosh MONGO_PORT=27019 ./smoke/smoke.sh
+```
+
+### Key build/runtime unblocks (Meteor 3.1)
+- **underscore linker crash** (`Runtime is not available … underscore`): resolved
+  `underscore@1.6.2` had a runtime-less `web.browser` unibuild → pin
+  **`underscore@1.6.4`** (diagnosed by instrumenting the tool's `linker.js`).
+- **collection2 v4** is fully lazy with no main module → import its eager entry
+  `meteor/aldeed:collection2/static.js` from `server|client/00-collection2-init.js`
+  so `attachSchema`/autoValues are patched before any collection loads.
+- **Fibers gone**: removed `fibers.js`; server sync Mongo → `*Async` throughout
+  (Rest.js + helpers + methods + startup: oauth/subsUnion/migrations/email/facts).
+- **vendored restivus** patched to `await` async endpoint handlers.
+- **`$near` + `countAsync()`**: driver 6 runs `count` via aggregation where
+  `$near` is illegal → derive total from `fetchAsync().length`.
+- **json-routes 3.0** matches routes in registration order → reordered the
+  `mobile/subscriptions/all/...` route before `.../:subsId` in Rest.js.
+- **fixtures.js / sitemaps.js** disabled (sync-only `@cleverbeagle/seeder` /
+  pre-0.9 `gadicohen:sitemaps`) — not on the REST path. Debt.
+
+### Still TODO before the web (not just REST) is fully deployable on 3.x
+- Web publications (`fireFromId`, `fireFromAlertId`, `falsePositivesMyloc`,
+  `industriesMyloc`) + remaining methods (comments, `subscriptions.remove`) →
+  `*Async` (not exercised by the smoke).
+- **React 16 → 18** render root + verify ancient react-* libs.
+- Re-enable dev fixtures / sitemaps / email default template with async ports.
+- SCSS `@import`→`@use`, `lighten`/`darken`→`color.adjust` (dart-sass deprecations).
+- **Production cutover** still needs: Mongo data migrated 3.2→7 (mongodump/restore),
+  the notifications service emitting in prod, and the Docker deployment (fase 3).
 
 ## Dependency debt (tracked, to resolve in the noted escala)