@wirecat/cli-core 0.598.0 → 0.599.0

package/dist/store/health.js

@@ -0,0 +1,170 @@
+import { existsSync, statSync } from "node:fs";
+import { openSqlite } from "./sqlite/open.js";
+export const QUICK_CHECK_LIMIT = 10_000;
+/** What `doctor` checks by default, said where it answers. */
+export const QUICK_HEALTH_CHECKS = "the file header, its size against its page count, and the schema's own pages";
+const FTS5 = /^\s*CREATE\s+VIRTUAL\s+TABLE\s+\S+\s+USING\s+fts5\s*\(/i;
+export const fts5Tables = (database) => database
+    .prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%' ORDER BY name")
+    .all()
+    .filter((row) => FTS5.test(String(row.sql)))
+    .map((row) => {
+    const sql = String(row.sql);
+    return { name: String(row.name), sql, external: /content\s*=\s*'[^']+'/i.test(sql) };
+});
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+const bytesOf = (path) => statSync(path, { throwIfNoEntry: false })?.size ?? 0;
+/** Groups the lines by the table whose tree they name: `Tree <root page> …` or `NULL value in <table>.<column>`. */
+export const damagedTables = (database, lines) => {
+    const roots = new Map(database
+        .prepare("SELECT rootpage, tbl_name FROM sqlite_master WHERE rootpage > 0")
+        .all()
+        .map((row) => [Number(row.rootpage), String(row.tbl_name)]));
+    const owners = new Map(database
+        .prepare("SELECT name, tbl_name FROM sqlite_master WHERE type = 'index'")
+        .all()
+        .map((row) => [String(row.name), String(row.tbl_name)]));
+    const virtual = database
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND sql LIKE 'CREATE VIRTUAL TABLE%'")
+        .all()
+        .map((row) => String(row.name));
+    // A search index's rows live in its shadow tables: `email_words_data` is damage to `email_words`.
+    const ownerOf = (table) => table === null ? null : (virtual.find((name) => table.startsWith(`${name}_`)) ?? table);
+    const tables = new Map();
+    for (const raw of lines) {
+        const line = raw.replace(/^\*\*\* in database \w+ \*\*\*\s*/, "");
+        const tree = /^Tree (\d+) /.exec(line);
+        const column = /value in (\w+)\.\w+/.exec(line) ?? /^table (\w+): /.exec(line);
+        const index = /index (\w+)/.exec(line)?.[1];
+        const table = ownerOf(tree
+            ? (roots.get(Number(tree[1])) ?? null)
+            : column
+                ? (column[1] ?? null)
+                : index
+                    ? (owners.get(index) ?? null)
+                    : null);
+        const known = tables.get(table);
+        if (known)
+            known.problems += 1;
+        else
+            tables.set(table, { table, problems: 1, sample: line.slice(0, 200) });
+    }
+    return [...tables.values()].sort((a, b) => b.problems - a.problems);
+};
+/** `rank = 0` checks the index's own structure, the only check a contentless index has; it writes nothing. */
+export const searchIndexHealth = (database) => fts5Tables(database).map(({ name }) => {
+    try {
+        database.exec("BEGIN");
+        try {
+            database.exec(`INSERT INTO "${name}" ("${name}", rank) VALUES ('integrity-check', 0)`);
+        }
+        finally {
+            database.exec("ROLLBACK");
+        }
+        return { name, ok: true };
+    }
+    catch (error) {
+        return { name, ok: false, error: messageOf(error) };
+    }
+});
+const pragmaLines = (database, sql) => database
+    .prepare(sql)
+    .all()
+    .flatMap((row) => String(Object.values(row)[0]).split("\n"));
+/**
+ * SQLite stops the whole check at a page it cannot read and returns none of what it found. Then each table is
+ * checked alone, so the answer still names every damaged one.
+ */
+const checkLines = (database) => {
+    try {
+        return pragmaLines(database, `PRAGMA quick_check(${QUICK_CHECK_LIMIT})`);
+    }
+    catch {
+        const tables = database
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND rootpage > 0 ORDER BY name")
+            .all()
+            .map((row) => String(row.name));
+        return tables.flatMap((table) => {
+            try {
+                return pragmaLines(database, `PRAGMA quick_check("${table}")`).filter((line) => line !== "ok");
+            }
+            catch (error) {
+                return [`table ${table}: ${messageOf(error)}`];
+            }
+        });
+    }
+};
+const quickHealth = (database, path) => {
+    const pragma = (name) => Number(Object.values(database.prepare(`PRAGMA ${name}`).get() ?? {})[0] ?? 0);
+    const file = {
+        bytes: bytesOf(path),
+        pages: pragma("page_count"),
+        pageSize: pragma("page_size"),
+        freePages: pragma("freelist_count"),
+    };
+    const schema = database
+        .prepare("PRAGMA quick_check('sqlite_schema')")
+        .all()
+        .map((row) => String(Object.values(row)[0]));
+    // Pages still in the write-ahead log are not in the file yet, so only a file with none of them must match.
+    const walFrames = existsSync(`${path}-wal`) && bytesOf(`${path}-wal`) > 0;
+    const sized = walFrames || file.bytes === file.pages * file.pageSize;
+    const problems = [
+        ...(schema.length === 1 && schema[0] === "ok" ? [] : schema),
+        ...(sized ? [] : [`the file holds ${file.bytes} bytes, its header says ${file.pages * file.pageSize}`]),
+    ];
+    return { file, problems };
+};
+/**
+ * The store's health without changing it. `quick` takes milliseconds at any size; `deep` reads every page
+ * (about 30 s for 6 GB) and checks every search index, under a transaction it rolls back.
+ */
+export const storeHealth = async (path, { deep = false } = {}) => {
+    const started = Date.now();
+    const checked = deep ? "deep" : "quick";
+    const done = (health) => ({
+        path,
+        checked,
+        ...health,
+        ms: Date.now() - started,
+    });
+    let database;
+    try {
+        database = (await openSqlite(path, { readOnly: !deep })).database;
+    }
+    catch (error) {
+        return done({ ok: false, error: messageOf(error) });
+    }
+    try {
+        const { file, problems } = quickHealth(database, path);
+        if (!deep) {
+            return done({
+                ok: problems.length === 0,
+                file,
+                ...(problems.length
+                    ? {
+                        problems: problems.length,
+                        damagedTables: [{ table: null, problems: problems.length, sample: problems[0] }],
+                    }
+                    : {}),
+            });
+        }
+        database.exec("PRAGMA busy_timeout = 30000");
+        const lines = checkLines(database);
+        const pagesOk = lines.length === 1 && lines[0] === "ok";
+        const indexes = searchIndexHealth(database);
+        return done({
+            ok: pagesOk && problems.length === 0 && indexes.every((index) => index.ok),
+            file,
+            problems: pagesOk ? 0 : lines.length,
+            damagedTables: pagesOk ? [] : damagedTables(database, lines),
+            searchIndexes: indexes,
+        });
+    }
+    catch (error) {
+        return done({ ok: false, error: messageOf(error) });
+    }
+    finally {
+        database.close();
+    }
+};

package/dist/store/index.d.ts

@@ -9,12 +9,14 @@ export type { FindingEvidence, FindingOutcome, MeetingFactFinding, MeetingFindin
 export { PAYMENT_DIRECTIONS, PAYMENT_STATES, type Payment, paymentTitle, validatePayment } from "../meetings/index.js";
 export { CLOSED_STATES, isClosedState, PRIORITY_LABELS, type PriorityLabel, priorityLabel, priorityOf, priorityOption, TASK_STATES, type TaskState, } from "../tasks/index.js";
 export type { AccountMail, AccountMeetings, AccountStore } from "./account-store.js";
+export { type DamageExplanation, explainDamage } from "./damage.js";
 export { assertMayDecide, DEFAULT_DECISION_POLICY, type Decider, type DecisionPolicy, isOwnerOnlyKind, mayDecide, type Proposer, type Refusal, } from "./decisions.js";
 export type { DocumentTransferOptions, DocumentTransferPreview, DocumentTransferReceipt, } from "./document-transfer/index.js";
 export { applyDocumentTransfer, previewDocumentTransfer } from "./document-transfer/index.js";
 export type { CacheDatabase, CacheStatement, OpenDatabase, SqlValue } from "./driver.js";
 export { PRAGMAS } from "./driver.js";
 export { EVIDENCE_FINDINGS_KIND, type EvidenceFindingsBatch, type EvidenceFindingsDecider, type EvidenceFindingsReceipt, type EvidenceFindingsStore, validateEvidenceFindings, } from "./evidence-findings.js";
+export { type DamagedTable, QUICK_HEALTH_CHECKS, type SearchIndexHealth, type StoreHealth, storeHealth, } from "./health.js";
 export { ORGANIZATIONS_QUERY, organization, PROJECTS_QUERY, project, REMINDERS_QUERY, reminder, } from "./knowledge-query.js";
 export { MAIL_FINDINGS_KIND, type MailFindingsBatch, type MailFindingsCheck, type MailFindingsStore, } from "./mail-findings.js";
 export type { MeetingFindingsBatch, MeetingFindingsStore } from "./meeting-findings.js";

package/dist/store/index.js

@@ -3,10 +3,12 @@ export { createTagRedirectIndex } from "../domain/tag-redirects.js";
 export { note } from "../entities/note.js";
 export { PAYMENT_DIRECTIONS, PAYMENT_STATES, paymentTitle, validatePayment } from "../meetings/index.js";
 export { CLOSED_STATES, isClosedState, PRIORITY_LABELS, priorityLabel, priorityOf, priorityOption, TASK_STATES, } from "../tasks/index.js";
+export { explainDamage } from "./damage.js";
 export { assertMayDecide, DEFAULT_DECISION_POLICY, isOwnerOnlyKind, mayDecide, } from "./decisions.js";
 export { applyDocumentTransfer, previewDocumentTransfer } from "./document-transfer/index.js";
 export { PRAGMAS } from "./driver.js";
 export { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "./evidence-findings.js";
+export { QUICK_HEALTH_CHECKS, storeHealth, } from "./health.js";
 export { ORGANIZATIONS_QUERY, organization, PROJECTS_QUERY, project, REMINDERS_QUERY, reminder, } from "./knowledge-query.js";
 export { MAIL_FINDINGS_KIND, } from "./mail-findings.js";
 export { MIGRATIONS, migrate } from "./migrations.js";

package/dist/store/recover.d.ts

@@ -0,0 +1,103 @@
+import type { CacheDatabase } from "./driver.js";
+import { type StoreHealth } from "./health.js";
+/** `contentless_delete`, which every word index uses, came in SQLite 3.43. */
+export declare const SQLITE3_MINIMUM: readonly [3, 43, 0];
+export declare const sqlite3Program: (program?: string) => {
+    program: string;
+    version: string | null;
+    usable: boolean;
+};
+/** The WireCat timers still scheduled: each may open the store while it is being recovered. Linux only. */
+export declare const activeTimers: () => string[] | undefined;
+/** Processes that have any of the store's files open, by PID and program name, never their arguments. */
+export declare const storeHolders: (path: string) => {
+    pid: number;
+    name: string;
+}[] | undefined;
+/** Rows per table that holds data; `null` where the table cannot be counted. Search shadow tables are left out. */
+export declare const tableRows: (database: CacheDatabase) => Record<string, number | null>;
+/**
+ * Copies every row SQLite can still read into a new file with the `sqlite3` program's `.recover`: node:sqlite has
+ * no recovery API. The damaged file is opened read-only. Rows that fit no table go to a table the rebuild counts
+ * and drops; a row that breaks its table's constraints (a NULL where none may be) is skipped. Free pages are not
+ * read: what they hold was deleted, and must not come back.
+ */
+export declare const copyReadableRows: (path: string, target: string, program?: string) => Promise<{
+    errors: string[];
+    read: Record<string, number>;
+}>;
+export interface DerivedRebuild {
+    lostAndFound: number;
+    searchIndexes: string[];
+    /** Indexes recreated empty that this build has no recipe for: they fill as the tools that own them write. */
+    unfilled: string[];
+    mentions: number;
+    vectorModels: string[];
+    /** Per model: pieces of text a search by meaning computes a vector for when it first needs one. */
+    chunksWithoutVector: Record<string, number>;
+}
+/**
+ * Drops every search index and vector index and makes it again empty, then fills it from the data. A recovered
+ * index holds whatever pages survived, which no check can tell from a whole one; the data they come from can.
+ */
+export declare const rebuildDerived: (database: CacheDatabase, { now, note }?: {
+    now?: () => number;
+    note?: (text: string) => void;
+}) => DerivedRebuild;
+export interface DanglingRows {
+    table: string;
+    parent: string;
+    rows: number;
+    /** Up to 20 keys of the parent rows they point at, which the store no longer holds. */
+    missing: (number | string)[];
+}
+/** Rows that point at a row the store does not hold: after a recovery, mostly rows that could not be read. */
+export declare const danglingRows: (database: CacheDatabase) => DanglingRows[];
+export interface LostRows {
+    table: string;
+    before: number | null;
+    read: number;
+    kept: number;
+}
+export interface Recovery {
+    path: string;
+    keptAt: string;
+    sqlite3: string;
+    /**
+     * Tables that lost rows or may have: `before` is null where the damaged file could not count them, `read` is what
+     * `.recover` found, `kept` what fit the table; rows on pages it could not read at all are in none of them.
+     */
+    lost: LostRows[];
+    dangling: DanglingRows[];
+    mailToFetch: {
+        account: string;
+        emails: number;
+    }[];
+    rebuilt: DerivedRebuild;
+    copyErrors: string[];
+    health: StoreHealth;
+    seconds: {
+        copy: number;
+        rebuild: number;
+        check: number;
+        total: number;
+    };
+}
+export interface RecoverOptions {
+    path: string;
+    command: string;
+    version?: string;
+    sqlite3?: string;
+    now?: () => number;
+    note?: (text: string) => void;
+    /** Copies the readable rows into the new file; `copyReadableRows` unless a test gives its own. */
+    copy?: (path: string, target: string) => Promise<{
+        errors: string[];
+        read: Record<string, number>;
+    }>;
+}
+/**
+ * Copies every readable row of a damaged store into a new file, rebuilds what is derived from them, checks the
+ * result, and puts it in place of the store. The damaged file is kept beside it and never written to.
+ */
+export declare const recoverStore: ({ path, command, version, sqlite3, now, note, copy, }: RecoverOptions) => Promise<Recovery>;