The registry loads into memory at gateway start and syncs writes to SQLite for durability across restarts.

The Gateway keeps the SQLite write-ahead log bounded by using SQLite's default

autocheckpoint threshold plus periodic and shutdown `TRUNCATE` checkpoints.

autocheckpoint threshold plus periodic `PASSIVE` checkpoints. Shutdown and

explicit maintenance checkpoints still use `TRUNCATE` so normal closes can

reclaim WAL space without making the background sweeper wait on active readers.

### Automatic maintenance

export {

CHARS_PER_TOKEN_ESTIMATE,

DEFAULT_SQLITE_WAL_AUTOCHECKPOINT_PAGES,

DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS,

DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS,

applyWindowsSpawnProgramPolicy,

configureSqliteWalMaintenance,

export { ssrfPolicyFromHttpBaseUrlAllowedHostname } from "../../../../src/infra/net/ssrf.js";

export {

DEFAULT_SQLITE_WAL_AUTOCHECKPOINT_PAGES,

DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS,

DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS,

configureSqliteWalMaintenance,

} from "../../../../src/infra/sqlite-wal.js";

export {

DEFAULT_SQLITE_WAL_AUTOCHECKPOINT_PAGES,

DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS,

DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS,

configureSqliteWalMaintenance,

} from "./openclaw-runtime-io.js";

}

});

it("runs periodic TRUNCATE checkpoints and stops them on close", () => {

it("runs lightweight periodic PASSIVE checkpoints and TRUNCATE on close", () => {

vi.useFakeTimers();

const db = createMockDb();

const maintenance = configureSqliteWalMaintenance(db, { checkpointIntervalMs: 100 });

expect(db["exec"]).toHaveBeenCalledTimes(2);

vi.advanceTimersByTime(100);

expect(db["exec"]).toHaveBeenLastCalledWith("PRAGMA wal_checkpoint(TRUNCATE);");

expect(db["exec"]).toHaveBeenLastCalledWith("PRAGMA wal_checkpoint(PASSIVE);");

expect(db["exec"]).toHaveBeenCalledTimes(3);

expect(maintenance.close()).toBe(true);

expect(db["exec"]).toHaveBeenLastCalledWith("PRAGMA wal_checkpoint(TRUNCATE);");

expect(db["exec"]).toHaveBeenCalledTimes(4);

vi.advanceTimersByTime(200);

maintenance.close();

});

it("honors explicit checkpoint mode overrides for periodic and close checkpoints", () => {

vi.useFakeTimers();

const db = createMockDb();

const maintenance = configureSqliteWalMaintenance(db, {

checkpointIntervalMs: 100,

checkpointMode: "FULL",

});

vi.advanceTimersByTime(100);

expect(db["exec"]).toHaveBeenLastCalledWith("PRAGMA wal_checkpoint(FULL);");

expect(maintenance.close()).toBe(true);

expect(db["exec"]).toHaveBeenLastCalledWith("PRAGMA wal_checkpoint(FULL);");

});

it("reports checkpoint errors without throwing from background maintenance", () => {

const db = createMockDb();

const error = new Error("busy");

// WAL maintenance configures SQLite write-ahead logging and schedules bounded

// checkpoints so state databases do not accumulate unbounded WAL files.

export const DEFAULT_SQLITE_WAL_AUTOCHECKPOINT_PAGES = 1000;

export const DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS = 30 * 60 * 1000;

export const DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS = 30 * 60 * 1000;

/**

* @deprecated Use DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS.

* Periodic checkpoints default to PASSIVE.

*/

export const DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS = DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS;

const LINUX_NFS_SUPER_MAGIC = 0x6969;

const PROC_MOUNTINFO_PATH = "/proc/self/mountinfo";

"autoCheckpointPages",

);

const checkpointIntervalMs = normalizeNonNegativeInteger(

options.checkpointIntervalMs ?? DEFAULT_SQLITE_WAL_TRUNCATE_INTERVAL_MS,

options.checkpointIntervalMs ?? DEFAULT_SQLITE_WAL_CHECKPOINT_INTERVAL_MS,

"checkpointIntervalMs",

);

const timerIntervalMs = Math.min(checkpointIntervalMs, MAX_TIMER_TIMEOUT_MS);

const checkpointMode = options.checkpointMode ?? "TRUNCATE";

const periodicCheckpointMode = options.checkpointMode ?? "PASSIVE";

if (options.databasePath && isNfsBackedPath(options.databasePath)) {

requireRollbackJournalMode(db, options);

return {

db.exec("PRAGMA journal_mode = WAL;");

db.exec(`PRAGMA wal_autocheckpoint = ${autoCheckpointPages};`);

const checkpoint = (): boolean => {

const runCheckpoint = (mode: SqliteWalCheckpointMode): boolean => {

try {

db.exec(`PRAGMA wal_checkpoint(${checkpointMode});`);

db.exec(`PRAGMA wal_checkpoint(${mode});`);

return true;

} catch (error) {

options.onCheckpointError?.(error);

return false;

}

};

const checkpoint = (): boolean => runCheckpoint(checkpointMode);

let timer: IntervalHandle | null = null;

if (timerIntervalMs > 0) {

timer = setInterval(checkpoint, timerIntervalMs) as IntervalHandle;

timer = setInterval(

() => runCheckpoint(periodicCheckpointMode),

timerIntervalMs,

) as IntervalHandle;

timer.unref?.();

}