11 KiB
11 KiB
Plan — engine stopped: audit fixes on 0279953 (bugfix, branch feature/rust-r3-anatomy-core)
Context
Commit 0279953 added CoreRuntime.stopped (recovery cap 3 spent), coreStopped(), coreFailureMessage(t)
(apps/app/src/core/failure.ts), canvas failure engine_stopped, key core.stopped ("reload the page, your
report is kept in this tab"). Independent audit found:
- A.
core.stoppedignoresreportStore.saveFailed(set by the draft mirror when sessionStorage refuses a write, reportStore.ts:392-396, shown as bannereditor.save_failed"Exportez le PDF pour les conserver", EditorRoute.tsx:303). Once stopped, export needs the core (pdf/export.ts:37index.ops.snapshot) → impossible. Reload restores the last successful write → edits since the refused write lost, unannounced. - B. Surfaces still offering a retry that cannot work once stopped: CoreUnavailable (EditorRoute.tsx:257,
sheet.retry→ runtime.retry() returns false at cap), export catch (editor.export_failed"Réessayez"), import (home.import.error_core_unavailable"Réessayez l'import"), NewReportRoute.tsx:55 (sheet.core_unavailable). AlsoreleaseUnreadSession(reportStore.ts:248-262) returns false on a core failure, so initReport / hydrateImport return HELD and the pages saysession.held_blocked(wrong cause). - C. Canvas "Réessayer" (AnatomyCanvas.tsx ~145) only bumps
attempt(rebuild), never callscoreRuntime().retry(): after a failed recovery below the cap (state unavailable, stopped false) it is a dead end. - D. Stale comment core/sheetOps.ts:17; test gaps (default cap 3 unpinned, failed recovery below/at cap, no census of call sites, no stopped+saveFailed test).
Owner choices (AskUserQuestion 2026-10-15):
- stopped + save failed → variant message
core.stopped_unsaved+ "Télécharger une copie" button writing the IN-MEMORY report as JSON, no core (rescue copy; not importable today, import reads PDFs only). FR: « Le moteur de calcul de Faunosteo s'est arrêté après plusieurs erreurs, et l'espace de stockage de cet onglet est plein : vos dernières modifications ne sont pas enregistrées et seraient perdues en rechargeant la page. Téléchargez une copie avant de recharger. » EN: "Faunosteo's computation engine stopped after several errors, and this tab's storage is full: your latest changes are not saved and would be lost if you reload the page. Download a copy before reloading." core.stoppedwording: "plusieurs erreurs successives" → "plusieurs erreurs" (EN "several successive errors" → "several errors"); rest unchanged.- "Recharger la page" button (new key
core.reload, FR « Recharger la page », EN "Reload the page") on the stopped notice ONLY when the save is fine; never in the unsaved variant.
Fix plan (rev 2, after 3 challengers)
- packages/core-wasm/src/runtime.ts —
a. Self-restart after a failed recovery (closes C everywhere, not only on the canvas):
restartable=state === 'unavailable' && !stopped && generation > 0(an instance ran before: a failed recovery or a failed restart; a failed FIRST load stays on useSheet's explicit retry).ready()on a restartable runtime returnsthis.retry()(awaits the restart); every CORE_UNAVAILABLE answer ofinvoke()and ofSheetSession.current()on a restartable runtime kicksvoid this.retry()and still answers CORE_UNAVAILABLE (the next user action works: "Réessayez" becomes true). No counter change: a restart is not a recovery; the cap still counts traps. A restart keepscompiledwhengeneration > 0(the module already ran; only a failed FIRST load clears it), so a restart fetches a glue record, never recompiles. b. Status listeners:subscribe(listener): () => void. Notification is deferred (queueMicrotask) after the transition, never inside the try blocks of load/recover, each listener wrapped in try/catch; a throwing or re-entrant listener cannot change the state machine. - apps/app/src/core/runtime.ts — module-scope
subscribeCore(cb) = coreRuntime().subscribe(cb)(stable identity) anduseCoreStopped()=useSyncExternalStore(subscribeCore, coreStopped). Used on the three core pages only (Editor, Home, New report); creating the runtime object loads nothing (lazy load stays on ready()). - apps/app/src/state/reportStore.ts —
a. exported selector
isUnsaved(s) = s.saveFailed && s.report !== null(one rule, used by the notice and the alerts). b.releaseUnreadSession/mayStartSessionreturnActionResult: set-aside failure → HELD; core cannot read the unread draft (any kind outside UNREADABLE_DRAFT_KINDS) → FAILED (never HELD); initReport / hydrateImport:const may = mayStartSession(index); if (!may.ok) return may. Nothing written in either case (unchanged). - apps/app/src/core/failure.ts —
stoppedMessageKey()=isUnsaved(useReportStore.getState()) ? 'core.stopped_unsaved' : 'core.stopped';coreFailureMessage(t, fallbackKey = 'core.action_failed'): stopped →t(stoppedMessageKey()), elset(fallbackKey). - apps/app/src/lib/download.ts (new) —
downloadJson(raw, stem): body of HeldSessionPanel'sdownloadCopy(Blob application/json, anchor attached while clicked, URL revoked after 30 s,<stem>-<todayIso()>.json). HeldSessionPanel calls it (behaviour unchanged). - apps/app/src/components/report/CoreStoppedNotice.tsx (new) — the one host of the stopped buttons. Reads
useReportStore(isUnsaved)andreport. unsaved → Notice errorcore.stopped_unsaved+ Buttonsession.held.download(reused key) →downloadJson(JSON.stringify(report), 'faunosteo-brouillon'); otherwise Notice errorcore.stopped+ Buttoncore.reload→window.location.reload(). Never a retry.CoreStoppedBanner(same file or inline) =useCoreStopped() ? <CoreStoppedNotice/> : null. - Placement (persistent, whenever stopped, so alerts never name a button that is not on the page):
- EditorRoute banner slot: stopped →
<CoreStoppedNotice/>(same margins as the save banner) INSTEAD ofeditor.save_failed; not stopped + saveFailed →editor.save_failedtext + the same core-free "Télécharger une copie" button [rev 3, owner gate Q1]: the rescue exists in every engine state (a restart that keeps failing offline never reachesstopped). - [rev 3, owner gate Q2]
beforeunloadguard whileisUnsaved(native browser confirm), registered in EditorRoute; removed when the save recovers. - HomeRoute and NewReportRoute:
<CoreStoppedBanner/>at the top of the page content (below the header), so the unsaved variant's download is on every page that can show its text. - CoreUnavailable:
useCoreStopped()→<main><CoreStoppedNotice/></main>instead of notice + retry.
- EditorRoute banner slot: stopped →
- apps/app/src/components/canvas/AnatomyCanvas.tsx — the engine variant is derived at render: a build failure
enginewithuseCoreStopped()true (or a buildengine_stopped) → Notice with the stopped text chosen fromuseReportStore(isUnsaved)(reactive), no button (the page banner holds the buttons; DetailModal never opens once stopped: a zone click is a core call). "Réessayer" (engine only):void coreRuntime().retry().finally(() => setAttempt(n => n + 1)). - Alerts / error lines: EditorRoute export catch →
coreFailureMessage(t, 'editor.export_failed'); NewReportRoute:55 →coreFailureMessage(t, 'sheet.core_unavailable'); HomeRouteimportErrorMessagecore_unavailable →coreFailureMessage(t, 'home.import.error_core_unavailable'); HomeRoute hydrateImport!ok:reason === 'held'→ held alert + navigate (unchanged), else throwImportError('core_unavailable'). - apps/app/src/core/sheetOps.ts:17 comment → "shows
coreFailureMessage". - i18n fr.ts / en.ts —
core.stoppedreworded (choice 2); newcore.stopped_unsaved,core.reload. - ESLint (apps/app/eslint.config.js):
no-restricted-syntaxont('core.action_failed'),t('editor.export_failed'),t('home.import.error_core_unavailable'),t('sheet.core_unavailable')call literals in src, except src/core/failure.ts, and forsheet.core_unavailablealso CoreUnavailable.tsx and AnatomyCanvas.tsx (the census, codebase idiom; dictionaries are not call sites). - docs/development/RUST.md §9.4 (+ §8 runtime note if it describes recovery) and the CHANGELOG R3 owner-decisions line: restart on next action after a failed recovery; stopped notice on the core pages (reload, or unsaved variant with copy); export / import / new report say the stopped message.
Tests
- core-wasm runtime.test.ts: default cap = 3 (three recoveries succeed, fourth trap → stopped, retry false);
failed recovery below the cap → stopped false, then the next call kicks a restart and the call after it
succeeds;
ready()after a failed recovery restarts and resolves true; third recovery fails → stopped true, no restart kicked; a failed first load is NOT restarted by a call (only retry()); subscribe notified (after a microtask) on the transition to stopped, a throwing listener does not change the state, unsubscribe stops it. - AnatomyCanvas: engine retry calls
coreRuntime().retry()(spy) then rebuilds; engine_stopped shows the stopped text (unsaved variant when isUnsaved) and no button. - CoreStoppedNotice: save fine →
core.stopped+ reload button, no retry; isUnsaved →core.stopped_unsaved+ download whose Blob content equals JSON.stringify(report). - EditorRoute: stopped → banner notice replaces
editor.save_failed; not stopped + saveFailed → save banner with the copy button; beforeunload registered only while isUnsaved; export failure while stopped → stopped alert. - runtime: a restart after a failed recovery reuses
compiled(compile called once). - HomeRoute / NewReportRoute: stopped → banner present; stopped + unsaved → download button on the page.
- state.heldSession.test.ts:268-280 inverted: core cannot read the draft →
{ ok: false }withoutreason: 'held', draft untouched; same for hydrateImport. - ESLint rule proven: lint fails on a sample
t('core.action_failed')outside failure.ts (rule test viapnpm linton the tree + one RuleTester-free check: the tree lints clean). pnpm typecheck && pnpm test:run && pnpm lintgreen; core-wasm vitest green (TS-only runtime change, no wasm rebuild; stamp unaffected).
Known residuals (recorded, not fixed here)
saveFailedalso covers a refused archive write (BDR-052 banner semantics, pre-existing): the unsaved variant over-warns then; the copy holds the report, the archive is the imported PDF still on disk.- Kinds such as
rebase_failed(sheet defect) answer FAILED → "Réessayez" (generic; near-unreachable). - Home while not stopped but the engine cannot restart (offline) and saveFailed: no banner there; the editor banner holds the copy.
- New report banner "Recharger la page" discards a typed form (shown from page entry, so usually before typing).
- New report / import while an open report has saveFailed replace it (pre-existing; deliberate user action).
- A draft that traps the core on every load → reload loop (pre-existing).
Out of scope
R4, merge, the frozen PDF engine, Rust crates, goldens; making the JSON copy importable.