From 9f94c3ffbe043e678fb37282e3b5778e6d9e17c5 Mon Sep 17 00:00:00 2001 From: jsboige Date: Sun, 12 Jul 2026 13:11:59 +0200 Subject: [PATCH] docs(dnn): refresh 3 runbooks post-execution (10.3.2+2sxc21 delivered full-IIS) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 3 #131/#132 runbooks were written Jun 15-25 as PRE-execution prep, before the migration was delivered. They now describe steps that have already happened (or carry an undocumented lesson that would bite a future executor). This refresh adds POST-EXECUTION REALITY banners + one targeted correctness addition — without rewriting the historical procedure (a valid record of the prep/reasoning). Changes (docs-only, 3 files, +85/-1): - 131-step1-sandbox-upgrade-runbook.md: POST-EXEC banner — marks the sandbox upgrade DELIVERED (10.3.2+2sxc21 live full-IIS, ACME bypass active), points to phase2-exec-rollback + MEMORY + UPGRADE-ASSESSMENT as current truth, flags 2 staleness items resolved (§2 "2sxc 15.02" was stale — already 21.07; §5 "templates untouched" moot — cliff crossed). - 131-regen-staging-runbook.md: REFRESH banner — scope DEFERRED 4-vs-8 lang RESOLVED (8-lang shipped #565, 41 SVGs), foreground-lock mitigated (#569 tscon recipe), Playwright deadlock resolved (#651), build-server deadlock lesson; points to regen-readiness-refresh-c1ed77d2 (#782) as the live harness. - 132-deployment-runbook.md: POST-EXEC banner (sandbox+full-IIS delivered, prod VPS go-live remains the gated frontier) + the critical B1-inversion lesson added to §5.5(a): 2sxc-21 REQUIRES .NET 8/9 BCL stack (Json 9.0.0.0/SCI 9.0.0.0/Bcl 8.0.0.0), NOT the 6.0.0.0 reversion the early repair-bin-net48.ps1 encoded. This was a real gap — the runbook predates the B1 incident and would have led a future executor to break 2sxc 21 with JsonOptions MissingMethodException. po-2023 lane (docs/dnn-localization/). Non-gated. No Cards/, no .cs, no DB. Gated ai-01 review before merge. Co-Authored-By: Claude-Code --- .../131-regen-staging-runbook.md | 23 +++++++++++ .../131-step1-sandbox-upgrade-runbook.md | 25 ++++++++++++ .../132-deployment-runbook.md | 38 ++++++++++++++++++- 3 files changed, 85 insertions(+), 1 deletion(-) diff --git a/docs/dnn-localization/131-regen-staging-runbook.md b/docs/dnn-localization/131-regen-staging-runbook.md index 99d9d3a8..995f05a0 100644 --- a/docs/dnn-localization/131-regen-staging-runbook.md +++ b/docs/dnn-localization/131-regen-staging-runbook.md @@ -9,6 +9,29 @@ run itself is a one-command affair — but it **launches nothing**. Per ai-01 di SECONDAIRE lane: "stager prérequis régén (sans lancer)". The **actual regen is GATED jsboige** (scope arbitration 4-vs-8 lang + Windows foreground-lock → run = jsboige RDP / ai-01 Opus, not the worker). +> ## 🔄 REFRESH (2026-07-12) — scope resolved, prereqs largely proven, see #782 for the live harness +> +> Two things this runbook **deferred as open** are now **closed**: +> - **§5 "scope DEFERRED — 4-lang vs 8-lang"** → **RESOLVED: 8 languages shipped** (PR #565, 41 SVGs across +> 8/8 langs via `git ls-tree`; byte-proven regen `Fallacies_zh.svg` 2026-06-24). When the print-bundle regen +> fires (post-GO-visuel jsboige), clobber **all 8** (`fr en ru pt es ar fa zh`) — scope option B is the live one. +> - **Foreground-lock blocker (§2)** → **mitigated**, not eliminated: PR #569 added the OS persistent-session +> recipe (`tscon /dest:console`) to keep the desktop foreground alive unattended. Freeplane headless +> is tracked (#568, open). The foreground-lock is a **fire-time condition**, not a code gap. +> +> **Two operational advances this doc predates** (honor at fire-time): +> - **Playwright/CardPen deadlock = RESOLVED (#651)** — console-flood sync I/O moved to a transport queue. The +> stall-watcher is reliable **provided it measures chromium **child** CPU, not parent-only** (parent-only +> false-kills legitimate heavy renders like Fallacies). +> - **`dotnet run` build-server deadlock** — can silently hang after cross-worktree builds; mitigation = +> `dotnet build-server shutdown` + explicit `dotnet build` + `dotnet run --no-build`. +> +> **This runbook remains valid for its staging structure** (FreeMind env var §2, Mode-isolation §3, harvest +> clobber §4, pre-flight §7). The **live, refreshed fire-time harness** — re-anchored to master `c1ed77d2` with +> the post-07-04 lessons — is +> [`../investigations/2026-07-11-regen-readiness-refresh-c1ed77d2.md`](../investigations/2026-07-11-regen-readiness-refresh-c1ed77d2.md) +> (PR #782 merged). Read that doc as the authoritative pre-regen gate; this runbook is its predecessor. + > **Scope-neutrality (HARD):** two scope options are on the table and **jsboige has not published the choice** > (ai-01: "4 cycles sans publication"). This doc describes prereqs that are **identical for both scopes** and > explicitly defers the one scope-dependent step (which language directories to clobber/regen) to the decision. diff --git a/docs/dnn-localization/131-step1-sandbox-upgrade-runbook.md b/docs/dnn-localization/131-step1-sandbox-upgrade-runbook.md index 6418ac76..d3e58108 100644 --- a/docs/dnn-localization/131-step1-sandbox-upgrade-runbook.md +++ b/docs/dnn-localization/131-step1-sandbox-upgrade-runbook.md @@ -6,6 +6,31 @@ **Base:** master `87a02c19` **Status:** **SANDBOX-PREP (research/runbook)** — execution GATED on jsboige's target decision (10.1.2 vs 10.3.2, see #520). **No prod deploy, no live sandbox mutation** until jsboige says go. +> ## ✅ POST-EXECUTION REALITY (refreshed 2026-07-12) — this prep doc's purpose was fulfilled +> +> The sandbox upgrade this runbook **prepared for** has been **executed and delivered**: DNN **10.3.2** + 2sxc +> **21.07** are live (full-IIS, `dnn.argumentum.myia.io`, HTTP 200/~85 KB, HTTPS SAN exp 2026-09-27). The +> 4-step staircase (9.11.1 → 9.13.10 → 10.2.0 → **10.3.2**) was completed on IIS Express :8090 (Phase B, +> 2026-06-28, jsboige GO), wizard automated via `wiz_runupgrade.ps1`, `dbo.[Version]` top row = 10.3.2. +> ACME bypass is **active in live** (`.well-known/acme-challenge/web.config`, renew win-acme 2026-08-23). +> +> **This doc is now a HISTORICAL prep record.** Read it for the staircase structure, pre-flight §3, and +> risk-register §5 reasoning. The **current source of truth** for state is: +> - [`131-dnn-phase2-exec-rollback.md`](131-dnn-phase2-exec-rollback.md) — the actual Phase B execution + rollback. +> - `MEMORY.md` §DNN — live state (runtime branch `dnn/sandbox-runtime-1032`, bin/ 330 files, B2.5 smoke GREEN). +> - [`../dnn/UPGRADE-ASSESSMENT.md`](../dnn/UPGRADE-ASSESSMENT.md) (#593) — corrected CVE + .NET 4.8 floor. +> +> **Two staleness items in the body below, now resolved** (do not act on them as written): +> - **§2 "2sxc 15.02"** — was STALE memory; 2sxc was **already 21.07.00** at Phase A boot. The 15.02 figure was +> a pre-export inference, corrected by the live manifest (`13-app60-resources.json`). +> - **§5 "2sxc stays 15.02 → templates untouched" (10.1.2 path)** — moot; target is 10.3.2, the cliff was crossed, +> and the 12-template audit + 2sxc-21 **BCL-stack alignment** were real work (see `132-deployment` §5.5 + the +> B1-inversion lesson: 2sxc-21 REQUIRES .NET 8/9 BCL Json 9.0.0.0/SCI 9.0.0.0/Bcl 8.0.0.0 — NOT the 6.0.0.0 +> reversion the early `repair-bin-net48.ps1` encoded; that thesis was inverted). +> +> **Remaining gated work** = prod go-live on the VPS (jsboige ops task), described in +> [`132-deployment-runbook.md`](132-deployment-runbook.md). + > ⚠️ **TARGET SUPERSEDED — jsboige decided 10.3.2 (decision #2, issue #458, 2026-06-18).** The 10.1.2 > target below is superseded; read > [131-target-revision-10.3.2-full-upgrade.md](131-target-revision-10.3.2-full-upgrade.md) as the source of diff --git a/docs/dnn-localization/132-deployment-runbook.md b/docs/dnn-localization/132-deployment-runbook.md index 0fe00907..a218f83c 100644 --- a/docs/dnn-localization/132-deployment-runbook.md +++ b/docs/dnn-localization/132-deployment-runbook.md @@ -8,6 +8,34 @@ upgrade, no go-live on production without jsboige's explicit go. This is the **go-live procedure**, distinct from the sandbox-upgrade procedure ([#522](131-step1-sandbox-upgrade-runbook.md)). +> ## 🟢 POST-EXECUTION REALITY (refreshed 2026-07-12) — sandbox + full-IIS delivered; prod VPS go-live remains +> +> Since this runbook was written (Jun 2026), the migration has been **executed and delivered up to full-IIS**: +> - **DNN 10.3.2 + 2sxc 21.07 LIVE** in full-IIS direct at `dnn.argumentum.myia.io` (HTTP 200/~85 KB, 0× +> "Something went wrong", HTTPS SAN 9D80D4CC exp 2026-09-27). Stopgap `dnn.myia.io` retiré, PortalAlias 1010 +> droppé. ACME bypass **active in live** (renew win-acme 2026-08-23). +> - The 4-step staircase (9.11.1 → 9.13.10 → 10.2.0 → 10.3.2) + the §5.5 cliff crossing were run on IIS Express +> :8090 (Phase B, 2026-06-28, jsboige GO). B2.5 smoke GREEN: homepage 200/86 KB, /Argumentum + /Règles render +> 2sxc content, 0 JsonOptions/conn-string errors. Runtime branch `dnn/sandbox-runtime-1032` (bin/ 330 files). +> +> **What this means for the runbook below:** the **6-phase structure, the rollback contract (§6), the runtime +> finding (.NET 4.8), and the honesty boundary (§7) remain the authoritative procedure for the one step still +> gated — **prod go-live on the VPS myia-web1** (jsboige ops task). The sandbox phases below are now a +> **proven replay** rather than a first-time plan. +> +> **ONE critical lesson this runbook predates — read before §5.5 (the cliff crossing):** +> - **2sxc-21 BCL-stack alignment (the "B1-inversion").** The earlier `repair-bin-net48.ps1` reverted BCL/SDK +> DLLs to 6.0.0.0, treating .NET 8/9 versions as "contamination." **That thesis was INVERTED for 2sxc 21**: +> 2sxc 21.07 is compiled against Json 9.0.0.0 / SCI 9.0.0.0 / Bcl 8.0.0.0. Reverting → `JsonOptions` type-init +> `MissingMethodException` → every 2sxc module "Something went really wrong in view.ascx". Fixed by deploying +> the matched BCL stack from the **2sxc 21.07 Install package** + aligning redirects. See +> [`682-field-model-revision-2sxc21.md`](682-field-model-revision-2sxc21.md) + MEMORY +> `reference-dnn-2sxc-net48-bcl-stack` for the authoritative version matrix. **§5.5(a) must include this +> BCL-stack step** — it is not optional on the prod path. +> +> **Remaining gated frontier:** prod VPS go-live (Phase 5 on myia-web1) + visual site verdict (jsboige/ai-01). +> This is a jsboige ops task, **de-coupled from the v0.9.0 print release** (worker reco). + > ## ⚠️ Target retarget — 10.1.2 → 10.3.2 (refreshed 2026-06-24) > > jsboige interactive decision **#2** (issue #458, 2026-06-18) chose the **full upgrade to @@ -170,8 +198,16 @@ This is the **net-new work** that 10.3.2 requires and 10.1.2 avoided. It is done then repeated on prod (Phase 5). The internals are in [131-2sxc-migration-plan.md]: - **(a) 2sxc 15.02 → 21.07 LTS** — install 2sxc 21 **before** the DNN upgrade crosses 10.2.0 - (else `DnnJsInclude` crashes IIS — the cliff). 2sxc content (`ToSic_EAV_*` + app tables) migrates + (else `DnnJsInclude` crashes IIS — the cliff). 2sxc content (`ToSIC_EAV_*` + app tables) migrates with the 2sxc installer, not the DNN wizard. + - **⚠️ MANDATORY sub-step (learned Phase B, the "B1-inversion"):** after installing 2sxc 21, **align the + BCL/SDK DLL stack** in `bin/` to what 2sxc 21.07 is compiled against — `System.Text.Json` **9.0.0.0**, + `System.Composition`/SCI **9.0.0.0**, `Microsoft.Extensions.*`/Bcl **8.0.0.0** — taken from the **2sxc 21.07 + Install package**. Do **NOT** let an earlier `repair-bin-net48.ps1`-style script revert these to 6.0.0.0 + (that was the inverted "decontamination" thesis — it breaks 2sxc 21 with `JsonOptions` type-init + `MissingMethodException` → every module "Something went really wrong in view.ascx"). Align the + `` redirects to match. Authoritative version matrix: MEMORY + `reference-dnn-2sxc-net48-bcl-stack` + [`682-field-model-revision-2sxc21.md`](682-field-model-revision-2sxc21.md). - **(b) 12-template audit** — migrate the custom Razor templates that 2sxc 21 no longer tolerates: `_FallacyExplorer_Root.cshtml` (`@inherits ToSic.Sxc.Dnn.RazorComponent` → `Custom.Hybrid.Razor14`), `_Parts.cshtml` (`@helper` → `@functions`, the one non-trivial step), + 10 others re-bind. Issue