From 23e30b238213aeed6c8b91c9c34ed9da385ede6a Mon Sep 17 00:00:00 2001 From: awork Date: Sat, 17 Oct 2026 17:00:59 +0800 Subject: [PATCH] fix(storage): Node-upgrade hint on the recurring sidecar-open degrade warn (#3489) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #3485 (directives 2+3 of #3338): item B of #3489 names TWO surfaces for the upgrade hint — the diagnostics/web degrade reason (covered by #3485 in runtime-status.ts) AND the recurring '[storage] unified sidecar failed to open ...' warn line (src/storage/shadow.ts) that fires on EVERY boot while degraded. The bootstrap-failure log line #3485 added only fires once per 6h cooldown window, so users normally never saw the hint. The hint is gated on the missing-engine error condition (same marker regex as runtime-status.ts), so corrupt-index.db warns keep their byte-stable recovery instruction; on Nodes that ship node:sqlite (>= 22.5) the suffix is empty and the line is unchanged. Tests: gate x version matrix pin + behavioral warn-line capture (no-engine warn carries exactly the helper's verdict for its own error text; corrupt-index warn byte-identical to pre-change). --- src/storage/shadow.ts | 13 +++++- tests/storage-engine-proofs.test.ts | 72 ++++++++++++++++++++++++++++- 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/src/storage/shadow.ts b/src/storage/shadow.ts index fbd57e19de..a3896e1b8c 100644 --- a/src/storage/shadow.ts +++ b/src/storage/shadow.ts @@ -27,6 +27,7 @@ import { resolveStorageMode, resolveStorageWalJournalSizeLimit, type StorageMode import { UnifiedStore, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; import { canonicalize, sha256 } from "./canonical.ts"; import { recordSidecarInstance, recordSidecarOpenFailure } from "./runtime-status.ts"; +import { nodeSqliteUpgradeHint } from "./engine-bootstrap.ts"; import type { SqliteEngineName, SqliteEngineSource } from "./driver.ts"; import type { CoreMessage, MessageContentStore } from "acp-kernel"; @@ -42,6 +43,16 @@ export const VERIFY_EVERY_INGESTS = 20; // discipline, #2030); re-exported here for the storage-layer importers. export { resolveStorageMode, type StorageMode } from "../knobs.ts"; +/** #3489 item B (follow-up to #3485): the recurring boot-time degrade warn + * carries the same Node-upgrade lever as the diagnostics degrade reason — + * but ONLY when the open failure IS the missing-engine condition (#2823); + * other failures (corrupt index.db, disk errors) keep their byte-stable + * recovery instruction untouched. Pure (errText + nodeVersion in → suffix + * out) so tests pin the gate without depending on the runner's own Node. */ +export function sidecarOpenFailHint(errText: string, nodeVersion: string = process.versions.node): string { + return /no SQLite engine available/i.test(errText) ? nodeSqliteUpgradeHint(nodeVersion) : ""; +} + interface ShadowStats { ingests: number; deltaIngests: number; @@ -97,7 +108,7 @@ export class UnifiedShadow { // blobs (#2671 Phase 2) — destructive recovery is operator policy. loggerLog( "warn", - `[storage] unified sidecar failed to open ${dir}/index.db (${String(err)}) — staying legacy-only; delete the file to reset the index`, + `[storage] unified sidecar failed to open ${dir}/index.db (${String(err)}) — staying legacy-only; delete the file to reset the index${sidecarOpenFailHint(String(err))}`, ); recordSidecarOpenFailure(String(err)); return null; diff --git a/tests/storage-engine-proofs.test.ts b/tests/storage-engine-proofs.test.ts index f323110c97..428394d32b 100644 --- a/tests/storage-engine-proofs.test.ts +++ b/tests/storage-engine-proofs.test.ts @@ -26,6 +26,9 @@ * instead of bricking construction (#2771). * CAS REFCOUNT — shared content blobs survive deleteSession of one * session and are collected only at refcount 0. + * DEGRADE HINT — the boot-time warn surfaces the Node-upgrade lever + * ONLY for the missing-engine failure; corrupt-index + * keeps its byte-stable recovery line (#3489 item B). * * The corrupt-index test is the regression for #2771; the rest are contract * pins (proof-only, no product change). @@ -39,8 +42,10 @@ import * as path from "node:path"; import { SessionStore } from "../src/persist.ts"; import type { Session } from "../src/session.ts"; import { UnifiedStore } from "../src/storage/store.ts"; -import { UnifiedShadow } from "../src/storage/shadow.ts"; +import { UnifiedShadow, sidecarOpenFailHint } from "../src/storage/shadow.ts"; import { setSqliteEnginesUnavailableForTests } from "../src/storage/driver.ts"; +import { nodeSqliteUpgradeHint } from "../src/storage/engine-bootstrap.ts"; +import { setLogCapture } from "../src/logger.ts"; import { planIngest, loadLegacyView, toLegacyLike, type LegacySessionLike } from "../src/storage/ingest.ts"; import { canonicalize, sha256 } from "./golden-canonical.ts"; import { driveWire, WIRES, type Wire } from "./golden-storage-drive.ts"; @@ -502,6 +507,71 @@ test("storage engine: no SQLite engine -> maybeOpen degrades to null (sidecar ab } }); +// --------------------------------------------------------------------------- +// DEGRADE HINT SURFACES (#3489 item B, follow-up to #3485): the recurring +// boot-time warn (maybeOpen's catch) must carry the Node-upgrade lever ONLY +// for the missing-engine condition; every other open failure keeps its +// byte-stable recovery instruction. +// --------------------------------------------------------------------------- + +test("storage engine: sidecarOpenFailHint pins the gate x version matrix (#3489)", () => { + const oldNode = "20.19.0"; + const hint = nodeSqliteUpgradeHint(oldNode); + assert.ok(hint.length > 0, "sanity: a pinned pre-22.5 Node must lack the builtin"); + assert.equal( + sidecarOpenFailHint("[storage:node:sqlite] no SQLite engine available", oldNode), + hint, + "missing-engine failure on a pre-22.5 Node must carry the upgrade hint", + ); + assert.equal( + sidecarOpenFailHint("SQLITE_NOTADB: file is not a database", oldNode), + "", + "corrupt-index failures must NOT pick up the upgrade hint", + ); + assert.equal( + sidecarOpenFailHint("[storage:node:sqlite] no SQLite engine available", "24.0.0"), + "", + "Nodes with the builtin have nothing to suggest", + ); +}); + +test("storage engine: no-engine boot warn carries the hint slot; corrupt-index warn stays byte-stable (#3489)", () => { + const dir = tmpdir("bili-engproof-hint-warn-"); + const lines: string[] = []; + setLogCapture((_level, msg) => { lines.push(msg); }); + try { + // Missing engine: the warn is the pre-change base PLUS exactly what + // the helper says for THIS runner's Node (on a <22.5 runner that IS + // the full upgrade hint). + setSqliteEnginesUnavailableForTests(true); + const shadow = UnifiedShadow.maybeOpen(dir, { BILI_STORAGE_UNIFIED: "full" }, () => null); + assert.equal(shadow, null, "no-engine maybeOpen must degrade to null"); + const base = `[storage] unified sidecar failed to open ${dir}/index.db`; + const line = lines.find((l) => l.startsWith(base)); + assert.ok(line, "no-engine open failure must log the degrade warn"); + const parsed = /\((.*)\) — staying legacy-only; delete the file to reset the index(.*)$/.exec(line); + assert.ok(parsed, "warn line shape drifted"); + const [, errText, suffix] = parsed; + assert.match(errText, /no SQLite engine available/i, "captured failure must be the missing-engine condition"); + assert.equal(suffix, sidecarOpenFailHint(errText), "suffix must be exactly the helper's verdict for the captured error"); + + // Corrupt index (engines available): the warn must end byte-identical + // to the pre-#3489 line — no hint, no drift of the recovery text. + setSqliteEnginesUnavailableForTests(false); + fs.writeFileSync(path.join(dir, "index.db"), Buffer.alloc(512, 0x5a)); + lines.length = 0; + const shadow2 = UnifiedShadow.maybeOpen(dir, { BILI_STORAGE_UNIFIED: "full" }, () => null); + assert.equal(shadow2, null, "corrupt-index maybeOpen must degrade to null"); + const corrupt = lines.find((l) => l.startsWith(base)); + assert.ok(corrupt, "corrupt-index open failure must log the degrade warn"); + assert.ok(corrupt.endsWith("delete the file to reset the index"), "corrupt-index warn must stay byte-stable (no hint)"); + } finally { + setSqliteEnginesUnavailableForTests(false); + setLogCapture(null); + rmrf(dir); + } +}); + test("storage engine: no SQLite engine -> SessionStore runs legacy-only, writes survive, no index.db (#2823)", async () => { const dir = tmpdir("bili-engproof-noengine-e2e-"); const prev = process.env.BILI_STORAGE_UNIFIED;