hippo-memory 1.63.1 → 1.64.0

package/dist/compaction-spool.js

@@ -0,0 +1,454 @@
+// Summaries post-compact could not record because the store was busy, waiting on disk for the next replay.
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { isObjectLike, isStringValue } from './capture-contract.js';
+import { isSqliteBusy } from './db/busy.js';
+import { errorMessage } from './log.js';
+export const SPOOL_DIR = 'compactions-spool';
+/** Starts the log line of a step that broke with an unexpected error, so the session-start banner counts it; a set-aside file is counted by its `.bad` name instead. */
+export const SPOOL_PROBLEM = 'spool problem: ';
+const LOCK = 'replay.lock';
+/** Long enough that a live replayer has finished with its claim. */
+const STALE_MS = 10 * 60_000;
+const MAX_ATTEMPTS = 3;
+const BUSY_RETRIES = 3;
+const BUSY_WAIT_MS = 50;
+// Antivirus, the indexer or a delete still pending on Windows: the step is left for a later run.
+const BUSY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+// A stem is `<ms13>-<rand8hex>`, so name order is age order; legacy files are `<session>-<ms>.json`.
+const WAITING = /^([\w-]+)(?:\.a(\d+))?\.json$/;
+const CLAIM = /^([\w-]+)\.a(\d+)\.claim-(\d{13})$/;
+// An old binary's claim carries no claim time, so its mtime stands in.
+const LEGACY_CLAIM = /^([\w-]+)(?:\.a(\d+))?\.json\.claimed$/;
+const TMP = /^([\w-]+)(?:\.a\d+)?\.json\.tmp$/;
+const BAD = /^([\w-]+)\.(?:\w+\.)?bad$/;
+const BAD_TMP = /^[\w-]+\.\w+\.bad\.[0-9a-f]{8}\.tmp$/;
+const NEW_STEM = /^(\d{13})-[0-9a-f]{8}$/;
+const LEGACY_STEM_TIME = /-(\d+)$/;
+let fsx = fs;
+/** Test-only seam, so a test can make one fs call fail; null restores the real fs. */
+export function __setSpoolFs(next) {
+    fsx = next ?? fs;
+}
+const stamp = (ms) => String(Math.trunc(ms)).padStart(13, '0');
+const isTime = (value) => typeof value === 'number' && Number.isFinite(value);
+const idle = new Int32Array(new SharedArrayBuffer(4));
+function errCode(cause) {
+    return cause instanceof Error && 'code' in cause && isStringValue(cause.code) ? cause.code : '';
+}
+/** Runs one fs step, retrying a busy code briefly; '' when it ran, else the busy code it kept hitting. Any other error throws. */
+function retryBusy(step) {
+    for (let retry = 0;; retry++) {
+        try {
+            step();
+            return '';
+        }
+        catch (err) {
+            const code = errCode(err);
+            if (!BUSY_CODES.has(code))
+                throw err;
+            if (retry === BUSY_RETRIES)
+                return code;
+            Atomics.wait(idle, 0, 0, BUSY_WAIT_MS);
+        }
+    }
+}
+/** Runs one fs step: ENOENT means gone, a busy code is retried briefly, and any other error is logged and counted busy, so a replay never throws. */
+function settleCode(step, log, what) {
+    try {
+        const code = retryBusy(step);
+        return { settled: code === '' ? 'done' : 'busy', code };
+    }
+    catch (err) {
+        const code = errCode(err);
+        if (code === 'ENOENT')
+            return { settled: 'gone', code };
+        log(`${SPOOL_PROBLEM}${what}: ${errorMessage(err)}`);
+        return { settled: 'busy', code };
+    }
+}
+/** {@link settleCode} for a caller that needs only the outcome. */
+function settle(step, log, what) {
+    return settleCode(step, log, what).settled;
+}
+/** When a stem was spooled: the time that leads a new stem, else the time that ends a legacy one, else 0. */
+function created(stem) {
+    const m = NEW_STEM.exec(stem) ?? LEGACY_STEM_TIME.exec(stem);
+    return m === null ? 0 : Number(m[1]);
+}
+/** Files waiting for import, oldest first across new and legacy names. */
+function waitingFiles(names) {
+    const found = names.flatMap((name) => {
+        const m = WAITING.exec(name);
+        return m === null ? [] : [{ name, stem: m[1], attempt: Number(m[2] ?? 0), created: created(m[1]) }];
+    });
+    return found.sort((a, b) => a.created - b.created || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+function claimOf(name) {
+    const m = CLAIM.exec(name);
+    if (m !== null)
+        return { name, stem: m[1], attempt: Number(m[2]), claimedAt: Number(m[3]) };
+    const legacy = LEGACY_CLAIM.exec(name);
+    return legacy === null ? null : { name, stem: legacy[1], attempt: Number(legacy[2] ?? 0), claimedAt: null };
+}
+// The session id stays in the body only, and the random part keeps two spools of one millisecond apart.
+function spoolFile(hippoRoot) {
+    return path.join(hippoRoot, SPOOL_DIR, `${stamp(Date.now())}-${randomBytes(4).toString('hex')}.a0.json`);
+}
+export function spool(hippoRoot, tenantId, payload, text, at) {
+    const file = spoolFile(hippoRoot);
+    fsx.mkdirSync(path.dirname(file), { recursive: true });
+    const body = { tenantId, sessionId: payload.sessionId, trigger: payload.trigger, cwd: payload.cwd, transcriptPath: payload.transcriptPath, at: at.toISOString(), summary: text.summary, items: text.items };
+    // Renamed into place so a replayer listing `.json` files never reads half a file.
+    fsx.writeFileSync(`${file}.tmp`, JSON.stringify(body), { encoding: 'utf8', flag: 'wx' });
+    // A rename that stays busy leaves a whole tmp, which a replay promotes once it is STALE_MS old.
+    retryBusy(() => fsx.renameSync(`${file}.tmp`, file));
+}
+/** null when the text is not a spooled compaction. */
+export function parseSpooled(text, fallbackTenantId) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null; // a half-written spool file holds no compaction; the caller treats null as unreadable
+    }
+    if (!isObjectLike(raw) || !('sessionId' in raw) || !isStringValue(raw.sessionId) || !('summary' in raw) || !isStringValue(raw.summary))
+        return null;
+    if (!('at' in raw) || !isStringValue(raw.at) || Number.isNaN(Date.parse(raw.at)))
+        return null;
+    const items = 'items' in raw && Array.isArray(raw.items) ? raw.items.filter(isStringValue) : [];
+    return {
+        tenantId: 'tenantId' in raw && isStringValue(raw.tenantId) && raw.tenantId !== '' ? raw.tenantId : fallbackTenantId,
+        payload: {
+            sessionId: raw.sessionId,
+            trigger: 'trigger' in raw && isStringValue(raw.trigger) ? raw.trigger : null,
+            cwd: 'cwd' in raw && isStringValue(raw.cwd) ? raw.cwd : null,
+            transcriptPath: 'transcriptPath' in raw && isStringValue(raw.transcriptPath) ? raw.transcriptPath : null,
+            compactSummary: null,
+        },
+        text: { summary: raw.summary, items },
+        at: new Date(raw.at),
+    };
+}
+const heldBy = (pid) => `spool left to another replayer (lock held by ${pid === null ? 'another process' : `pid ${pid}`})`;
+function parseLock(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null; // torn, or its holder is still writing it; the caller judges it by mtime
+    }
+    if (!isObjectLike(raw) || !('at' in raw) || !isTime(raw.at))
+        return null;
+    const pid = 'pid' in raw && isTime(raw.pid) ? raw.pid : null;
+    const token = 'token' in raw && isStringValue(raw.token) ? raw.token : null;
+    return { pid, at: raw.at, token };
+}
+/** The lock's body; its mtime stands in for the time when the body does not parse. */
+function readLock(lock, log) {
+    let text = '';
+    const read = settle(() => { text = fsx.readFileSync(lock, 'utf8'); }, log, 'spool lock not read');
+    if (read !== 'done')
+        return read;
+    const body = parseLock(text);
+    if (body !== null)
+        return body;
+    let mtime = 0;
+    const stat = settle(() => { mtime = fsx.statSync(lock).mtimeMs; }, log, 'spool lock not read');
+    return stat === 'done' ? { pid: null, at: mtime, token: null } : stat;
+}
+function createLock(lock, body, log) {
+    try {
+        fsx.writeFileSync(lock, body, { encoding: 'utf8', flag: 'wx' });
+        return 'taken';
+    }
+    catch (err) {
+        const code = errCode(err);
+        if (code === 'EEXIST')
+            return 'exists';
+        // Windows refuses a create while a delete of the same name is pending, and the folder may have just gone.
+        if (code !== 'ENOENT' && !BUSY_CODES.has(code))
+            log(`spool lock not taken: ${errorMessage(err)}`);
+        return 'skip';
+    }
+}
+/** This run's token and take time once it holds `replay.lock`, else null: another replayer holds it, or it could not be made. */
+function takeLock(dir, log) {
+    const lock = path.join(dir, LOCK);
+    const token = randomBytes(8).toString('hex');
+    const at = Date.now();
+    const body = JSON.stringify({ pid: process.pid, at, token });
+    for (let tries = 0; tries < 2; tries++) {
+        const made = createLock(lock, body, log);
+        if (made === 'taken')
+            return { token, at };
+        if (made === 'skip')
+            break;
+        const held = readLock(lock, log);
+        if (held === 'gone')
+            continue;
+        if (held === 'busy')
+            break;
+        if (Math.abs(Date.now() - held.at) <= STALE_MS) {
+            log(heldBy(held.pid));
+            return null;
+        }
+        // SHORTCUT: two takers of one stale lock overlap by one file each; a pid-alive check is the upgrade.
+        if (settle(() => fsx.unlinkSync(lock), log, 'spool lock not taken over') === 'busy')
+            break;
+    }
+    log(heldBy(null));
+    return null;
+}
+/** False, after saying so, once `replay.lock` no longer holds this run's token or cannot be read. */
+function ownsLock(dir, token, log) {
+    const held = readLock(path.join(dir, LOCK), log);
+    if (held !== 'gone' && held !== 'busy' && held.token === token)
+        return true;
+    log(held === 'busy' ? 'spool lock could not be read, stopping' : 'spool left to another replayer (lock taken over)');
+    return false;
+}
+/** Removes `replay.lock` only while it holds this run's token, so a run never deletes a successor's lock. Never throws. */
+function releaseLock(dir, mine, log) {
+    const lock = path.join(dir, LOCK);
+    const held = readLock(lock, log);
+    // A takeover needs a lock over STALE_MS old, so a busy read of one this run took more recently is still this run's.
+    const ours = held === 'busy' ? Date.now() - mine.at < STALE_MS : held !== 'gone' && held.token === mine.token;
+    if (ours)
+        settle(() => fsx.unlinkSync(lock), log, 'spool lock not released');
+}
+/** Claim time sits in the claim's name, so a claim over STALE_MS away from now belongs to a replayer that never finished. True when one was put back. */
+function recoverStaleClaims(dir, names, log) {
+    const now = Date.now();
+    // A claim whose unlink stayed busy after its `.bad` landed is a spare copy, not a second failure.
+    const setAside = new Set(names.flatMap((name) => BAD.exec(name)?.[1] ?? []));
+    let putBackOne = false;
+    for (const claim of names.flatMap((name) => claimOf(name) ?? [])) {
+        const file = path.join(dir, claim.name);
+        const what = `spool file ${claim.name} not recovered`;
+        let at = claim.claimedAt ?? 0;
+        if (claim.claimedAt === null && settle(() => { at = fsx.statSync(file).mtimeMs; }, log, what) !== 'done')
+            continue;
+        if (Math.abs(now - at) <= STALE_MS)
+            continue;
+        const next = claim.attempt + 1;
+        if (setAside.has(claim.stem)) {
+            settle(() => fsx.unlinkSync(file), log, what);
+        }
+        else if (next < MAX_ATTEMPTS) {
+            if (settle(() => fsx.renameSync(file, path.join(dir, `${claim.stem}.a${next}.json`)), log, what) === 'done') {
+                log(`spool file ${claim.name} was claimed by a replayer that never finished, put back (try ${next} of ${MAX_ATTEMPTS})`);
+                putBackOne = true;
+            }
+        }
+        else if (moveBad(dir, file, claim.stem, claim.attempt, 'interrupted', log)) {
+            log(`spool file ${claim.name} was claimed by a replayer that never finished ${MAX_ATTEMPTS} times, set aside as .bad`);
+        }
+    }
+    return putBackOne;
+}
+/** Returns a claim to the waiting files as `<stem>.a<attempt>.json`; one that stays busy is left for stale recovery. */
+function putBack(dir, claim, stem, attempt, log) {
+    const name = path.basename(claim);
+    if (settle(() => fsx.renameSync(claim, path.join(dir, `${stem}.a${attempt}.json`)), log, `spool file ${name} not put back`) === 'busy') {
+        log(`spool file ${name} could not be put back; it returns ${STALE_MS / 60_000} minutes after its claim`);
+    }
+}
+/** Writes `<stem>.<cause>.bad` through a random temp file, so the rename replaces any torn `.bad` a crash left. */
+function writeBad(dir, stem, cause, text, log, what) {
+    const tmp = path.join(dir, `${stem}.${cause}.bad.${randomBytes(4).toString('hex')}.tmp`);
+    const written = settle(() => fsx.writeFileSync(tmp, text, { encoding: 'utf8', flag: 'wx' }), log, what);
+    const moved = written === 'done' ? settle(() => fsx.renameSync(tmp, path.join(dir, `${stem}.${cause}.bad`)), log, what) : written;
+    if (moved !== 'done' && written === 'done')
+        settle(() => fsx.unlinkSync(tmp), log, what);
+    return moved === 'done';
+}
+/** Sets a claim aside as `.bad` before the claim goes, so a crash between leaves a whole copy; a busy write puts the claim back. */
+function moveBad(dir, claim, stem, attempt, cause, log, raw) {
+    const what = `spool file ${path.basename(claim)} not set aside`;
+    let text = raw ?? '';
+    if (raw === undefined && settle(() => { text = fsx.readFileSync(claim, 'utf8'); }, log, what) !== 'done')
+        return false;
+    if (!writeBad(dir, stem, cause, text, log, what)) {
+        putBack(dir, claim, stem, attempt, log);
+        return false;
+    }
+    settle(() => fsx.unlinkSync(claim), log, what);
+    return true;
+}
+/** A tmp over STALE_MS old belongs to a spool that never renamed it: a whole one joins the waiting files, a torn one is set aside. True when one joined. */
+function promoteTmp(dir, names, tenantId, log) {
+    const now = Date.now();
+    let promoted = false;
+    for (const name of names) {
+        const m = TMP.exec(name);
+        if (m === null && !BAD_TMP.test(name))
+            continue;
+        const file = path.join(dir, name);
+        const what = `spool file ${name} not promoted`;
+        let mtime = 0;
+        let text = '';
+        if (settle(() => { mtime = fsx.statSync(file).mtimeMs; }, log, what) !== 'done' || Math.abs(now - mtime) <= STALE_MS)
+            continue;
+        if (m === null) {
+            // A `.bad` write cut off before its rename: its source goes only after that rename lands, so this copy is spare.
+            settle(() => fsx.unlinkSync(file), log, `spool file ${name} not removed`);
+            continue;
+        }
+        if (settle(() => { text = fsx.readFileSync(file, 'utf8'); }, log, what) !== 'done')
+            continue;
+        if (parseSpooled(text, tenantId) !== null) {
+            if (settle(() => fsx.renameSync(file, file.slice(0, -'.tmp'.length)), log, what) === 'done') {
+                log(`spool file ${name} was never renamed into place, promoted`);
+                promoted = true;
+            }
+        }
+        else if (writeBad(dir, m[1], 'unreadable', text, log, what)) {
+            settle(() => fsx.unlinkSync(file), log, what);
+            log(`spool file ${name} was never finished, set aside as .bad`);
+        }
+    }
+    return promoted;
+}
+/** Removes a claim once the store holds its summary; a claim left behind is imported again, so the log says so. */
+function removeClaim(claim, name, log) {
+    const removed = settleCode(() => fsx.unlinkSync(claim), log, `spool file ${name} claim not removed`);
+    if (removed.settled === 'busy')
+        log(`spool file ${name} saved; its claim could not be removed (${removed.code}); it will be imported again`);
+}
+/** After an importer throw: a busy store stops the run with the count unchanged, any other error counts one try toward .bad. */
+function importFailed(dir, claim, entry, text, recorded, cause, log) {
+    const { name } = entry;
+    const busy = isSqliteBusy(cause);
+    if (recorded) {
+        // The record stays `summarised`, so the stalled-record step of a later replay writes its items.
+        log(busy ? `spool file ${name} saved; its memories wait for the next sleep (store busy)` : `spool file ${name} saved; writing its memories failed: ${errorMessage(cause)}`);
+        return busy ? 'stop' : 'skipped';
+    }
+    if (busy) {
+        putBack(dir, claim, entry.stem, entry.attempt, log);
+        log(`spool file ${name} waits for the next run: the store is busy`);
+        return 'stop';
+    }
+    const next = entry.attempt + 1;
+    if (next < MAX_ATTEMPTS) {
+        putBack(dir, claim, entry.stem, next, log);
+        log(`spool file ${name} failed to import (try ${next} of ${MAX_ATTEMPTS}): ${errorMessage(cause)}`);
+    }
+    else if (moveBad(dir, claim, entry.stem, entry.attempt, 'failed', log, text)) {
+        log(`spool file ${name} set aside as .bad after ${MAX_ATTEMPTS} tries: ${errorMessage(cause)}`);
+    }
+    return 'skipped';
+}
+/** Claims, reads and imports one waiting file; `stop` ends the run because the store is busy. */
+function importFile(dir, entry, tenantId, log, importOne) {
+    const { name } = entry;
+    const claim = path.join(dir, `${entry.stem}.a${entry.attempt}.claim-${stamp(Date.now())}`);
+    const taken = settleCode(() => fsx.renameSync(path.join(dir, name), claim), log, `spool file ${name} not claimed`);
+    if (BUSY_CODES.has(taken.code))
+        log(`spool file ${name} is locked by another program, left for the next run`);
+    if (taken.settled !== 'done')
+        return 'skipped';
+    let text = '';
+    const read = settle(() => { text = fsx.readFileSync(claim, 'utf8'); }, log, `spool file ${name} not read`);
+    if (read === 'gone')
+        log(`spool file ${name} vanished`);
+    if (read === 'busy')
+        putBack(dir, claim, entry.stem, entry.attempt, log);
+    if (read !== 'done')
+        return 'skipped';
+    const spooled = parseSpooled(text, tenantId);
+    if (spooled === null) {
+        if (moveBad(dir, claim, entry.stem, entry.attempt, 'unreadable', log, text))
+            log(`spool file ${name} is not readable, set aside as .bad`);
+        return 'skipped';
+    }
+    let recorded = false;
+    const markRecorded = () => {
+        if (recorded)
+            return;
+        recorded = true;
+        removeClaim(claim, name, log);
+    };
+    try {
+        importOne(spooled, markRecorded);
+        markRecorded();
+        return 'imported';
+    }
+    catch (err) {
+        return importFailed(dir, claim, entry, text, recorded, err, log);
+    }
+}
+function mtimeOf(file) {
+    try {
+        return fsx.statSync(file).mtimeMs;
+    }
+    catch (err) {
+        const code = errCode(err);
+        // Moved by a replay after the listing, or held by another program: left out of this count rather than failing it.
+        if (code === 'ENOENT' || BUSY_CODES.has(code))
+            return null;
+        throw err;
+    }
+}
+/** What doctor reports, read only: files a replay should have taken by now, claims and tmp files a dead process left, and `.bad` files. */
+export function spoolCounts(hippoRoot, now, waitingAfterMs) {
+    const counts = { waiting: 0, stale: 0, bad: 0 };
+    const dir = path.join(hippoRoot, SPOOL_DIR);
+    if (!fsx.existsSync(dir))
+        return counts;
+    const at = now.getTime();
+    for (const name of fsx.readdirSync(dir)) {
+        const file = path.join(dir, name);
+        const waiting = WAITING.exec(name);
+        const claim = claimOf(name);
+        if (name.endsWith('.bad'))
+            counts.bad++;
+        else if (waiting !== null) {
+            const spooled = NEW_STEM.test(waiting[1]) ? created(waiting[1]) : mtimeOf(file);
+            if (spooled !== null && at - spooled > waitingAfterMs)
+                counts.waiting++;
+        }
+        else if (claim !== null || TMP.test(name)) {
+            const since = claim?.claimedAt ?? mtimeOf(file);
+            if (since !== null && Math.abs(at - since) > STALE_MS)
+                counts.stale++;
+        }
+    }
+    return counts;
+}
+/** One replayer at a time holds `replay.lock`, so only one process claims a file even where Windows lets two renames of it both land. */
+export function importSpool(hippoRoot, tenantId, log, deadline, importOne) {
+    const dir = path.join(hippoRoot, SPOOL_DIR);
+    if (!fsx.existsSync(dir))
+        return 0;
+    const mine = takeLock(dir, log);
+    if (mine === null)
+        return 0;
+    try {
+        if (!ownsLock(dir, mine.token, log))
+            return 0;
+        const names = fsx.readdirSync(dir);
+        const promoted = promoteTmp(dir, names, tenantId, log);
+        const recovered = recoverStaleClaims(dir, names, log);
+        let finished = 0;
+        // Only promotion and recovery add waiting names, so the folder is listed again only after one of them did.
+        for (const entry of waitingFiles(promoted || recovered ? fsx.readdirSync(dir) : names)) {
+            if (Date.now() > deadline || !ownsLock(dir, mine.token, log))
+                break;
+            const outcome = importFile(dir, entry, tenantId, log, importOne);
+            if (outcome === 'imported')
+                finished++;
+            if (outcome === 'stop')
+                break;
+        }
+        return finished;
+    }
+    finally {
+        releaseLock(dir, mine, log);
+    }
+}
+//# sourceMappingURL=compaction-spool.js.map

