@wirecat/cli-core 0.594.0 → 0.596.0

package/CHANGELOG.md

@@ -5,7 +5,34 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.596.0 — 06.11.2026
+
+### Added
+
+- **`package.json` says which store schema the version speaks.** `wirecat.store` holds `speaks`, the newest schema
+  it migrates a file to, and `minCompatible`, the oldest schema that can still use a file it migrated, so an
+  installer can check a tool against the owner's store from the npm registry before installing it.
+
+### Fixed
+
+- **A read-only open migrates an older store first.** `openStore({ readOnly: true })` on a file at an older schema
+  opens it the ordinary way once, which migrates it, then opens it read-only, instead of refusing it with
+  `configuration_error`. A tool whose first command only reads no longer needs a workaround. A newer incompatible
+  schema is still refused, and a missing file is still not created.
+
+## 0.595.0 — 06.11.2026
+
+### Added
+
+- **A rollback copy before a breaking store upgrade.** Before a migration that raises `min_compatible` (after which
+  older tools refuse the store), the base tables it names are copied into `backups/` beside the store, as
+  `<store>-rollback-schema-<version>-<time>.db`, with the schema as it was. Search indexes, vectors and other derived
+  tables are never copied. Without the free space for it, the upgrade runs anyway and warns. `store restore <copy>`
+  puts the tables back and returns the store to that version, so the older tool opens it again; its `store rebuild`
+  then refreshes the search indexes. The copy is deleted on the first open a day after the upgrade succeeded.
+- **`Migration.tables`** and the manifest's `tables`: required on a migration that raises `minCompatible`, the base
+  tables it changes by their names before it. `generatedMigrations` refuses a raising one without it, or one that
+  names a derived table.
 
 ## 0.594.0 — 06.11.2026
 

package/dist/background/schedules.d.ts

@@ -49,6 +49,14 @@ export interface DaySpend {
 export declare const localDay: (at: Date) => string;
 /** What the schedule's runs cost today; nothing before its first priced run of the day. */
 export declare const spentToday: (file: string, now?: Date) => number;
+/**
+ * What an agent is given on its stdin before its first turn: the host's own reads of what the run is about, so
+ * the agent spends no model turns fetching them. Returns `undefined` when the schedule has none. `run` runs one
+ * command of this CLI under the run's variables and answers its stdout.
+ */
+export type AgentInput = (schedule: Schedule, run: (argv: string[]) => Promise<string>) => Promise<string | undefined>;
+/** The most an agent's input may hold; a longer one is cut, so a mailbox in flood cannot grow every turn's context. */
+export declare const AGENT_INPUT_MAX_CHARS = 60000;
 /** Another CLI a scheduled agent may run by name, as the host declares it: `memo`'s agent runs `mail`. */
 export type AgentCli = Pick<AppIdentity, "command" | "appName" | "envPrefix">;
 export interface LastRun {
@@ -164,7 +172,7 @@ export declare const CREDENTIALS_UNREACHABLE = "credentials.unreachable";
  * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
  * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, untilUnlocked, wait, agentRuns, }?: {
+export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, untilUnlocked, wait, agentRuns, agentInput, }?: {
     now?: () => Date;
     timer?: Timer;
     signal?: AbortSignal;
@@ -173,4 +181,5 @@ export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env:
     wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** The other CLIs an agent may run; each runs under its own read-only lock and knows it runs from a schedule. */
     agentRuns?: readonly AgentCli[];
+    agentInput?: AgentInput;
 }) => Promise<LastRun>;

package/dist/background/schedules.js

@@ -53,6 +53,11 @@ const reportOf = (stdout) => {
         return { text: stdout };
     }
 };
+/** The most an agent's input may hold; a longer one is cut, so a mailbox in flood cannot grow every turn's context. */
+export const AGENT_INPUT_MAX_CHARS = 60_000;
+const capped = (input) => input.length <= AGENT_INPUT_MAX_CHARS
+    ? input
+    : `${input.slice(0, AGENT_INPUT_MAX_CHARS)}\n\n[input cut at ${AGENT_INPUT_MAX_CHARS} characters; the rest waits for the next run]\n`;
 /** Why a timer left a run out, as an id a translation can key on; `why` stays the English sentence. */
 export const SKIP_REASONS = {
     costDayCap: "cost.day-cap",
@@ -426,7 +431,7 @@ const pause = (ms, signal) => new Promise((resolve) => {
  * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
  * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, untilUnlocked = false, wait = pause, agentRuns = [], } = {}) => {
+export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, untilUnlocked = false, wait = pause, agentRuns = [], agentInput, } = {}) => {
     const schedule = readSchedule(file);
     const folder = join(file, "..");
     const runs = join(folder, "runs");
@@ -434,12 +439,24 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
     const agent = schedule.kind === "agent";
     const retries = untilUnlocked && !("every" in schedule.when);
     const firstAt = now().getTime();
-    let last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns });
+    let last = await attemptSchedule(app, system, env, schedule, folder, {
+        now,
+        signal,
+        killAfterMs,
+        agentRuns,
+        agentInput,
+    });
     for (let delay = LOCKED_FIRST_WAIT_MS; retries && lockedOut(last) && !signal?.aborted && now().getTime() - firstAt + delay <= LOCKED_GIVE_UP_MS; delay = Math.min(delay * 2, LOCKED_LONGEST_WAIT_MS)) {
         await wait(delay, signal);
         if (signal?.aborted)
             break;
-        last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns });
+        last = await attemptSchedule(app, system, env, schedule, folder, {
+            now,
+            signal,
+            killAfterMs,
+            agentRuns,
+            agentInput,
+        });
     }
     const { exitCode, output } = last;
     const errors = agent ? output.replace(/\.md$/, ".log") : output;
@@ -493,8 +510,24 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
     }
     return last;
 };
+/** The agent's input, or none: a host read that fails leaves the agent to fetch what it needs itself. */
+const inputOf = async (agentInput, system, env, schedule, log) => {
+    try {
+        const input = await agentInput(schedule, async (argv) => {
+            const ran = await system.run([...system.entry, ...argv], env);
+            if (ran.code !== 0)
+                throw new Error(`${argv.slice(0, 3).join(" ")} exited ${ran.code}`);
+            return ran.stdout;
+        });
+        return input === undefined ? undefined : capped(input);
+    }
+    catch (error) {
+        log.warn({ event: "schedule.input-failed", schedule: schedule.name, reason: String(error) });
+        return undefined;
+    }
+};
 /** One run of the schedule's command or agent: its output in `runs/`, its result in `last.json`. */
