@aligndottech/cli 0.49.0 → 0.50.0

package/dist/lib/sync/forget.js

@@ -0,0 +1,32 @@
+/**
+ * L5: what `align local forget <source>` does to the graph, beside dropping the token.
+ * Without `--purge`: the source's sync rows and item state go (its window and watermark mean nothing
+ * without a token) and the imported items stay; the caller is told how many. With `--purge`: the
+ * items nobody has vouched for go too (purge.ts says which are kept and why).
+ *
+ * ONE transaction: a failure leaves the graph as it was, and the caller drops the token only after
+ * this returns, so a failed forget never leaves a token-less source with half its state.
+ */
+import fs from 'node:fs';
+import { createLocalDb } from '../local-db.js';
+import { isPurgeable, previewIn, purgeIn } from './purge.js';
+import { transact } from './sync-state.js';
+export function forgetSourceData(dbPath, source, o) {
+    // A graph that does not exist has nothing to forget, and opening it would create it.
+    if (dbPath === undefined || !fs.existsSync(dbPath))
+        return { syncRowsRemoved: 0, staying: 0, ...(o.purge ? { purged: { deleted: 0, kept: 0 } } : {}) };
+    if (o.purge && !isPurgeable(source))
+        throw new Error(`"${source.slice(0, 24)}" is not a connector source, so nothing was purged.`);
+    // Opening through the one opener migrates an older file (the tables below exist) and refuses a newer one.
+    createLocalDb(dbPath).close();
+    return transact(dbPath, (db) => {
+        const syncRowsRemoved = Number(db.prepare('DELETE FROM source_sync WHERE source_id = ?').run(source).changes);
+        db.prepare('DELETE FROM sync_item_state WHERE platform = ?').run(source);
+        if (o.purge) {
+            const purged = purgeIn(db, source);
+            return { syncRowsRemoved, purged, staying: purged.kept };
+        }
+        return { syncRowsRemoved, staying: previewIn(db, source).total };
+    });
+}
+//# sourceMappingURL=forget.js.map

package/dist/lib/sync/forget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forget.js","sourceRoot":"","sources":["../../../src/lib/sync/forget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAoB,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAU3C,MAAM,UAAU,gBAAgB,CAAC,MAA0B,EAAE,MAAc,EAAE,CAAqB;IAChG,qFAAqF;IACrF,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACvJ,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,qDAAqD,CAAC,CAAC;IACnI,0GAA0G;IAC1G,aAAa,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;IAC9B,OAAO,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;QAC7B,MAAM,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,6CAA6C,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;QAC9G,EAAE,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YACnC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/sync/launch-hook.d.ts

@@ -0,0 +1,42 @@
+import { type SyncSummary } from './summary-read.js';
+export declare const BACKGROUND_SYNC_NOTICE = "Align refreshes your connected sources in the background when you start it, at most every 15 minutes per source. Turn off: align sync --off";
+export interface BackgroundSyncConfig {
+    isBackgroundSyncOff?(): boolean;
+    backgroundSyncNoticeShown?(): boolean;
+    markBackgroundSyncNoticeShown?(at: string): void;
+    getReauthLineShownAt?(): string | undefined;
+    markReauthLineShown?(at: string): void;
+}
+/** The parts that touch the disk or start a process. Tests replace them; the defaults are rooted at the host's env and home. */
+export interface BackgroundSyncIo {
+    readSummary(): SyncSummary | undefined;
+    /** Is a sync or a backfill running for this source right now? */
+    busy(source: string): boolean;
+    inCi(): boolean;
+    /**
+     * Take the per-source claim for this interval, atomically (an exclusive create). False when another launch holds a
+     * fresh one, or the claim cannot be written: then nothing starts for that source. Concurrent launches inside the child's
+     * 20 s delay therefore start ONE child, not one each.
+     */
+    claim(source: string): boolean;
+    releaseClaim(source: string): void;
+    /** Fire and forget. The launcher never awaits what this returns. */
+    start(sources: string[]): unknown;
+    nowMs(): number;
+}
+export interface BackgroundSyncHost {
+    env: Record<string, string | undefined>;
+    home: string;
+    platform: string;
+    isTTY: boolean;
+    config: BackgroundSyncConfig;
+    err(line: string): void;
+    io?: Partial<BackgroundSyncIo>;
+}
+export interface BackgroundPlan {
+    sources: string[];
+    reauth: string[];
+}
+export declare function planBackgroundSync(h: BackgroundSyncHost): BackgroundPlan;
+export declare function applyBackgroundPlan(plan: BackgroundPlan, h: BackgroundSyncHost): void;
+//# sourceMappingURL=launch-hook.d.ts.map