package/dist/config.d.ts

@@ -151,6 +151,14 @@ export interface HippoConfig {
     projectIdentity: {
         remote: boolean;
     };
+    /** The store serves many people, so a write that names no project is stamped NULL, never this folder's project,
+     *  and a context read must name the caller's project. Default false. Read it through isSharedStore. */
+    sharedStore: boolean;
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
+/** True when the store's config.json sets `"sharedStore": true`. Once true, a root stays true for this process,
+ *  so a broken edit while a server runs cannot turn it off. Reads only this key: loadConfig has no cache. */
+export declare function isSharedStore(hippoRoot: string): boolean;
+/** Test seam: forget every root seen as shared. */
+export declare function _resetSharedStoreCacheForTests(): void;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -96,6 +96,7 @@ const DEFAULT_CONFIG = {
     projectIdentity: {
         remote: true,
     },
+    sharedStore: false,
 };
 function isMemoryValueConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -220,6 +221,14 @@ function defaultHalfLifeDays(raw) {
     }
     return days;
 }
+// Only a real true turns it on; anything else present warns and stays off.
+function sharedStoreFlag(raw) {
+    const value = raw.sharedStore;
+    if (value === undefined || value === true || value === false)
+        return value === true;
+    log.warn(`config.json's "sharedStore" must be true or false (got ${JSON.stringify(value)}) - using false.`);
+    return false;
+}
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
     if (!fs.existsSync(configPath))