-const attemptSchedule = async (app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns, }) => {
+const attemptSchedule = async (app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns, agentInput, }) => {
     const runs = join(folder, "runs");
     const stamp = now()
         .toISOString()
@@ -526,9 +559,13 @@ const attemptSchedule = async (app, system, env, schedule, folder, { now, signal
     const facts = { schedule: schedule.name, kind: schedule.kind };
     const began = now().getTime();
     log.info({ event: "schedule.start", ...facts });
+    const input = agent && agentInput ? await inputOf(agentInput, system, childEnv, schedule, log) : undefined;
     let costUsd;
     const exitCode = await new Promise((resolve) => {
-        const child = spawn(program, args, { env: childEnv, cwd: folder, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(program, args, { env: childEnv, cwd: folder, stdio: ["pipe", "pipe", "pipe"] });
+        // An agent that stops reading its stdin may close it first; that is no failure of the run.
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(input);
         const out = [];
         const err = [];
         child.stdout.on("data", (chunk) => out.push(chunk));

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, type AISettings, resolveAISettings } from "../analysis/settings.js";
-export type { AgentCli } from "../background/schedules.js";
+export type { AgentCli, AgentInput } from "../background/schedules.js";
 export { parseDuration } from "../domain/duration.js";
 export { openOf, PROFILE_PLACEHOLDER, type ProfilesFor, type RefOpen, type RefSummary, refLabel, } from "../domain/ref-summaries.js";
 export { botTemplate } from "../entities/list-results.js";

package/dist/cli/messenger/store-maintenance-command.js

@@ -12,7 +12,7 @@ import { migrate } from "../../store/migrations.js";
 import { openCache } from "../../store/open.js";
 import { storePath } from "../../store/path.js";
 import { deleteCopy, repairStore } from "../../store/repair.js";
-import { drainNoteIndex, dropAllUnusedVectors, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, searchIndexState, stemmerCache, stemsState, vectorIndexCounts, } from "../../store/store.js";
+import { drainNoteIndex, dropAllUnusedVectors, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, rollBack, searchIndexState, stemmerCache, stemsState, vectorIndexCounts, } from "../../store/store.js";
 import { environmentOf, outputFor } from "../context.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -362,7 +362,11 @@ const migrateCommand = (messenger) => annotate(new Command("migrate"), { output:
     }
     const answer = await reading(path, (database) => {
         const from = schemaOf(database).version;
-        migrate(database, { command: messenger.app.command, version: messenger.app.version });
+        migrate(database, {
+            command: messenger.app.command,
+            version: messenger.app.version,
+            rollback: { store: path, warn: (line) => renderer.warn(line) },
+        });
         const { normalized, indexed, terms } = buildWordIndex(database, (note) => renderer.note(note));
         const stemmed = buildStems(database, (note) => renderer.note(note));
         const notes = buildNoteIndex(database, (note) => renderer.note(note));
@@ -533,9 +537,11 @@ const decryptCommand = () => annotate(new Command("decrypt"), { output: { entity
  * `serve` runs: that opens the store on its first write, so until then it holds nothing to see.
  */
 const restoreCommand = (messenger) => annotate(new Command("restore"), { output: { entity: "store_restore" }, effects: LOCAL_WRITE })
-    .summary("restore a backup while keeping the current store")
-    .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted")
-    .argument("<file>", "a file `store backup` wrote; one written with --encrypt asks for its password")
+    .summary("restore a backup and keep the current store, or roll back a breaking upgrade")
+    .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted. Given a rollback " +
+    "copy (backups/<store>-rollback-schema-<version>-<time>.db, kept for a day before an upgrade older tools " +
+    "cannot open), put its tables back in the store and return it to that version instead")
+    .argument("<file>", "a file `store backup` wrote, or a rollback copy; one written with --encrypt asks for its password")
     .action(async function (file) {
     const path = storePath(environmentOf(this).env ?? process.env);
     const given = resolve(file);
@@ -560,6 +566,8 @@ const restoreFrom = async (command, messenger, backup, given) => {
     if (existsSync(path) && realpathSync(backup) === realpathSync(path)) {
         throw new CliError("validation_error", `${backup} is the store itself`);
     }
+    if (await isRollbackCopy(backup))
+        return rollBackFrom(command, messenger, backup);
     const schema = await backupSchema(backup);
     const stamp = stampNow();
     const kept = existsSync(path) ? `${path}.before-restore-${stamp}` : null;
@@ -588,6 +596,47 @@ const restoreFrom = async (command, messenger, backup, given) => {
         renderer.note(`the backup is behind this build; the next command migrates it — \`${lineOf(command, "store migrate")}\` now`);
     }
 };
+const isRollbackCopy = async (file) => {
+    try {
+        return await readingOnly(file, (database) => database.prepare("SELECT 1 FROM sqlite_master WHERE name = 'rollback_meta'").get() !== undefined);
+    }
+    catch {
+        return false;
+    }
+};
+/** In place, in one transaction: the copy holds only the tables the upgrade changed, never a whole store. */
+const rollBackFrom = async (command, messenger, copy) => {
+    const { renderer } = outputFor(command);
+    const path = storePath(environmentOf(command).env ?? process.env);
+    if (!existsSync(path))
+        throw new CliError("not_found", `no store at ${path} to roll back`);
+    const waitMs = environmentOf(command).storeLockWaitMs;
+    await quiesce(path, messenger, "restore", (message) => renderer.warn(message), waitMs);
+    const { database } = await openSqlite(path);
+    let rolled;
+    try {
+        rolled = rollBack(database, copy);
+    }
+    finally {
+        database.close();
+    }
+    result(command, {
+        path,
+        restoredFrom: copy,
+        rolledBack: true,
+        schema: rolled.from,
+        was: rolled.was,
+        tables: rolled.restored,
+        rebuilt: rolled.rebuilt,
+        foreignKeyViolations: rolled.foreignKeyViolations,
+    });
+    const taken = new Date(rolled.createdAt).toISOString();
+    renderer.note(`the store is back at schema ${rolled.from}; ${rolled.tables.length > 0 ? rolled.tables.join(", ") : "no table"} ` +
+        `hold what they held at ${taken}, and what was written to them since is not kept`);
+    renderer.note("open it with the older tool and run its `store rebuild`: the search indexes are behind the tables");
+    renderer.note(`a tool that speaks schema ${rolled.to} or later migrates it again on its next run`);
+    renderer.note("restart every serve and mcp of either CLI that was running, so they read the restored store");
+};
 const backupSchema = async (backup) => {
     let read;
     try {

package/dist/cli/schedule/schedule-command.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { type AgentCli, type Schedule } from "../../background/schedules.js";
+import { type AgentCli, type AgentInput, type Schedule } from "../../background/schedules.js";
 import { type MailWaiting } from "../../mail/marks.js";
 import { type AppIdentity } from "../../ports/app.js";
 import { type AnswerOutput } from "../envelope.js";
@@ -19,6 +19,8 @@ export interface ScheduleHost {
      * then runs only once enough of it waits, or the oldest has waited long enough.
      */
     newMail?: (command: Command, holder: string) => Promise<MailWaiting>;
+    /** What an agent is given on its stdin before its first turn; see `AgentInput`. */
+    agentInput?: AgentInput;
     /** The config file's settings for agent schedules; a schedule's own flags win, the defaults fill the rest. */
     limits?: (command: Command) => ScheduleLimits;
     /**
@@ -47,5 +49,5 @@ export declare const scheduleLimitsOf: (config: {
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
-export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, limits: configured, agentRuns, }: ScheduleHost) => Command;
+export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, agentInput, limits: configured, agentRuns, }: ScheduleHost) => Command;
 export {};

package/dist/cli/schedule/schedule-command.js

@@ -157,7 +157,7 @@ const runCapOf = (argv) => {
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
-export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: configured, agentRuns = [], }) => {
+export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentInput, limits: configured, agentRuns = [], }) => {
     const agentClis = [app, ...agentRuns];
     const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
     const prepare = (self, resolving = {}) => {
@@ -427,6 +427,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
             timer: timer(),
             agentRuns,
+            ...(agentInput ? { agentInput } : {}),
             ...(signal ? { signal } : {}),
         }));
         say(snakeKeys({ name, ...last }), [`${name}: exit ${last.exitCode} — ${last.output}`]);
@@ -462,6 +463,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, file, {
             timer: timer(),
             agentRuns,
+            ...(agentInput ? { agentInput } : {}),
             untilUnlocked: true,
             ...(signal ? { signal } : {}),
         }));

package/dist/entities/index.d.ts

@@ -9649,12 +9649,24 @@ export declare const ENTITIES: {
         readonly from: v.StringSchema<undefined>;
         readonly bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
     }, undefined>;
-    readonly store_restore: v.StrictObjectSchema<{
+    readonly store_restore: v.UnionSchema<[v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;
         readonly restored_from: v.StringSchema<undefined>;
         readonly kept_at: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
-    }, undefined>;
+    }, undefined>, v.StrictObjectSchema<{
+        readonly path: v.StringSchema<undefined>;
+        readonly restored_from: v.StringSchema<undefined>;
+        readonly rolled_back: v.LiteralSchema<true, undefined>;
+        readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly was: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly tables: v.ArraySchema<v.StrictObjectSchema<{
+            readonly table: v.StringSchema<undefined>;
+            readonly rows: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        }, undefined>, undefined>;
+        readonly rebuilt: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly foreign_key_violations: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>], undefined>;
     readonly store_reset: v.UnionSchema<[v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;
         readonly exists: v.LiteralSchema<false, undefined>;

package/dist/entities/store-maintenance.d.ts

@@ -344,12 +344,24 @@ export declare const storeDecrypt: v.StrictObjectSchema<{
     readonly from: v.StringSchema<undefined>;
     readonly bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
 }, undefined>;
-export declare const storeRestore: v.StrictObjectSchema<{
+export declare const storeRestore: v.UnionSchema<[v.StrictObjectSchema<{
     readonly path: v.StringSchema<undefined>;
     readonly restored_from: v.StringSchema<undefined>;
     readonly kept_at: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
-}, undefined>;
+}, undefined>, v.StrictObjectSchema<{
+    readonly path: v.StringSchema<undefined>;
+    readonly restored_from: v.StringSchema<undefined>;
+    readonly rolled_back: v.LiteralSchema<true, undefined>;
+    readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly was: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly tables: v.ArraySchema<v.StrictObjectSchema<{
+        readonly table: v.StringSchema<undefined>;
+        readonly rows: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>;
+    readonly rebuilt: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly foreign_key_violations: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>], undefined>;
 export declare const storeReset: v.UnionSchema<[v.StrictObjectSchema<{
     readonly path: v.StringSchema<undefined>;
     readonly exists: v.LiteralSchema<false, undefined>;

package/dist/entities/store-maintenance.js

@@ -155,12 +155,25 @@ export const storeBackup = v.strictObject({
     encrypted: v.optional(v.literal(true)),
 });
 export const storeDecrypt = v.strictObject({ path: text, from: text, bytes: count });
-export const storeRestore = v.strictObject({
-    path: text,
-    restored_from: text,
-    kept_at: v.nullable(text),
-    schema: count,
-});
+export const storeRestore = v.union([
+    v.strictObject({
+        path: text,
+        restored_from: text,
+        kept_at: v.nullable(text),
+        schema: count,
+    }),
+    /** From a rollback copy: its tables put back in place, the store returned to `schema` from `was`. */
+    v.strictObject({
+        path: text,
+        restored_from: text,
+        rolled_back: v.literal(true),
+        schema: count,
+        was: count,
+        tables: v.array(v.strictObject({ table: text, rows: count })),
+        rebuilt: v.array(text),
+        foreign_key_violations: count,
+    }),
+]);
 export const storeReset = v.union([
     v.strictObject({ ...absent.entries, reset: v.literal(false) }),
     v.strictObject({

package/dist/store/migrations.d.ts

@@ -1,9 +1,15 @@
 import type { CacheDatabase } from "./driver.js";
+import { type RollbackCopyOptions } from "./sqlite/rollback-copy.js";
 export interface Migration {
     version: number;
     /** The oldest schema version whose statements still work on a file at this version. */
     minCompatible: number;
     statements: string[];
+    /**
+     * The base tables it changes, by their names before it. Required when it raises `minCompatible`: they are copied
+     * aside before it runs, so `store restore` can take the store back to the version older tools still open.
+     */
+    tables?: string[];
     /** Runs before the statements, inside the same transaction. */
     before?: (database: CacheDatabase, now: () => number) => void;
 }
@@ -12,7 +18,8 @@ export interface Migration {
  * schema. **A migration that has reached anyone's file is never edited.** After it: forward-only and additive —
  * no `DROP` and no rebuild of a base table, a new column is nullable or has a default, and every `INSERT` in the
  * store names its columns — so an older `tg` keeps writing to a file a newer `max` has migrated. Only a breaking
- * change raises `minCompatible`, and that is a major version of this package. The search indexes are derived and
+ * change raises `minCompatible`, and that is a major version of this package; it names the base tables it changes
+ * (`tables`), which are copied aside before it runs (`sqlite/rollback-copy.ts`). The search indexes are derived and
  * may be dropped and rebuilt. Every version after the first gets a `version-N.test.ts` that opens a file at N-1.
  *
  * Times are epoch milliseconds: an integer sorts and ranges without a format to agree on.
@@ -24,11 +31,13 @@ export declare const MIGRATIONS: Migration[];
  * that fails names `store reset` when the app has one: without it the owner is stuck until a build that can migrate
  * the file. An app without that command (drive) passes no `command`, and the advice names none.
  */
-export declare const migrate: (database: CacheDatabase, { migrations, now, command, version, ownTable, }?: {
+export declare const migrate: (database: CacheDatabase, { migrations, now, command, version, ownTable, rollback, }?: {
     migrations?: Migration[];
     now?: () => number;
     command?: string;
     /** The CLI's own version: with `command`, it is recorded so a later upgrade can name who it locks out. */
     version?: string;
     ownTable?: string | null;
+    /** A store on disk: before a migration that raises `minCompatible`, a copy of the tables it changes. */
+    rollback?: RollbackCopyOptions;
 }) => string | undefined;

package/dist/store/migrations.js

@@ -1,12 +1,14 @@
 import { CliError } from "@wirecat/cli-base";
 import { lockedOutNotice, recordClient, refusalAdvice, storeClients } from "./sqlite/clients.js";
 import { generatedMigrations } from "./sqlite/manifest.js";
+import { discardRollbackCopy, recordRollbackCopy, takeRollbackCopy, } from "./sqlite/rollback-copy.js";
 /**
  * Every migration is generated by drizzle-kit and numbered in `sqlite/manifest.ts`. Version 1 creates the whole
  * schema. **A migration that has reached anyone's file is never edited.** After it: forward-only and additive —
  * no `DROP` and no rebuild of a base table, a new column is nullable or has a default, and every `INSERT` in the
  * store names its columns — so an older `tg` keeps writing to a file a newer `max` has migrated. Only a breaking
- * change raises `minCompatible`, and that is a major version of this package. The search indexes are derived and
+ * change raises `minCompatible`, and that is a major version of this package; it names the base tables it changes
+ * (`tables`), which are copied aside before it runs (`sqlite/rollback-copy.ts`). The search indexes are derived and
  * may be dropped and rebuilt. Every version after the first gets a `version-N.test.ts` that opens a file at N-1.
  *
  * Times are epoch milliseconds: an integer sorts and ranges without a format to agree on.
@@ -31,18 +33,44 @@ const fileState = (database) => {
         .get();
     return { version: Number(row?.version ?? 0), minCompatible: Number(row?.min_compatible ?? 0) };
 };
+/** The tables every pending migration that raises `minCompatible` names; none for a new file or a foreign one. */
+const copyBeforeBreaking = (database, migrations, { ownTable, now }, options) => {
+    if (!hasTable(database, "schema_migrations"))
+        return undefined;
+    const file = fileState(database);
+    if (file.version === 0 || (ownTable !== null && !hasTable(database, ownTable)))
+        return undefined;
+    let floor = file.minCompatible;
+    const tables = [];
+    for (const migration of migrations) {
+        if (migration.version <= file.version || migration.minCompatible <= floor)
+            continue;
+        floor = migration.minCompatible;
+        for (const table of migration.tables ?? [])
+            tables.push(table);
+    }
+    if (floor === file.minCompatible)
+        return undefined;
+    return takeRollbackCopy(database, { from: file.version, to: latest(migrations), tables, at: now() }, options);
+};
 /**
  * Brings the file up to this version, or opens a newer one it can still write to, or refuses.
  * Inside `BEGIN IMMEDIATE`, so two processes opening an old file at once migrate it once. A migration
  * that fails names `store reset` when the app has one: without it the owner is stuck until a build that can migrate
  * the file. An app without that command (drive) passes no `command`, and the advice names none.
  */
-export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, command, version, ownTable = OWN_TABLE, } = {}) => {
+export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, command, version, ownTable = OWN_TABLE, rollback, } = {}) => {
     const ours = latest(migrations);
+    let copy = rollback ? copyBeforeBreaking(database, migrations, { ownTable, now }, rollback) : undefined;
     database.exec("BEGIN IMMEDIATE");
     try {
         database.exec(HISTORY);
         const file = fileState(database);
+        // Another process migrated the file between the copy and this transaction, and took its own.
+        if (copy && copy.from !== file.version) {
+            discardRollbackCopy(copy);
+            copy = undefined;
+        }
         if (file.version > 0 && ownTable !== null && !hasTable(database, ownTable)) {
             throw new CliError("configuration_error", `the message store was written by another, incompatible tool (schema ${file.version} by its own numbering, ` +
                 "with no meetings table) — this tool will not open or change it; move it aside to start a new store");
@@ -73,6 +101,8 @@ export const migrate = (database, { migrations = MIGRATIONS, now = Date.now, com
         }
         if (command && version)
             recordClient(database, { command, version, speaks: ours }, now());
+        if (copy)
+            recordRollbackCopy(database, copy, now());
         database.exec("COMMIT");
         return notice;
     }

package/dist/store/sqlite/manifest.d.ts

@@ -11,6 +11,8 @@ export interface ManifestEntry {
     name: string;
     version: number;
     minCompatible: number;
+    /** Required on a version that raises `minCompatible`: the base tables it changes (`Migration.tables`). */
+    tables?: string[];
 }
 /** One migration creates the whole schema; every later one is added as the next version. */
 export declare const MANIFEST: ManifestEntry[];

package/dist/store/sqlite/manifest.js

@@ -1,4 +1,33 @@
 import { GENERATED } from "./migrations.generated.js";
+import { isDerivedTable } from "./rollback-copy.js";
+const V31_TABLES = [
+    "accounts",
+    "account_identities",
+    "agent_actions",
+    "aliases",
+    "attachments",
+    "bot_updates",
+    "chats",
+    "documents",
+    "email_threads",
+    "emails",
+    "facts",
+    "links",
+    "mail_rules",
+    "mailboxes",
+    "meeting_series",
+    "meetings",
+    "memories",
+    "messages",
+    "notes",
+    "projects",
+    "proposed_actions",
+    "reminders",
+    "store_settings",
+    "sync_cursors",
+    "syncs",
+    "taggings",
+];
 /** One migration creates the whole schema; every later one is added as the next version. */
 export const MANIFEST = [
     { name: "20261010184427_initial", version: 1, minCompatible: 1 },
@@ -36,14 +65,24 @@ export const MANIFEST = [
     { name: "20261021224625_version-28-chat-state", version: 28, minCompatible: 1 },
     { name: "20261023105057_version-29-transcript-words", version: 29, minCompatible: 1 },
     { name: "20261023105101_version-29-transcript-words-triggers", version: 29, minCompatible: 1 },
-    { name: "20261025064253_version-30-reviewed-tag-consolidation", version: 30, minCompatible: 30 },
+    {
+        name: "20261025064253_version-30-reviewed-tag-consolidation",
+        version: 30,
+        minCompatible: 30,
+        tables: ["tags", "auto_tag_claims"],
+    },
     { name: "20261025064302_version-30-resolved-tag-view", version: 30, minCompatible: 30 },
-    { name: "20261025070402_version-31-drive-account", version: 31, minCompatible: 31 },
-    { name: "20261025071848_version-32-files", version: 32, minCompatible: 32 },
+    { name: "20261025070402_version-31-drive-account", version: 31, minCompatible: 31, tables: V31_TABLES },
+    {
+        name: "20261025071848_version-32-files",
+        version: 32,
+        minCompatible: 32,
+        tables: ["accounts", "documents", "identities", "store_settings"],
+    },
     { name: "20261025071850_version-32-files-data", version: 32, minCompatible: 32 },
     { name: "20261025072643_version-33-calendars", version: 33, minCompatible: 32 },
     { name: "20261025072644_version-33-calendars-triggers", version: 33, minCompatible: 32 },
-    { name: "20261025182500_version-34-vector-index", version: 34, minCompatible: 34 },
+    { name: "20261025182500_version-34-vector-index", version: 34, minCompatible: 34, tables: [] },
     { name: "20261025182501_version-34-vector-index-triggers", version: 34, minCompatible: 34 },
     { name: "20261027102259_version-35-calendar-neutral", version: 35, minCompatible: 34 },
     { name: "20261027102302_version-35-calendar-neutral-data", version: 35, minCompatible: 34 },
@@ -83,12 +122,25 @@ export const generatedMigrations = (manifest = MANIFEST, generated = GENERATED)
         const last = migrations.at(-1);
         if (last && last.version !== entry.version && entry.minCompatible < last.minCompatible)
             throw new Error("migration minCompatible cannot decrease");
+        const derived = entry.tables?.filter(isDerivedTable) ?? [];
+        if (derived.length > 0)
+            throw new Error(`migration ${entry.version} names derived tables (${derived.join(", ")}); they are rebuilt, never copied`);
         if (last?.version !== entry.version) {
-            migrations.push({ version: entry.version, minCompatible: entry.minCompatible, statements: [...found.statements] });
+            if (last && entry.minCompatible > last.minCompatible && entry.tables === undefined)
+                throw new Error(`migration ${entry.version} raises minCompatible, so it names the base tables it changes (tables)`);
+            migrations.push({
+                version: entry.version,
+                minCompatible: entry.minCompatible,
+                statements: [...found.statements],
+                ...(entry.tables ? { tables: [...entry.tables] } : {}),
+            });
         }
         else if (last.minCompatible !== entry.minCompatible) {
             throw new Error(`the rows of version ${entry.version} disagree on minCompatible`);
         }
+        else if (entry.tables && JSON.stringify(entry.tables) !== JSON.stringify(last.tables)) {
+            throw new Error(`the rows of version ${entry.version} disagree on tables`);
+        }
         else {
             last.statements.push(...found.statements);
         }

package/dist/store/sqlite/open-store.d.ts

@@ -1,7 +1,7 @@
 import { type DecisionPolicy } from "../decisions.js";
 import { type StoreContext } from "./open.js";
 export interface StoreOptions {
-    /** Open an existing compatible store without maintenance; SQLite refuses writes. */
+    /** Open an existing compatible store without maintenance, migrating an older one first; SQLite refuses writes. */
     readOnly?: boolean;
     path?: string;
     env?: NodeJS.ProcessEnv;
@@ -16,4 +16,4 @@ export interface StoreOptions {
     decisions?: DecisionPolicy;
 }
 export declare const BACKFILL_ON_OPEN = 5000;
-export declare const openStoreContext: ({ path, env, now, command, version, warn, readOnly, decisions, }?: StoreOptions) => Promise<StoreContext>;
+export declare const openStoreContext: (options?: StoreOptions) => Promise<StoreContext>;

package/dist/store/sqlite/open-store.js

@@ -14,7 +14,8 @@ import { logPruner } from "./log-pruning.js";
 import { openSqlite } from "./open.js";
 import { movePaymentFacts } from "./payment-facts.js";
 import { loadProviders } from "./providers.js";
-import { assertReadCompatible } from "./read-compatibility.js";
+import { assertReadCompatible, readCompatibility } from "./read-compatibility.js";
+import { pruneRollbackCopies } from "./rollback-copy.js";
 import { stemsState } from "./stems.js";
 import { fillStems, followDefaultStemmers } from "./stems-fill.js";
 import { moveSuggestedLinks } from "./suggested-links.js";
@@ -35,7 +36,32 @@ const createWritable = (file) => {
         throw new CliError("permission_error", "the message store cannot be written from here; run where it is writable, or set MESSAGING_STORE", { reason: "store.not-writable" });
     }
 };
-export const openStoreContext = async ({ path, env, now = Date.now, command, version, warn = (line) => process.stderr.write(`${line}\n`), readOnly = false, decisions = DEFAULT_DECISION_POLICY, } = {}) => {
+// A new tool's first command may only read; it migrates the file as its first write would.
+const openReadable = async (file, options) => {
+    const first = await openSqlite(file, { readOnly: true });
+    try {
+        if (readCompatibility(first.database, options.command) === "current")
+            return first;
+    }
+    catch (error) {
+        first.database.close();
+        throw error;
+    }
+    first.database.close();
+    const writable = await openStoreContext({ ...options, path: file, readOnly: false });
+    writable.database.close();
+    const migrated = await openSqlite(file, { readOnly: true });
+    try {
+        assertReadCompatible(migrated.database, options.command);
+        return migrated;
+    }
+    catch (error) {
+        migrated.database.close();
+        throw error;
+    }
+};
+export const openStoreContext = async (options = {}) => {
+    const { path, env, now = Date.now, command, version, warn = (line) => process.stderr.write(`${line}\n`), readOnly = false, decisions = DEFAULT_DECISION_POLICY, } = options;
     if (typeof readOnly !== "boolean")
         throw new CliError("validation_error", "readOnly must be a boolean");
     await storeCapable();
@@ -47,15 +73,19 @@ export const openStoreContext = async ({ path, env, now = Date.now, command, ver
     }
     else
         createWritable(file);
-    const opened = await openSqlite(file, { readOnly });
+    const opened = readOnly ? await openReadable(file, options) : await openSqlite(file, { readOnly });
     const database = opened.database;
     try {
-        if (readOnly)
-            assertReadCompatible(database, command);
-        else {
-            const notice = migrate(database, { now, command, ...(version ? { version } : {}) });
+        if (!readOnly) {
+            const notice = migrate(database, {
+                now,
+                command,
+                ...(version ? { version } : {}),
+                rollback: { store: file, warn },
+            });
             if (notice)
                 warn(notice);
+            pruneRollbackCopies(database, now());
             fillFiles(database, now);
             fillFolded(database);
             fillJoinKeys(database);

package/dist/store/sqlite/read-compatibility.d.ts

@@ -1,2 +1,4 @@
 import type { CacheDatabase } from "../driver.js";
+/** "older" when the file needs migrating before a read-only open; throws for every file it may not read. */
+export declare const readCompatibility: (database: CacheDatabase, command?: string) => "current" | "older";
 export declare const assertReadCompatible: (database: CacheDatabase, command?: string) => void;

package/dist/store/sqlite/read-compatibility.js

@@ -1,7 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
 import { MIGRATIONS } from "../migrations.js";
 import { refusalAdvice, storeClients } from "./clients.js";
-export const assertReadCompatible = (database, command) => {
+/** "older" when the file needs migrating before a read-only open; throws for every file it may not read. */
+export const readCompatibility = (database, command) => {
     const ours = MIGRATIONS.at(-1)?.version ?? 0;
     if (!database.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_migrations'").get())
         throw new CliError("configuration_error", "The store has no schema history; initialize it explicitly before a read-only open");
@@ -15,8 +16,11 @@ export const assertReadCompatible = (database, command) => {
         minCompatible < 1 ||
         minCompatible > version)
         throw new CliError("configuration_error", "The store schema history is invalid; read-only opening cannot repair it");
-    if (version < ours)
-        throw new CliError("configuration_error", `The store needs schema ${ours} maintenance before a read-only open (found ${version})`);
     if (minCompatible > ours)
         throw new CliError("configuration_error", `The store requires schema ${minCompatible}, but this tool supports ${ours}; ${refusalAdvice(storeClients(database), command, version)}`);
+    return version < ours ? "older" : "current";
+};
+export const assertReadCompatible = (database, command) => {
+    if (readCompatibility(database, command) === "older")
+        throw new CliError("configuration_error", `The store needs schema ${MIGRATIONS.at(-1)?.version ?? 0} maintenance before a read-only open`);
 };

package/dist/store/sqlite/rollback-copy.d.ts

@@ -0,0 +1,49 @@
+import type { CacheDatabase } from "../driver.js";
+export declare const isDerivedTable: (name: string) => boolean;
+export interface RollbackCopyOptions {
+    /** The store's own path: the copy goes in `backups/` beside it. */
+    store: string;
+    freeBytes?: (dir: string) => number;
+    warn?: (line: string) => void;
+}
+export interface RollbackCopy {
+    path: string;
+    from: number;
+    to: number;
+}
+/**
+ * Outside the migration's transaction (SQLite cannot attach inside one), committed on its own, so a migration that
+ * fails leaves it whole. Never blocks the migration: no room, or any failure, is a warning and no copy.
+ */
+export declare const takeRollbackCopy: (database: CacheDatabase, { from, to, tables, at }: {
+    from: number;
+    to: number;
+    tables: string[];
+    at: number;
+}, { store, freeBytes, warn }: RollbackCopyOptions) => RollbackCopy | undefined;
+/** Inside the migration's transaction: a migration that fails never records its copy, so cleanup never takes it. */
+export declare const recordRollbackCopy: (database: CacheDatabase, copy: RollbackCopy, at: number) => void;
+export declare const discardRollbackCopy: (copy: RollbackCopy) => void;
+/**
+ * The day after: a copy recorded by a migration that committed, once the store is still at that version. Only the
+ * recorded file is deleted, never anything else in `backups/`.
+ */
+export declare const pruneRollbackCopies: (database: CacheDatabase, now: number) => void;
+export interface RollbackCopyMeta {
+    from: number;
+    to: number;
+    tables: string[];
+    createdAt: number;
+}
+export interface RollbackResult extends RollbackCopyMeta {
+    /** The schema the store was at before the rollback. */
+    was: number;
+    restored: {
+        table: string;
+        rows: number;
+    }[];
+    rebuilt: string[];
+    foreignKeyViolations: number;
+}
+/** Puts a rollback copy back into the store, in place. The caller makes sure nothing else has the store open. */
+export declare const rollBack: (database: CacheDatabase, path: string) => RollbackResult;

package/dist/store/sqlite/rollback-copy.js

@@ -0,0 +1,290 @@
+import { mkdirSync, rmSync, statfsSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, parse } from "node:path";
+import { CliError } from "@wirecat/cli-base";
+/**
+ * A breaking migration (one that raises `min_compatible`) locks older tools out of the store. Before it runs, the
+ * base tables it names are copied into a small file in `backups/` beside the store, with the whole schema as it was;
+ * `store restore <copy>` puts them back and returns the file to the old version. Derived tables are never copied:
+ * search indexes, their queues, vectors, chunks, mentions and involvements are rebuilt from the base tables.
+ */
+const DERIVED = /(_fts|_words|_stems|_trigrams|_pending)$|^(embeddings|chunks|chunk_messages|mentions|involvements|search_terms)$|^vector_index/;
+export const isDerivedTable = (name) => DERIVED.test(name);
+/**
+ * Always copied, a few rows each: migrations seed rows into them, and the next upgrade after a rollback would insert
+ * those rows again and fail on its own unique keys.
+ */
+const BOOKKEEPING = ["store_settings", "search_index_state"];
+const KEY = "rollback_copy:";
+const SCHEMA = "rollback_copy";
+const ROWID = "__rollback_rowid";
+const DAY_MS = 24 * 60 * 60 * 1000;
+// The migration's own write-ahead log needs room too.
+const HEADROOM = 256 * 1024 * 1024;
+const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+const megabytes = (bytes) => `${Math.ceil(bytes / 1024 / 1024)} MB`;
+const freeBytesOf = (dir) => {
+    const { bavail, bsize } = statfsSync(dir);
+    return Number(bavail) * Number(bsize);
+};
+const tableIn = (database, schema, name) => database.prepare(`SELECT 1 FROM ${schema}.sqlite_master WHERE type = 'table' AND name = ?`).get(name) !== undefined;
+const keepsRowid = (database, schema, table) => Number(database.prepare("SELECT wr FROM pragma_table_list WHERE schema = ? AND name = ?").get(schema, table)?.wr) ===
+    0;
+const columnsOf = (database, schema, table) => database
+    .prepare("SELECT name FROM pragma_table_info(?, ?)")
+    .all(table, schema)
+    .map((row) => String(row.name));
+const versionOf = (database) => Number(database.prepare("SELECT max(version) AS version FROM main.schema_migrations").get()?.version ?? 0);
+const tableBytes = (database, tables) => {
+    try {
+        return Number(database
+            .prepare(`SELECT coalesce(sum(pgsize), 0) AS bytes FROM dbstat
+           WHERE schema = 'main' AND aggregate = 1 AND name IN (${tables.map(() => "?").join(", ")})`)
+            .get(...tables)?.bytes ?? 0);
+    }
+    catch {
+        // Bun's SQLite is built without dbstat: the whole file is the bound.
+        const pragma = (name) => Number(database.prepare(`PRAGMA ${name}`).get()?.[name] ?? 0);
+        return pragma("page_count") * pragma("page_size");
+    }
+};
+const stampOf = (at) => new Date(at).toISOString().replace(/[:.]/g, "-");
+const attach = (database, path) => database.prepare(`ATTACH DATABASE ? AS ${SCHEMA}`).run(path);
+/**
+ * Outside the migration's transaction (SQLite cannot attach inside one), committed on its own, so a migration that
+ * fails leaves it whole. Never blocks the migration: no room, or any failure, is a warning and no copy.
+ */
+export const takeRollbackCopy = (database, { from, to, tables, at }, { store, freeBytes = freeBytesOf, warn = (line) => process.stderr.write(`${line}\n`) }) => {
+    const dir = join(dirname(store), "backups");
+    const present = [...new Set([...BOOKKEEPING, ...tables])].filter((table) => tableIn(database, "main", table));
+    const afterwards = `going back to schema ${from} then needs an empty store, and its data pulled again from the sources`;
+    let path;
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const needed = tableBytes(database, present);
+        const free = freeBytes(dir);
+        if (free < needed + HEADROOM) {
+            warn(`not enough free disk space for a rollback copy before schema ${to} (about ${megabytes(needed + HEADROOM)} ` +
+                `needed, ${megabytes(free)} free in ${dir}) — migrating without one; ${afterwards}`);
+            return undefined;
+        }
+        path = join(dir, `${parse(store).name}-rollback-schema-${from}-${stampOf(at)}.db`);
+        writeFileSync(path, "", { flag: "wx", mode: 0o600 });
+        attach(database, path);
+        try {
+            database.exec("BEGIN IMMEDIATE");
+            try {
+                const copied = versionOf(database);
+                database.exec(`CREATE TABLE ${SCHEMA}.rollback_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+                database.exec(`CREATE TABLE ${SCHEMA}.rollback_schema AS
+           SELECT m.type, m.name, m.tbl_name, m.sql, coalesce(l.type, m.type) AS kind
+           FROM main.sqlite_master m LEFT JOIN pragma_table_list l ON l.schema = 'main' AND l.name = m.name
+           ORDER BY m.rowid`);
+                for (const table of present) {
+                    const rowid = keepsRowid(database, "main", table) ? `rowid AS ${ROWID}, ` : "";
+                    database.exec(`CREATE TABLE ${SCHEMA}.${quote(table)} AS SELECT ${rowid}* FROM main.${quote(table)}`);
+                }
+                const meta = { from: copied, to, tables: present, created_at: at };
+                const insert = database.prepare(`INSERT INTO ${SCHEMA}.rollback_meta (key, value) VALUES (?, ?)`);
+                for (const [key, value] of Object.entries(meta))
+                    insert.run(key, JSON.stringify(value));
+                database.exec("COMMIT");
+                return { path, from: copied, to };
+            }
+            catch (error) {
+                database.exec("ROLLBACK");
+                throw error;
+            }
+        }
+        finally {
+            database.exec(`DETACH DATABASE ${SCHEMA}`);
+        }
+    }
+    catch (error) {
+        if (path)
+            rmSync(path, { force: true });
+        warn(`the rollback copy before schema ${to} could not be written (${error instanceof Error ? error.message : String(error)}) — migrating without one; ${afterwards}`);
+        return undefined;
+    }
+};
+/** Inside the migration's transaction: a migration that fails never records its copy, so cleanup never takes it. */
+export const recordRollbackCopy = (database, copy, at) => {
+    database
+        .prepare("INSERT OR REPLACE INTO store_settings (key, value, at) VALUES (?, ?, ?)")
+        .run(`${KEY}${basename(copy.path)}`, JSON.stringify({ path: copy.path, from: copy.from, to: copy.to, at }), at);
+};
+export const discardRollbackCopy = (copy) => rmSync(copy.path, { force: true });
+/**
+ * The day after: a copy recorded by a migration that committed, once the store is still at that version. Only the
+ * recorded file is deleted, never anything else in `backups/`.
+ */
+export const pruneRollbackCopies = (database, now) => {
+    const recorded = database
+        .prepare("SELECT key, value FROM store_settings WHERE key LIKE 'rollback\\_copy:%' ESCAPE '\\'")
+        .all();
+    if (recorded.length === 0)
+        return;
+    const version = versionOf(database);
+    for (const { key, value } of recorded) {
+        let copy;
+        try {
+            copy = JSON.parse(String(value));
+        }
+        catch {
+            continue;
+        }
+        if (typeof copy.path !== "string" || now - Number(copy.at) < DAY_MS || version < Number(copy.to))
+            continue;
+        if (!database.prepare("SELECT 1 FROM schema_migrations WHERE version = ?").get(Number(copy.to)))
+            continue;
+        rmSync(copy.path, { force: true });
+        database.prepare("DELETE FROM store_settings WHERE key = ?").run(String(key));
+    }
+};
+const objectsOf = (database, sql) => database
+    .prepare(sql)
+    .all()
+    .map((row) => ({
+    type: String(row.type),
+    name: String(row.name),
+    sql: row.sql === null ? null : String(row.sql),
+    kind: String(row.kind),
+}));
+const currentObjects = (database) => objectsOf(database, `SELECT m.type, m.name, m.sql, coalesce(l.type, m.type) AS kind
+     FROM main.sqlite_master m LEFT JOIN pragma_table_list l ON l.schema = 'main' AND l.name = m.name`);
+const internal = ({ name, kind }) => name.startsWith("sqlite_") || kind === "shadow";
+const metaOf = (database) => {
+    const values = new Map(database
+        .prepare(`SELECT key, value FROM ${SCHEMA}.rollback_meta`)
+        .all()
+        .map((row) => [String(row.key), JSON.parse(String(row.value))]));
+    const tables = values.get("tables");
+    return {
+        from: Number(values.get("from")),
+        to: Number(values.get("to")),
+        tables: Array.isArray(tables) ? tables.map(String) : [],
+        createdAt: Number(values.get("created_at")),
+    };
+};
+/** FTS5 tables over a table's own rows; the other search indexes hold their own text and wait for `store rebuild`. */
+const contentOf = (sql) => /\bcontent\s*=\s*'([^']+)'/i.exec(sql ?? "")?.[1];
+const RANK = { table: 0, index: 1, view: 2, trigger: 3 };
+/**
+ * Returns the file to the schema the copy saved: every object made since is dropped, every table the migration
+ * changed is put back with its rows, a table only extended since is rebuilt to its old shape, and the history
+ * goes back to the copy's version. One transaction: on any failure the store is as it was.
+ */
+const rewind = (database, saved, named) => {
+    const before = new Map(saved.map((object) => [object.name, object]));
+    const same = (object) => before.get(object.name)?.type === object.type && before.get(object.name)?.sql === object.sql;
+    const touched = new Set(named);
+    const rebuilt = [];
+    // A trigger or view over a table dropped or rebuilt below would point nowhere; all of them come back from the copy.
+    for (const object of currentObjects(database)) {
+        if (object.type === "trigger")
+            database.exec(`DROP TRIGGER IF EXISTS ${quote(object.name)}`);
+        if (object.type === "view")
+            database.exec(`DROP VIEW IF EXISTS ${quote(object.name)}`);
+        if (object.type === "index" && object.sql !== null && !same(object))
+            database.exec(`DROP INDEX IF EXISTS ${quote(object.name)}`);
+    }
+    for (const object of currentObjects(database)) {
+        if (object.type !== "table" || internal(object))
+            continue;
+        const old = before.get(object.name);
+        if (named.has(object.name) || !old || (object.kind === "virtual" && !same(object))) {
+            database.exec(`DROP TABLE ${quote(object.name)}`);
+        }
+        else if (!same(object) && old.sql) {
+            rebuild(database, object.name, old.sql);
+            rebuilt.push(object.name);
+            touched.add(object.name);
+        }
+    }
+    const present = new Set(currentObjects(database).map(({ name }) => name));
+    const missing = saved
+        .filter((object) => !internal(object) && object.sql !== null && !present.has(object.name))
+        .sort((a, b) => (RANK[a.type] ?? 9) - (RANK[b.type] ?? 9));
+    for (const object of missing) {
+        database.exec(object.sql);
+        if (object.type === "table" && named.has(object.name))
+            restoreRows(database, object.name);
+        if (object.kind === "virtual")
+            touched.add(object.name);
+    }
+    for (const object of saved) {
+        const content = contentOf(object.sql);
+        if (object.kind !== "virtual" || !(content && (touched.has(content) || touched.has(object.name))))
+            continue;
+        database.exec(`INSERT INTO ${quote(object.name)} (${quote(object.name)}) VALUES ('rebuild')`);
+    }
+    return rebuilt;
+};
+const rebuild = (database, table, sql) => {
+    const aside = `__rollback_${table}`;
+    database.exec(`ALTER TABLE ${quote(table)} RENAME TO ${quote(aside)}`);
+    database.exec(sql);
+    const kept = new Set(columnsOf(database, "main", aside));
+    const columns = columnsOf(database, "main", table).filter((column) => kept.has(column));
+    const rowid = keepsRowid(database, "main", table) ? ["rowid"] : [];
+    const list = [...rowid, ...columns.map(quote)].join(", ");
+    database.exec(`INSERT INTO ${quote(table)} (${list}) SELECT ${list} FROM ${quote(aside)}`);
+    database.exec(`DROP TABLE ${quote(aside)}`);
+};
+const restoreRows = (database, table) => {
+    const copied = new Set(columnsOf(database, SCHEMA, table));
+    const columns = columnsOf(database, "main", table).filter((column) => copied.has(column));
+    const rowid = keepsRowid(database, "main", table) && copied.has(ROWID);
+    const into = [...(rowid ? ["rowid"] : []), ...columns.map(quote)].join(", ");
+    const from = [...(rowid ? [ROWID] : []), ...columns.map(quote)].join(", ");
+    database.exec(`INSERT INTO main.${quote(table)} (${into}) SELECT ${from} FROM ${SCHEMA}.${quote(table)}`);
+};
+/** Puts a rollback copy back into the store, in place. The caller makes sure nothing else has the store open. */
+export const rollBack = (database, path) => {
+    attach(database, path);
+    let result;
+    try {
+        if (!tableIn(database, SCHEMA, "rollback_meta"))
+            throw new CliError("validation_error", `${path} is not a rollback copy`);
+        const meta = metaOf(database);
+        const was = versionOf(database);
+        if (!database.prepare("SELECT 1 FROM main.schema_migrations WHERE version = ?").get(meta.to)) {
+            throw new CliError("validation_error", `the store is at schema ${was} and was never migrated to ${meta.to}, the schema this copy was taken before — nothing to roll back`);
+        }
+        const saved = objectsOf(database, `SELECT type, name, sql, kind FROM ${SCHEMA}.rollback_schema ORDER BY rowid`);
+        database.exec("PRAGMA foreign_keys = OFF");
+        // Renaming a table aside must not rewrite the references other tables hold to it.
+        database.exec("PRAGMA legacy_alter_table = ON");
+        try {
+            database.exec("BEGIN IMMEDIATE");
+            try {
+                const named = new Set(meta.tables);
+                const rebuilt = rewind(database, saved, named);
+                database.prepare("DELETE FROM main.schema_migrations WHERE version > ?").run(meta.from);
+                database.prepare("DELETE FROM main.store_settings WHERE key = ?").run(`${KEY}${basename(path)}`);
+                database.exec("COMMIT");
+                const count = (table) => Number(database.prepare(`SELECT count(*) AS n FROM main.${quote(table)}`).get()?.n ?? 0);
+                result = {
+                    ...meta,
+                    was,
+                    restored: meta.tables.map((table) => ({ table, rows: count(table) })),
+                    rebuilt,
+                };
+            }
+            catch (error) {
+                database.exec("ROLLBACK");
+                throw error;
+            }
+        }
+        finally {
+            database.exec("PRAGMA legacy_alter_table = OFF");
+            database.exec("PRAGMA foreign_keys = ON");
+        }
+    }
+    finally {
+        database.exec(`DETACH DATABASE ${SCHEMA}`);
+    }
+    // Only the tables put back: a check of the whole store reads every row of it.
+    const checked = [...result.restored.map(({ table }) => table), ...result.rebuilt];
+    const foreignKeyViolations = checked.reduce((total, table) => total + database.prepare(`PRAGMA foreign_key_check(${quote(table)})`).all().length, 0);
+    return { ...result, foreignKeyViolations };
+};

package/dist/store/store.d.ts

@@ -133,6 +133,7 @@ export interface MessageStore {
 export type { ChatHistoryShape, StoredHistorySkip } from "./sqlite/history-skips.js";
 export { BACKFILL_ON_OPEN, type StoreOptions } from "./sqlite/open-store.js";
 export type { ChatScope, NewestMessage, ReplyDelay, WaitingChat } from "./sqlite/reply-times.js";
+export { rollBack } from "./sqlite/rollback-copy.js";
 export { fileFacts, readStoreTables, type TableKind } from "./sqlite/store-tables.js";
 export declare const openStore: (options?: StoreOptions) => Promise<MessageStore>;
 export * from "./exports.js";

package/dist/store/store.js

@@ -50,6 +50,7 @@ import { syncStoreOver } from "./sync.js";
 import { tagsStoreOver } from "./tags.js";
 import { accountVectorsOver, vectorsStoreOver } from "./vectors.js";
 export { BACKFILL_ON_OPEN } from "./sqlite/open-store.js";
+export { rollBack } from "./sqlite/rollback-copy.js";
 export { fileFacts, readStoreTables } from "./sqlite/store-tables.js";
 export const openStore = async (options = {}) => {
     const context = await openStoreContext(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.594.0",
+  "version": "0.596.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -13,6 +13,12 @@
     "url": "https://github.com/WireCatLabs/cli-core/issues"
   },
   "type": "module",
+  "wirecat": {
+    "store": {
+      "speaks": 53,
+      "minCompatible": 34
+    }
+  },
   "engines": {
     "node": "^22.16.0 || >=24"
   },