package/dist/lib/sync/launch-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-hook.d.ts","sourceRoot":"","sources":["../../../src/lib/sync/launch-hook.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE,eAAO,MAAM,sBAAsB,gJAC4G,CAAC;AAEhJ,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,CAAC,IAAI,OAAO,CAAC;IAChC,yBAAyB,CAAC,IAAI,OAAO,CAAC;IACtC,6BAA6B,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,oBAAoB,CAAC,IAAI,MAAM,GAAG,SAAS,CAAC;IAC5C,mBAAmB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,gIAAgI;AAChI,MAAM,WAAW,gBAAgB;IAC/B,WAAW,IAAI,WAAW,GAAG,SAAS,CAAC;IACvC,iEAAiE;IACjE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,IAAI,IAAI,OAAO,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAClC,KAAK,IAAI,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,EAAE,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAAG,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE;AA2BvE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAuBxE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAkCrF"}

package/dist/lib/sync/launch-hook.js

@@ -0,0 +1,117 @@
+/**
+ * L6: the launch-time background refresh (Decisions 8, 9, 23). Called from launchIfChosen in two
+ * halves so the launch cost line stays honest:
+ *
+ *  - `planBackgroundSync` DECIDES. Read-only: one small JSON file, a lock file per due source, nothing
+ *    else. It runs before the overhead trace line, so its time is in the number the budget gates.
+ *  - `applyBackgroundPlan` ACTS: prints the two lines, records that it did, and starts the detached
+ *    child without waiting for it. It runs only after the dry-run exit, because a dry run measures
+ *    and must not change the machine.
+ *
+ * Imports are deliberately small (no database layer, no fetcher, no setup.ts):
+ * launch-path-imports.test.ts walks them. Nothing here throws into the launcher: a failure to
+ * decide or to start means no refresh this time, and the agent opens exactly as it would have.
+ */
+import path from 'node:path';
+import { alignStateDirPath, liveBackfills, pidAlive } from '../backfill-state.js';
+import { inCi } from '../telemetry-ci.js';
+import { claimInForce, releaseClaim, takeClaim } from './bg-claim.js';
+import { lockHolder } from './lock.js';
+import { BACKGROUND_LAUNCH_DELAY_SECONDS, REAUTH_LINE_INTERVAL_MS, reauthSources, shouldBackgroundSync, SYNC_MIN_INTERVAL_MS } from './should-background-sync.js';
+import { startSyncChild } from './spawn-background.js';
+import { readSummary } from './summary-read.js';
+export const BACKGROUND_SYNC_NOTICE = 'Align refreshes your connected sources in the background when you start it, at most every 15 minutes per source. Turn off: align sync --off';
+const EMPTY = { sources: [], reauth: [] };
+const set = (v) => v !== undefined && v !== '';
+function defaultIo(h) {
+    const stateDir = alignStateDirPath(h.env, h.home, h.platform);
+    // Read once per launch, however many sources are due.
+    let backfills;
+    const runningBackfills = () => (backfills ??= liveBackfills(path.join(stateDir, 'backfill'), pidAlive));
+    return {
+        readSummary: () => readSummary(stateDir),
+        busy: (source) => lockHolder(`sync-${source}`, { dir: stateDir }) !== undefined
+            || runningBackfills().some((s) => s.source === source)
+            || claimInForce(stateDir, source, Date.now(), SYNC_MIN_INTERVAL_MS),
+        inCi: () => inCi(h.env),
+        // Skip, never block: a claim that cannot be recorded (an object in the way, an unwritable directory) means no start for that source,
+        // and `align sync --status` says why.
+        claim: (source) => takeClaim(stateDir, source, Date.now(), SYNC_MIN_INTERVAL_MS).ok,
+        releaseClaim: (source) => releaseClaim(stateDir, source, Date.now(), SYNC_MIN_INTERVAL_MS),
+        start: (sources) => startSyncChild(sources, { delaySeconds: BACKGROUND_LAUNCH_DELAY_SECONDS, env: h.env, caller: 'launcher' }),
+        nowMs: () => Date.now(),
+    };
+}
+const ioOf = (h) => ({ ...defaultIo(h), ...h.io });
+export function planBackgroundSync(h) {
+    try {
+        // The cheap gates first: most launches outside a terminal, or with the switch set, read nothing.
+        if (!h.isTTY || set(h.env['ALIGN_WRAPPED']) || set(h.env['ALIGN_NO_SYNC']))
+            return EMPTY;
+        if (h.config.isBackgroundSyncOff?.() === true)
+            return EMPTY;
+        const io = ioOf(h);
+        const summary = io.readSummary();
+        if (summary === undefined)
+            return EMPTY;
+        const now = io.nowMs();
+        const gates = { isTty: h.isTTY, wrapped: false, noSync: false, disabled: false, summary, now };
+        // `ci` is asked only when something is due, and `busy` only for what is due.
+        let sources = shouldBackgroundSync({ ...gates, ci: false, minIntervalMs: SYNC_MIN_INTERVAL_MS });
+        if (sources.length > 0) {
+            const busy = new Set(sources.filter((s) => io.busy(s)));
+            sources = io.inCi() ? [] : shouldBackgroundSync({ ...gates, ci: false, minIntervalMs: SYNC_MIN_INTERVAL_MS, busy });
+        }
+        let reauth = reauthSources({ ...gates, ci: false, lastShownAt: h.config.getReauthLineShownAt?.(), intervalMs: REAUTH_LINE_INTERVAL_MS });
+        if (reauth.length > 0 && io.inCi())
+            reauth = [];
+        return { sources, reauth };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+export function applyBackgroundPlan(plan, h) {
+    try {
+        const io = ioOf(h);
+        const stamp = () => new Date(io.nowMs()).toISOString();
+        // Mark first and print only if the mark held: a config that cannot be written would otherwise repeat the line every launch.
+        if (plan.reauth.length > 0) {
+            try {
+                h.config.markReauthLineShown?.(stamp());
+                const s = plan.reauth.length === 1;
+                h.err(`Align cannot refresh ${plan.reauth.join(', ')}: ${s ? 'its' : 'their'} saved login stopped working. Reconnect: align connect ${plan.reauth[0]}`);
+            }
+            catch { /* an unwritable config: no line this time, and no repeat */ }
+        }
+        if (plan.sources.length === 0)
+            return;
+        if (h.config.backgroundSyncNoticeShown?.() !== true) {
+            try {
+                h.config.markBackgroundSyncNoticeShown?.(stamp());
+            }
+            catch {
+                return; // the first-use line cannot be recorded, so it is not shown and nothing starts undisclosed
+            }
+            h.err(BACKGROUND_SYNC_NOTICE);
+        }
+        // Only the sources whose claim THIS launch took: a concurrent launch already started those.
+        const claimed = plan.sources.filter((s) => io.claim(s));
+        if (claimed.length === 0)
+            return;
+        // Not awaited: the agent must not wait for a process to be confirmed. A start that fails gives the claim back.
+        const release = () => { for (const s of claimed)
+            io.releaseClaim(s); };
+        try {
+            void Promise.resolve(io.start(claimed)).then((r) => { if (r?.ok === false)
+                release(); }, release);
+        }
+        catch {
+            release();
+        }
+    }
+    catch {
+        // No refresh this time; the launch goes on.
+    }
+}
+//# sourceMappingURL=launch-hook.js.map

package/dist/lib/sync/launch-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-hook.js","sourceRoot":"","sources":["../../../src/lib/sync/launch-hook.ts"],"names":[],"mappings":"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"}

package/dist/lib/sync/lock.d.ts

@@ -0,0 +1,35 @@
+export declare const LOCK_STALE_MS: number;
+export interface LockBody {
+    pid: number;
+    started_at: string;
+    at: number;
+    nonce: string;
+}
+export type Lock = {
+    ok: true; /** Is the lock file still mine? False after a takeover or a release. */
+    owned(): boolean;
+    touch(): void;
+    release(): void;
+}
+/** `holder` is absent when the lock could not be taken for a reason that names no process. */
+ | {
+    ok: false;
+    holder?: {
+        pid: number;
+        started_at: string;
+    };
+};
+export interface LockOptions {
+    dir?: string;
+    pid?: number;
+    now?: () => number;
+    alive?: (pid: number) => boolean;
+}
+export declare function lockFile(dir: string, name: string): string;
+export declare function acquireLock(name: string, o?: LockOptions): Lock;
+/** Who holds this lock right now (a live pid, touched within 30 minutes), or undefined. Reads only: it never takes the lock. */
+export declare function lockHolder(name: string, o?: LockOptions): {
+    pid: number;
+    started_at: string;
+} | undefined;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lib/sync/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/lib/sync/lock.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,aAAa,QAAc,CAAC;AAKzC,MAAM,WAAW,QAAQ;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAExF,MAAM,MAAM,IAAI,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC,CAAC,wEAAwE;IAAC,KAAK,IAAI,OAAO,CAAC;IAAC,KAAK,IAAI,IAAI,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE;AACzI,8FAA8F;GAC5F;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1D;AAuCD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,WAAgB,GAAG,IAAI,CAkEnE;AAED,gIAAgI;AAChI,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE,WAAgB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAO7G"}

package/dist/lib/sync/lock.js

@@ -0,0 +1,175 @@
+/**
+ * L5: the sync lock. One writer per source, across processes, on every OS.
+ *
+ * A lock is a small file created ATOMICALLY WITH ITS CONTENT: the body is written to a private
+ * temp file and hard-linked into place, and link fails if the name exists, so a reader never sees a
+ * half-written lock and two processes cannot both create it. (A filesystem without hard links
+ * falls back to the exclusive-create flag.) It holds the pid, the start time and a nonce. It is
+ * STALE when its pid is gone or it has not been touched for 30 minutes (a pid can be reused, and a
+ * run quiet for half an hour has stopped). A lock file that cannot be read is NOT stale until its
+ * own modified time is 30 minutes old: a corrupt file is more likely a peer mid-write than a corpse.
+ *
+ * Takeover is serialised by a guard file (`<lock>.takeover`, exclusive create): one process at a
+ * time judges a lock stale, removes it and creates its own, and it re-reads the lock after taking
+ * the guard so it removes only the lock it judged. A second process arriving meanwhile is told the
+ * lock is held, which is the safe answer.
+ *
+ * A holder can still lose its lock (a laptop asleep past 30 minutes, then a peer took over). The
+ * holder therefore asks `owned()` before every batch it commits and before it records its result,
+ * and stops if the answer is no: at worst one batch of idempotent upserts overlaps.
+ */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { alignStateDir, pidAlive } from '../backfill-state.js';
+import { readRegularFile } from './safe-read.js';
+export const LOCK_STALE_MS = 30 * 60_000;
+/** A takeover guard is held for microseconds; one older than this is a corpse. */
+const GUARD_STALE_MS = 10_000;
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+export function lockFile(dir, name) {
+    if (!NAME.test(name))
+        throw new Error(`Not a valid lock name: ${JSON.stringify(name.slice(0, 40))}`);
+    return path.join(dir, `${name}.lock`);
+}
+function read(file) {
+    const raw = readRegularFile(file, 4096);
+    if (raw === undefined)
+        return undefined;
+    try {
+        const b = JSON.parse(raw);
+        if (Number.isInteger(b.pid) && typeof b.at === 'number' && typeof b.started_at === 'string' && typeof b.nonce === 'string')
+            return { raw, body: b };
+    }
+    catch { /* not a lock body */ }
+    return { raw, body: undefined };
+}
+function ageOf(file, now) {
+    try {
+        return now - fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/** Create `file` holding `body` in one atomic step, or report that it exists. */
+function createWhole(file, body, tag) {
+    const tmp = `${file}.tmp.${tag}`;
+    fs.writeFileSync(tmp, body, { mode: 0o600 });
+    try {
+        fs.linkSync(tmp, file);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'EEXIST')
+            return false;
+        // No hard links here (some network and FAT filesystems): the exclusive-create flag is the next best atomic.
+        try {
+            fs.writeFileSync(file, body, { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+        catch (e2) {
+            if (e2.code === 'EEXIST')
+                return false;
+            throw e2;
+        }
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+}
+export function acquireLock(name, o = {}) {
+    const dir = o.dir ?? alignStateDir();
+    if (dir === null)
+        return { ok: false };
+    const file = lockFile(dir, name);
+    const pid = o.pid ?? process.pid;
+    const now = o.now ?? Date.now;
+    const alive = o.alive ?? pidAlive;
+    const mine = { pid, started_at: new Date(now()).toISOString(), at: now(), nonce: randomBytes(8).toString('hex') };
+    const create = () => createWhole(file, JSON.stringify(mine), `${pid}.${mine.nonce}`);
+    const held = (seen) => (seen?.body ? { ok: false, holder: { pid: seen.body.pid, started_at: seen.body.started_at } } : { ok: false });
+    /** Is what we read a lock somebody may still be using? */
+    const live = (seen) => seen.body !== undefined ? alive(seen.body.pid) && now() - seen.body.at <= LOCK_STALE_MS : ageOf(file, now()) <= LOCK_STALE_MS;
+    if (!create()) {
+        const seen = read(file);
+        if (seen === undefined) {
+            // Gone between our create and our read: its holder just released it. One more try decides.
+            if (!create())
+                return { ok: false };
+        }
+        else if (live(seen)) {
+            return held(seen);
+        }
+        else {
+            const guard = `${file}.takeover`;
+            const guardBody = JSON.stringify({ pid, at: now() });
+            let guarded = false;
+            for (let attempt = 0; attempt < 2 && !guarded; attempt++) {
+                try {
+                    fs.writeFileSync(guard, guardBody, { flag: 'wx', mode: 0o600 });
+                    guarded = true;
+                }
+                catch (e) {
+                    if (e.code !== 'EEXIST')
+                        throw e;
+                    if (ageOf(guard, now()) <= GUARD_STALE_MS)
+                        return { ok: false }; // somebody is taking it over right now
+                    fs.rmSync(guard, { force: true });
+                }
+            }
+            if (!guarded)
+                return { ok: false };
+            try {
+                const again = read(file);
+                // Only the lock we judged stale may be removed. Anything else is a peer's: leave it.
+                if (again !== undefined && again.raw !== seen.raw)
+                    return held(again);
+                if (again !== undefined)
+                    fs.rmSync(file, { force: true });
+                if (!create())
+                    return { ok: false };
+            }
+            finally {
+                fs.rmSync(guard, { force: true });
+            }
+        }
+    }
+    const ownsIt = () => read(file)?.body?.nonce === mine.nonce;
+    return {
+        ok: true,
+        owned: ownsIt,
+        touch() {
+            if (!ownsIt())
+                return;
+            const tmp = `${file}.touch.${pid}.${mine.nonce}`;
+            try {
+                fs.writeFileSync(tmp, JSON.stringify({ ...mine, at: now() }), { mode: 0o600 });
+                fs.renameSync(tmp, file);
+            }
+            catch {
+                fs.rmSync(tmp, { force: true }); /* the next touch will try again */
+            }
+        },
+        release() {
+            if (!ownsIt())
+                return;
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch { /* a stale lock is taken over after 30 minutes */ }
+        },
+    };
+}
+/** Who holds this lock right now (a live pid, touched within 30 minutes), or undefined. Reads only: it never takes the lock. */
+export function lockHolder(name, o = {}) {
+    const dir = o.dir ?? alignStateDir();
+    if (dir === null)
+        return undefined;
+    const body = read(lockFile(dir, name))?.body;
+    const now = o.now ?? Date.now;
+    const alive = o.alive ?? pidAlive;
+    return body !== undefined && alive(body.pid) && now() - body.at <= LOCK_STALE_MS ? { pid: body.pid, started_at: body.started_at } : undefined;
+}
+//# sourceMappingURL=lock.js.map

package/dist/lib/sync/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/lib/sync/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,GAAG,MAAM,CAAC;AACzC,kFAAkF;AAClF,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,IAAI,GAAG,sBAAsB,CAAC;AAgBpC,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAY;IAChD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAC;QAC/C,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAa,EAAE,CAAC;IAClK,CAAC;IAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,KAAK,CAAC,IAAY,EAAE,GAAW;IACtC,IAAI,CAAC;QAAC,OAAO,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAAC,CAAC;AAC5F,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,GAAW;IAC1D,MAAM,GAAG,GAAG,GAAG,IAAI,QAAQ,GAAG,EAAE,CAAC;IACjC,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,GAAI,CAAuB,CAAC,IAAI,CAAC;QAC3C,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpC,4GAA4G;QAC5G,IAAI,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1D,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACZ,IAAK,EAAwB,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAC9D,MAAM,EAAE,CAAC;QACX,CAAC;IACH,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAiB,EAAE;IAC3D,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;IACrC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACjC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;IAClC,MAAM,IAAI,GAAa,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IAC5H,MAAM,MAAM,GAAG,GAAY,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAE9F,MAAM,IAAI,GAAG,CAAC,IAA6B,EAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACrK,0DAA0D;IAC1D,MAAM,IAAI,GAAG,CAAC,IAA0C,EAAW,EAAE,CACnE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,aAAa,CAAC;IAEhI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,2FAA2F;YAC3F,IAAI,CAAC,MAAM,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QACtC,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,GAAG,IAAI,WAAW,CAAC;YACjC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACrD,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;gBACzD,IAAI,CAAC;oBACH,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBAChE,OAAO,GAAG,IAAI,CAAC;gBACjB,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAK,CAAuB,CAAC,IAAI,KAAK,QAAQ;wBAAE,MAAM,CAAC,CAAC;oBACxD,IAAI,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc;wBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,uCAAuC;oBACxG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YACD,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;gBACzB,qFAAqF;gBACrF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG;oBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;gBACtE,IAAI,KAAK,KAAK,SAAS;oBAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC1D,IAAI,CAAC,MAAM,EAAE;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;YACtC,CAAC;oBAAS,CAAC;gBACT,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;IACrE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,MAAM;QACb,KAAK;YACH,IAAI,CAAC,MAAM,EAAE;gBAAE,OAAO;YACtB,MAAM,GAAG,GAAG,GAAG,IAAI,UAAU,GAAG,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACjD,IAAI,CAAC;gBACH,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/E,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBAAC,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,mCAAmC;YAAC,CAAC;QAClF,CAAC;QACD,OAAO;YACL,IAAI,CAAC,MAAM,EAAE;gBAAE,OAAO;YACtB,IAAI,CAAC;gBAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,iDAAiD,CAAC,CAAC;QACvG,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gIAAgI;AAChI,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAiB,EAAE;IAC1D,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;IACrC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC;IAC7C,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;IAClC,OAAO,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAChJ,CAAC"}

package/dist/lib/sync/purge.d.ts

@@ -0,0 +1,38 @@
+/**
+ * L5: `align local forget <source> --purge`. Forgetting a source drops its token and its sync rows
+ * and keeps what it imported; `--purge` also deletes the imported items, but only ones nobody has
+ * put their name to or ever handled.
+ *
+ * What may be purged: a row of a CONNECTOR source (never git, docs, sessions, cli or anything
+ * else) that carries a `source_key`, which only a connector import ever sets. A row captured by
+ * hand (`align capture <PR url>`, a plain-text capture) has none, so it cannot be purged even when
+ * its platform says `github`. Note that `decider_kind` cannot separate imports from captures:
+ * every connector import is derived `human` (decider-kind.ts), so it is not used here.
+ *
+ * Kept whatever the platform says: a ratified row, a confirmed row, a row with ANY audit act on it
+ * (a `capture_seen` note is one: somebody captured it by hand after the import; only the notes the
+ * system writes about its own text revisions and classification attempts are not acts), a row a
+ * local judgement names as target or counterpart, and a row a promotion records (`promotions.local_id`).
+ *
+ * Every purged row is copied to `decisions_purged_backup` (with its vector and refs) in the same
+ * transaction, so a purge can be undone by copying them back. Its links and sync-item state go with it.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** Audit rows the system writes about itself. They are not acts. `capture_seen` is NOT here: it is a person's act. */
+export declare const SYSTEM_AUDIT_ACTIONS: readonly ["text_revision_pending", "sync_classified"];
+/** The only names `--purge` accepts: sources a connector import fills. */
+export declare const PURGEABLE_SOURCES: readonly string[];
+export declare const isPurgeable: (name: string) => boolean;
+export interface PurgeResult {
+    deleted: number;
+    kept: number;
+}
+export declare function previewIn(db: DatabaseSync, platform: string): PurgeResult & {
+    total: number;
+};
+/** Copy, then delete, inside the caller's transaction. */
+export declare function purgeIn(db: DatabaseSync, platform: string): PurgeResult;
+/** How many rows of this platform a purge would delete and keep. Reads only; refuses a name that is not a connector. */
+export declare function purgePreview(dbPath: string, platform: string): PurgeResult;
+export declare function purgePlatform(dbPath: string, platform: string): PurgeResult;
+//# sourceMappingURL=purge.d.ts.map

package/dist/lib/sync/purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../../src/lib/sync/purge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,sHAAsH;AACtH,eAAO,MAAM,oBAAoB,uDAAwD,CAAC;AAE1F,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAkC,CAAC;AAClF,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,OAA2C,CAAC;AAEvF,MAAM,WAAW,WAAW;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAyB9D,wBAAgB,SAAS,CAAC,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAI7F;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAYvE;AAED,wHAAwH;AACxH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAI1E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAG3E"}

package/dist/lib/sync/purge.js

@@ -0,0 +1,61 @@
+import { copyRowsToBackup } from '../backup-copy.js';
+import { createLocalDb } from '../local-db.js';
+import { deleteDecisionWithDependents } from '../local-db-migrate.js';
+import { BACKFILL_SOURCES } from '../mcp-backfill.js';
+import { transact } from './sync-state.js';
+/** Audit rows the system writes about itself. They are not acts. `capture_seen` is NOT here: it is a person's act. */
+export const SYSTEM_AUDIT_ACTIONS = ['text_revision_pending', 'sync_classified'];
+/** The only names `--purge` accepts: sources a connector import fills. */
+export const PURGEABLE_SOURCES = [...BACKFILL_SOURCES, 'zoom'];
+export const isPurgeable = (name) => PURGEABLE_SOURCES.includes(name);
+const hasTable = (db, name) => db.prepare(`SELECT 1 AS hit FROM sqlite_master WHERE type = 'table' AND name = ?`).get(name) !== undefined;
+/** A WHERE fragment over `decisions d` selecting the rows a purge of one platform may delete. Binds the platform once. */
+function disposableWhere(db) {
+    const marks = SYSTEM_AUDIT_ACTIONS.map((a) => `'${a}'`).join(', ');
+    const parts = [
+        'd.platform = ?',
+        'd.source_key IS NOT NULL',
+        `d.platform NOT IN ('cli', 'agent-session')`,
+        'd.ratified_at IS NULL',
+        'd.confirmed_at IS NULL',
+        `NOT EXISTS (SELECT 1 FROM decision_audit a WHERE a.decision_id = d.id AND a.action NOT IN (${marks}))`,
+    ];
+    if (hasTable(db, 'local_judgements')) {
+        parts.push('NOT EXISTS (SELECT 1 FROM local_judgements j WHERE j.decision_id = d.id OR j.counterpart_id = d.id)');
+    }
+    if (hasTable(db, 'promotions')) {
+        parts.push('NOT EXISTS (SELECT 1 FROM promotions p WHERE p.local_id = d.id)');
+    }
+    return parts.join(' AND ');
+}
+export function previewIn(db, platform) {
+    const total = db.prepare('SELECT COUNT(*) AS n FROM decisions WHERE platform = ?').get(platform).n;
+    const deletable = isPurgeable(platform) ? db.prepare(`SELECT COUNT(*) AS n FROM decisions d WHERE ${disposableWhere(db)}`).get(platform).n : 0;
+    return { deleted: deletable, kept: total - deletable, total };
+}
+/** Copy, then delete, inside the caller's transaction. */
+export function purgeIn(db, platform) {
+    if (!isPurgeable(platform))
+        throw new Error(`"${platform.slice(0, 24)}" is not a connector source, so nothing was purged.`);
+    const { total } = previewIn(db, platform);
+    const ids = db.prepare(`SELECT d.id AS id FROM decisions d WHERE ${disposableWhere(db)}`).all(platform).map((r) => r.id);
+    for (const id of ids) {
+        copyRowsToBackup(db, 'decisions', 'decisions_purged_backup', 'id', id);
+        copyRowsToBackup(db, 'decision_embeddings', 'decision_embeddings_purged_backup', 'decision_id', id);
+        copyRowsToBackup(db, 'decision_refs', 'decision_refs_purged_backup', 'decision_id', id);
+        deleteDecisionWithDependents(db, id);
+        db.prepare('DELETE FROM sync_item_state WHERE decision_id = ?').run(id);
+    }
+    return { deleted: ids.length, kept: total - ids.length };
+}
+/** How many rows of this platform a purge would delete and keep. Reads only; refuses a name that is not a connector. */
+export function purgePreview(dbPath, platform) {
+    createLocalDb(dbPath).close(); // migrates an older file, refuses a newer one
+    const r = transact(dbPath, (db) => previewIn(db, platform));
+    return { deleted: r.deleted, kept: r.kept };
+}
+export function purgePlatform(dbPath, platform) {
+    createLocalDb(dbPath).close();
+    return transact(dbPath, (db) => purgeIn(db, platform));
+}
+//# sourceMappingURL=purge.js.map

package/dist/lib/sync/purge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge.js","sourceRoot":"","sources":["../../../src/lib/sync/purge.ts"],"names":[],"mappings":"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"}