Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion src/storage/shadow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
72 changes: 71 additions & 1 deletion tests/storage-engine-proofs.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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";
Expand Down Expand Up @@ -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;
Expand Down
Loading