@@ -267,6 +276,7 @@ export function loadConfig(hippoRoot) {
             deliveryLedger: { enabled: deliveryLedgerEnabled(raw.deliveryLedger) },
             pilot: { holdoutRateBp: pilotHoldoutRate(raw.pilot) },
             projectIdentity: { remote: projectIdentityRemote(raw.projectIdentity) },
+            sharedStore: sharedStoreFlag(raw),
         };
     }
     catch (err) {
@@ -276,4 +286,43 @@ export function loadConfig(hippoRoot) {
         return { ...DEFAULT_CONFIG };
     }
 }
+const sharedStoreRoots = new Set();
+/** The folder as isGlobalStoreRoot compares it (realpath, case-folded on Windows); its helper sits behind an import cycle. */
+function sharedStoreKey(hippoRoot) {
+    let real;
+    try {
+        real = fs.realpathSync.native(hippoRoot);
+    }
+    catch (err) {
+        log.debug(`sharedStore: realpath fell back to resolve for ${hippoRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        real = path.resolve(hippoRoot);
+    }
+    return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+/** True when the store's config.json sets `"sharedStore": true`. Once true, a root stays true for this process,
+ *  so a broken edit while a server runs cannot turn it off. Reads only this key: loadConfig has no cache. */
+export function isSharedStore(hippoRoot) {
+    const key = sharedStoreKey(hippoRoot);
+    if (sharedStoreRoots.has(key))
+        return true;
+    const configPath = path.join(path.resolve(hippoRoot), 'config.json');
+    if (!fs.existsSync(configPath))
+        return false;
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch (err) {
+        log.warn(`failed to read ${configPath}: ${err instanceof Error ? err.message : err} - sharedStore read as false.`);
+        return false;
+    }
+    if (raw?.sharedStore !== true)
+        return false;
+    sharedStoreRoots.add(key);
+    return true;
+}
+/** Test seam: forget every root seen as shared. */
+export function _resetSharedStoreCacheForTests() {
+    sharedStoreRoots.clear();
+}
 //# sourceMappingURL=config.js.map

package/dist/connectors/github/deletion.d.ts

@@ -24,7 +24,7 @@ export interface DeletionResult {
  * match a single deletion event. Archive ALL of them.
  *
  * ONE shared DB handle wraps ALL archives + the idempotency mark in a single
- * outer SAVEPOINT: a per-row failure rolls back the whole batch, idempotency
+ * outer write scope: a per-row failure rolls back the whole batch, idempotency
  * included, so a retry re-attempts cleanly instead of leaving searchable
  * survivors. archiveRawMemory's own inner SAVEPOINT nests safely inside it.
  *

package/dist/connectors/github/deletion.js

@@ -1,4 +1,4 @@
-import { openHippoDb, closeHippoDb } from '../../db.js';
+import { openHippoDb, closeHippoDb, withWriteScope } from '../../db.js';
 import { archiveRawMemory } from '../../raw-archive.js';
 import { hasSeenKey, markKeySeen } from './idempotency.js';
 /**
@@ -9,7 +9,7 @@ import { hasSeenKey, markKeySeen } from './idempotency.js';
  * match a single deletion event. Archive ALL of them.
  *
  * ONE shared DB handle wraps ALL archives + the idempotency mark in a single
- * outer SAVEPOINT: a per-row failure rolls back the whole batch, idempotency
+ * outer write scope: a per-row failure rolls back the whole batch, idempotency
  * included, so a retry re-attempts cleanly instead of leaving searchable
  * survivors. archiveRawMemory's own inner SAVEPOINT nests safely inside it.
  *
@@ -40,11 +40,10 @@ export function handleCommentDeleted(ctx, input) {
             });
             return { status: 'archive_skipped_not_found', archivedCount: 0 };
         }
-        // Outer SAVEPOINT wrapping all archives + the idempotency mark. Any throw
+        // Outer write scope wrapping all archives + the idempotency mark. Any throw
         // rolls back the whole batch so retry sees neither archive nor mark — and
         // re-attempts the full set.
-        db.exec('SAVEPOINT github_delete_all');
-        try {
+        withWriteScope(db, 'github_delete_all', () => {
             for (const id of memoryIds) {
                 archiveRawMemory(db, id, {
                     reason: `source_deleted:github:${input.eventName}:${input.deliveryId}`,
@@ -57,18 +56,7 @@ export function handleCommentDeleted(ctx, input) {
                 eventName: input.eventName,
                 memoryId: memoryIds[0],
             });
-            db.exec('RELEASE SAVEPOINT github_delete_all');
-        }
-        catch (e) {
-            try {
-                db.exec('ROLLBACK TO SAVEPOINT github_delete_all');
-                db.exec('RELEASE SAVEPOINT github_delete_all');
-            }
-            catch {
-                // Best effort. Surface the original error.
-            }
-            throw e;
-        }
+        });
         return { status: 'archived', archivedCount: memoryIds.length };
     }
     finally {

package/dist/consolidate/conflicts.js

@@ -1,6 +1,7 @@
 import { Layer, calculateStrength } from '../memory.js';
 import { jaccardMinShared, overlapPartners } from '../overlap-index.js';
 import { isQuarantineScope } from '../quarantine.js';
+import { isPersonalScope } from '../recall-scope.js';
 import { DECAY_THRESHOLD } from './decay.js';
 // Contradictions should be gated by content overlap, not shared tags. Tags like
 // `feedback` / `policy` are too coarse and can make unrelated rules look like
@@ -66,6 +67,9 @@ rescuedIds = new Set()) {
 }
 /** One project's ambient context can show both: same tenant, and the same project or a user-global row beside a project's. */
 function recalledTogether(a, b) {
+    // A personal row pairs only inside its own scope; any other pair shows its id to someone else.
+    if ((isPersonalScope(a.scope) || isPersonalScope(b.scope)) && a.scope !== b.scope)
+        return false;
     if (a.tenantId !== b.tenantId)
         return false;
     const [x, y] = [a.origin_project ?? null, b.origin_project ?? null];

package/dist/consolidate/flush-units.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryEntry } from '../memory.js';
+import type { DormantMove } from '../dormant.js';
+import type { FlushComponent } from '../store/delete-and-batch.js';
+/** Components that share no id, ordered by each one's first op across writes, then deletes, then dormant moves. */
+export declare function groupFlush(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], units: readonly (readonly string[])[]): FlushComponent[];
+/** [child, parent] for each queued op on a child whose DAG parent the run removes: a child's change marks the parent
+ *  dirty, and one transaction always applied that mark after the parent was gone, so it audited nothing. */
+export declare function familyUnits(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], snapshot: ReadonlyMap<string, MemoryEntry>): string[][];
+//# sourceMappingURL=flush-units.d.ts.map