renor-engine 0.0.0-stage → 1.0.0

package/dist/importing/forgetImported.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPORT_JOURNAL_DIR = void 0;
+exports.forgetImportedNotes = forgetImportedNotes;
+const crypto_1 = __importDefault(require("crypto"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const journalLog_1 = require("./journalLog");
+/**
+ * The import journal: one JSON manifest per batch in `.renor-imports/` (hosted.ts writes it and undo_import reads it). While a
+ * batch is applying, its notes are in a sidecar log beside the manifest instead (journalLog.ts).
+ * It names every note a batch created, by path, and the batch's label, which is the folder name of those notes. A note that is
+ * permanently deleted (purgeRetired) leaves no trace there: its path is a name the owner chose, and the label can say more
+ * than the note does.
+ */
+exports.IMPORT_JOURNAL_DIR = '.renor-imports';
+async function replaceManifest(file, manifest) {
+    const tmp = `${file}.${crypto_1.default.randomUUID()}.tmp`;
+    await promises_1.default.writeFile(tmp, JSON.stringify(manifest), { flag: 'wx', mode: 0o600 });
+    await promises_1.default.rename(tmp, file);
+    // A batch that is no longer applying has no log of its own to keep: a log left beside it would still name the paths removed here.
+    await promises_1.default.rm(path_1.default.join(path_1.default.dirname(file), (0, journalLog_1.journalLogName)(path_1.default.basename(file, '.json'))), { force: true }).catch(() => undefined);
+}
+/**
+ * Remove the given note paths from every import manifest: from `created` (so undo_import has nothing to retire for them) and
+ * from `result.conflicts`. A batch left with no note is kept as a record that it is over, with its id and state `undone`, but
+ * without its label, paths or counts, so undo_import and a second apply say so instead of "not found". A batch that still
+ * holds other notes keeps them, and its label, which is their folder. An apply still running is left alone: it writes its own
+ * journal. Each file is replaced atomically. Idempotent, so a retry after a crash repeats it harmlessly. A file that is not a
+ * plain manifest is left alone.
+ */
+async function forgetImportedNotes(memoryDir, relPaths) {
+    if (relPaths.size === 0)
+        return;
+    const dir = path_1.default.join(memoryDir, exports.IMPORT_JOURNAL_DIR);
+    let names;
+    try {
+        names = await promises_1.default.readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const file = path_1.default.join(dir, name);
+        const st = await promises_1.default.lstat(file);
+        if (!st.isFile())
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(await promises_1.default.readFile(file, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(manifest.created) || manifest.state === 'applying')
+            continue;
+        const created = manifest.created.filter((c) => !relPaths.has(String(c.relPath)));
+        const conflictsWas = Array.isArray(manifest.result?.conflicts) ? manifest.result.conflicts : null;
+        const conflicts = conflictsWas?.filter((p) => !relPaths.has(String(p))) ?? null;
+        const changed = created.length !== manifest.created.length || (conflicts !== null && conflicts.length !== conflictsWas.length);
+        if (!changed)
+            continue;
+        if (created.length === 0) {
+            await replaceManifest(file, { batchId: String(manifest.batchId ?? path_1.default.basename(name, '.json')), state: 'undone', created: [] });
+            continue;
+        }
+        manifest.created = created;
+        if (conflicts !== null)
+            manifest.result = { ...manifest.result, conflicts };
+        await replaceManifest(file, manifest);
+    }
+}

package/dist/importing/hosted.js

@@ -0,0 +1,467 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importBatchSchema = exports.importPreviewSchema = exports.IMPORT_LIMITS = void 0;
+exports.folderLabel = folderLabel;
+exports.previewImport = previewImport;
+exports.applyHostedImport = applyHostedImport;
+exports.undoHostedImport = undoHostedImport;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const zod_1 = require("zod");
+const markdown_1 = require("./markdown");
+const source_1 = require("./source");
+const types_1 = require("./types");
+const plan_1 = require("./plan");
+const apply_1 = require("./apply");
+const memoryMap_1 = require("../memorymap/memoryMap");
+const invisibleText_1 = require("../memory/invisibleText");
+const controls_1 = require("../memory/controls");
+const secretGuard_1 = require("../extraction/secretGuard");
+const toolRefusal_1 = require("../toolRefusal");
+const forgetImported_1 = require("./forgetImported");
+const storedSize_1 = require("../mvp/storedSize");
+const journalLog_1 = require("./journalLog");
+// Fits the existing 1 MiB HTTP ceiling even with JSON escaping. Count UTF-8
+// bytes, including paths, before parsing/selection. Refuse rather than slice.
+exports.IMPORT_LIMITS = { fileBytes: 64 * 1024, batchBytes: 128 * 1024, files: 100 };
+const PREVIEW_MS = 15 * 60 * 1000;
+const batchIdSchema = zod_1.z.string().uuid('batchId must be the batchId returned by preview_import (a UUID)');
+/** Zod's default for a missing field says only "expected array, received undefined"; say what to send instead. */
+function required(message) { return (issue) => (issue.input === undefined ? message : undefined); }
+exports.importPreviewSchema = {
+    label: zod_1.z.string().min(1).max(200).describe('Name for this import; notes go to Imported/<label>/. It is a folder name: letters (any alphabet), digits, "-" and "_" are kept; spaces and punctuation become "-".'),
+    files: zod_1.z.array(zod_1.z.object({
+        relativePath: zod_1.z.string({ error: required("files[] entries need relativePath: the file's path inside the folder, e.g. notes/idea.md") }).min(1).max(512),
+        markdown: zod_1.z.string({ error: required("files[] entries need markdown: the file's full text") })
+            .max(exports.IMPORT_LIMITS.fileBytes, 'This file is over 64 KiB. Split it into several smaller .md files (by heading) or leave it out.'),
+    }).strict(), { error: required('files is required: an array of { relativePath, markdown } holding each file\'s text. The server cannot read your disk; read each file yourself and send its text.') })
+        .min(1).max(exports.IMPORT_LIMITS.files, 'Too many files: send at most 100 per call, then call preview_import again for the next group.'),
+    include: zod_1.z.array(zod_1.z.string().min(1).max(512)).max(100).optional().describe('Only these folder or file path prefixes, e.g. "Projects" (prefixes, not globs)'),
+    exclude: zod_1.z.array(zod_1.z.string().min(1).max(512)).max(100).optional().describe('Leave these folder or file path prefixes out, e.g. "Private" (prefixes, not globs)'),
+    stage: zod_1.z.boolean().optional().describe('false: check only. Same answer without a batchId; nothing is held, so nothing can be applied from it'),
+};
+exports.importBatchSchema = { batchId: batchIdSchema };
+const states = new WeakMap();
+function state(db) {
+    let value = states.get(db);
+    if (!value) {
+        value = { previews: new Map(), chain: Promise.resolve() };
+        states.set(db, value);
+    }
+    return value;
+}
+function serial(db, fn) {
+    const tenant = state(db);
+    const result = tenant.chain.then(fn, fn);
+    tenant.chain = result.then(() => undefined, () => undefined);
+    return result;
+}
+function invalidUnicode(text) {
+    return /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(text);
+}
+/**
+ * The folder name Imported/<label> uses. A name the old pattern accepted ([a-zA-Z0-9][a-zA-Z0-9_-]{0,63}) maps to
+ * itself, so a re-import lands on the same notes. Only letters, digits, marks, '-' and '_' survive (in NFC, so "café" is
+ * one folder however it was typed): no '/', '.', '\\', control character or anything else that changes the target.
+ */
+const MAX_LABEL_BYTES = 200;
+function folderLabel(raw) {
+    const kept = raw.normalize('NFC').replace(/[^\p{L}\p{N}\p{M}_-]+/gu, '-').replace(/^[^\p{L}\p{N}]+/u, '');
+    const label = [...kept].slice(0, 64).join('');
+    if (!label)
+        throw (0, toolRefusal_1.refusal)('invalid_argument', 'label needs at least one letter or digit, e.g. "chatgpt-memory" (it becomes a folder name).');
+    if (Buffer.byteLength(label, 'utf8') > MAX_LABEL_BYTES)
+        throw (0, toolRefusal_1.refusal)('field_too_long', `label is too long as a folder name (over ${MAX_LABEL_BYTES} bytes in UTF-8); shorten it.`);
+    return label;
+}
+function validatePath(rel, i) {
+    const at = `files[${i}]: `;
+    if (rel.startsWith('/') || /^[a-zA-Z]:/.test(rel))
+        throw (0, toolRefusal_1.refusal)('unsafe_path', `${at}relativePath must be relative to the folder you are importing (e.g. notes/CLAUDE.md), not an absolute path.`);
+    if (rel.includes('\\'))
+        throw (0, toolRefusal_1.refusal)('unsafe_path', `${at}use / between folders in relativePath, not a backslash.`);
+    if (rel.split('/').some(part => !part || part === '.' || part === '..' || part.trim() !== part)) {
+        throw (0, toolRefusal_1.refusal)('unsafe_path', `${at}relativePath cannot hold .., . or empty folder names, or a name with leading or trailing spaces; use a path like notes/idea.md.`);
+    }
+    if (invalidUnicode(rel) || /[:\x00-\x1f\x7f]/.test(rel))
+        throw (0, toolRefusal_1.refusal)('unsafe_path', `${at}relativePath has a character that cannot be imported (colon, control character or invalid Unicode); rename the file.`);
+    if (rel.split('/').some(part => Buffer.byteLength(part, 'utf8') > 255))
+        throw (0, toolRefusal_1.refusal)('unsafe_path', `${at}a file or folder name in relativePath is over 255 bytes; shorten it.`);
+    if (rel.endsWith('.'))
+        throw (0, toolRefusal_1.refusal)('unsupported_import_format', `${at}relativePath cannot end with a dot; the name must end in .md.`);
+    if (!rel.endsWith('.md')) {
+        throw (0, toolRefusal_1.refusal)('unsupported_import_format', /\.md$/i.test(rel)
+            ? `${at}rename the extension to lowercase .md.`
+            : `${at}only .md files can be imported. Leave attachments out; send text or JSON as Markdown (a \`\`\`json fence works) under a .md name.`);
+    }
+}
+/** Check ancestors too. The tenant process is the only authorized vault writer. */
+function safeTarget(root, rel) {
+    let current = fs_1.default.realpathSync(root);
+    const parts = rel.split('/');
+    for (let i = 0; i < parts.length; i++) {
+        current = path_1.default.join(current, parts[i]);
+        try {
+            const stat = fs_1.default.lstatSync(current);
+            if (i < parts.length - 1 && (!stat.isDirectory() || stat.isSymbolicLink()))
+                throw (0, toolRefusal_1.refusal)('unsafe_path', 'Unsafe import destination ancestor');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    return current;
+}
+function inspect(ctx, plan) {
+    const conflicts = [];
+    const unchangedPaths = [];
+    for (const note of plan.notes) {
+        const target = safeTarget(ctx.memoryDir, note.relPath);
+        try {
+            const stat = fs_1.default.lstatSync(target);
+            // An empty file here is an interrupted earlier import's leftover: apply replaces it, so it is not a conflict.
+            if ((0, apply_1.isEmptyLeftover)(stat))
+                continue;
+            if (!stat.isFile() || stat.isSymbolicLink() || fs_1.default.readFileSync(target, 'utf8') !== note.content)
+                conflicts.push(note.relPath);
+            else
+                unchangedPaths.push(note.relPath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    return { conflicts, unchangedPaths, toWrite: plan.notes.length - unchangedPaths.length - conflicts.length };
+}
+function journalPath(ctx, batchId) {
+    batchIdSchema.parse(batchId);
+    const target = safeTarget(ctx.memoryDir, `${forgetImported_1.IMPORT_JOURNAL_DIR}/${batchId}.json`);
+    const dir = path_1.default.dirname(target);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { mode: 0o700 });
+    try {
+        const stat = fs_1.default.lstatSync(target);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw (0, toolRefusal_1.refusal)('unsafe_path', 'Unsafe import journal');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    return target;
+}
+/** The sidecar log of a batch, beside its manifest (journalLog.ts). */
+function journalLogPath(ctx, batchId) {
+    return path_1.default.join(path_1.default.dirname(journalPath(ctx, batchId)), (0, journalLog_1.journalLogName)(batchId));
+}
+function writeJournal(ctx, manifest) {
+    const target = journalPath(ctx, manifest.batchId);
+    const tmp = `${target}.${crypto_1.default.randomUUID()}.tmp`;
+    // Synced before the rename: the journal is what undo_import and a restart trust to name the notes this batch created.
+    const fd = fs_1.default.openSync(tmp, 'wx', 0o600);
+    try {
+        fs_1.default.writeFileSync(fd, JSON.stringify(manifest));
+        fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    fs_1.default.renameSync(tmp, target);
+    // A manifest that is no longer applying holds every note, so the batch's log is only a duplicate of it now.
+    if (manifest.state !== 'applying')
+        (0, journalLog_1.removeJournalLog)(path_1.default.join(path_1.default.dirname(target), (0, journalLog_1.journalLogName)(manifest.batchId)));
+}
+function readJournal(ctx, batchId) {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(journalPath(ctx, batchId), 'utf8'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+function manifests(ctx) {
+    const dir = safeTarget(ctx.memoryDir, '.renor-imports');
+    try {
+        return fs_1.default.readdirSync(dir).flatMap(name => {
+            if (!/^[0-9a-f-]{36}\.json$/i.test(name))
+                return [];
+            return [JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, name), 'utf8'))];
+        });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+}
+/** Dry run: bounded, expiring staging in tenant-local memory; no memory writes. */
+async function previewImport(ctx, input) {
+    const parsed = zod_1.z.object(exports.importPreviewSchema).strict().parse(input);
+    // "./notes/a.md" is the same file as "notes/a.md".
+    const args = { ...parsed, files: parsed.files.map(file => ({ ...file, relativePath: file.relativePath.replace(/^(\.\/)+/, '') })) };
+    const label = folderLabel(args.label);
+    for (const prefix of [...(args.include ?? []), ...(args.exclude ?? [])]) {
+        if (prefix.split('/').includes('..'))
+            throw new Error('include/exclude prefixes are folder paths inside the import, like "Projects"; they cannot contain "..".');
+    }
+    let bytes = 0;
+    const paths = new Set();
+    for (const [i, file] of args.files.entries()) {
+        validatePath(file.relativePath, i);
+        if (paths.has(file.relativePath))
+            throw (0, toolRefusal_1.refusal)('duplicate_import_path', `files[${i}]: the same relativePath was sent twice; send each file once.`);
+        paths.add(file.relativePath);
+        const size = Buffer.byteLength(file.markdown, 'utf8');
+        bytes += size + Buffer.byteLength(file.relativePath, 'utf8');
+        if (size > exports.IMPORT_LIMITS.fileBytes)
+            throw (0, toolRefusal_1.refusal)('import_too_large', `files[${i}]: over 64 KiB. Split it into several smaller .md files (by heading) or leave it out.`);
+        if (bytes > exports.IMPORT_LIMITS.batchBytes)
+            throw (0, toolRefusal_1.refusal)('import_too_large', 'Import is over 128 KiB in total, paths included. Send fewer files per call: call preview_import again for each group; every call gets its own batchId and applies on its own.');
+        if (invalidUnicode(file.markdown))
+            throw (0, toolRefusal_1.refusal)('invalid_text', `files[${i}]: the text has invalid Unicode; send plain UTF-8 Markdown.`);
+        // A control character is refused as it is in a note or a statement (memory/controls.ts): the note is
+        // written into the vault and indexed, so what the preview admits the workspace holds afterwards.
+        try {
+            (0, controls_1.assertNoUnstorableControls)(`files[${i}] (${file.relativePath})`, file.markdown);
+        }
+        catch (err) {
+            throw (0, toolRefusal_1.refusal)('invalid_text', err instanceof Error ? err.message : String(err));
+        }
+    }
+    const skipped = [];
+    const notes = args.files.flatMap(file => {
+        if (file.relativePath.split('/').some(part => part.startsWith('.') || part === 'node_modules')) {
+            skipped.push({ relativePath: file.relativePath, reason: "hidden or node_modules path (a name starts with '.'); to import it, resend under a path without the leading '.' folder, e.g. memory/note.md" });
+            return [];
+        }
+        if (!(0, source_1.isSelected)(file.relativePath, { include: args.include ?? [], exclude: args.exclude ?? [] })) {
+            skipped.push({ relativePath: file.relativePath, reason: 'selection' });
+            return [];
+        }
+        if ((0, invisibleText_1.isBlankOrInvisible)(file.markdown)) {
+            skipped.push({ relativePath: file.relativePath, reason: 'empty note' });
+            return [];
+        }
+        return [(0, markdown_1.parseMarkdownImportNote)(file.relativePath, file.relativePath, file.markdown, new Date().toISOString())];
+    });
+    const bundle = {
+        format: types_1.BUNDLE_FORMAT, sourceLabel: label, notes, facts: [],
+        stats: { notesAvailable: args.files.length, notesSelected: notes.length, notesFilteredOut: skipped.length,
+            notesWithOriginalBytes: notes.length, chunksSelected: notes.reduce((sum, note) => sum + note.chunks.length, 0), factsAvailable: 0, factsSelected: 0 },
+    };
+    const plan = (0, plan_1.buildImportPlan)(bundle, { namespace: `Imported/${label}`, label, eventSource: 'import:markdown' });
+    const { conflicts, unchangedPaths, toWrite } = inspect(ctx, plan);
+    const report = { namespace: plan.namespace, counts: plan.counts, conflicts, unchanged: unchangedPaths.length, toWrite, skipped, limits: exports.IMPORT_LIMITS,
+        // RENOR_SECRET_GUARD on: the notes the plan left out because they look like a secret, by path and field, never text.
+        ...(plan.skipped.secretGuard ? { secretGuard: plan.skipped.secretGuard } : {}) };
+    // A check holds nothing: a reviewer can check every batch of a large import before choosing, which the
+    // bounded staging below (8 previews, 15 minutes) could not hold, and the notes leave the process with the reply.
+    // It also names the notes already there unchanged, so a reviewer is not offered them as new.
+    if (args.stage === false)
+        return { ok: true, staged: false, ...report, unchangedPaths };
+    const previews = state(ctx.db).previews;
+    for (const [id, preview] of previews)
+        if (preview.expiresAt <= Date.now())
+            previews.delete(id);
+    if (previews.size >= 8)
+        throw (0, toolRefusal_1.refusal)('too_many_previews', 'Too many pending previews (8). Call apply_import for one of them, or wait up to 15 minutes for the rest to expire.');
+    const batchId = crypto_1.default.randomUUID();
+    const expiresAt = Date.now() + PREVIEW_MS;
+    previews.set(batchId, { bundle, plan, expiresAt });
+    return { ok: true, batchId, expiresAt: new Date(expiresAt).toISOString(), ...report };
+}
+function applyHostedImport(ctx, batchId, storageLimitBytes) {
+    return serial(ctx.db, async () => {
+        const existing = readJournal(ctx, batchId);
+        if (existing?.state === 'applied')
+            return { ok: true, batchId, ...existing.result };
+        if (existing?.state === 'undone')
+            throw (0, toolRefusal_1.refusal)('batch_already_applied', 'This batch was undone. Call preview_import again for a new batchId.');
+        if (existing)
+            throw (0, toolRefusal_1.refusal)('batch_already_applied', 'This batch did not finish applying and cannot be applied again. Call undo_import with this batchId, then preview_import again.');
+        const preview = state(ctx.db).previews.get(batchId);
+        if (!preview || preview.expiresAt <= Date.now())
+            throw (0, toolRefusal_1.refusal)('batch_not_found', 'Preview missing or expired; preview this batch again');
+        inspect(ctx, preview.plan);
+        const manifest = { batchId, state: 'applying', created: [], reasserted: [] };
+        writeJournal(ctx, manifest);
+        state(ctx.db).previews.delete(batchId);
+        // Each note is logged as it is journalled (journalLog.ts); the manifest is rewritten in full once, when the batch ends.
+        const log = new journalLog_1.JournalLog(journalLogPath(ctx, batchId));
+        try {
+            const result = await (0, apply_1.applyImportPlan)(preview.plan, preview.bundle, {
+                memoryDir: ctx.memoryDir, dbPath: ctx.db.name, ledgerRelPath: ctx.ledgerRelPath,
+                onNoteCreated(note) {
+                    manifest.created.push({ relPath: note.relPath, hash: note.contentHash });
+                    log.append({ list: 'created', relPath: note.relPath, hash: note.contentHash });
+                },
+                onNoteUnchanged(note) {
+                    manifest.reasserted.push({ relPath: note.relPath, hash: note.contentHash });
+                    log.append({ list: 'reasserted', relPath: note.relPath, hash: note.contentHash });
+                },
+                ...(storageLimitBytes === undefined ? {} : { validateBeforeCommit: async () => {
+                        const bytes = await (0, storedSize_1.measureMarkdownBytes)(ctx.memoryDir);
+                        if (bytes > storageLimitBytes) {
+                            throw new apply_1.ImportStorageLimitError(`Renor: this workspace would store ${bytes.toLocaleString('en-US')} bytes of Markdown; the storage limit is ${storageLimitBytes.toLocaleString('en-US')} bytes. This memory write was not run.`);
+                        }
+                    } }),
+            });
+            log.close();
+            manifest.result = result;
+            manifest.state = 'applied';
+            writeJournal(ctx, manifest);
+            return { ok: true, batchId, ...result, recall: ctx.indexOptions.embeddingProvider && result.indexRows.chunksInserted > 0
+                    ? 'Keyword recall is ready through search_text. The new notes are embedded in the background: search by meaning finds them once memory_status says semantic: true. No structured facts were generated.'
+                    : 'Keyword recall is ready through search_text; no embeddings or structured facts were generated.' };
+        }
+        catch (err) {
+            log.close();
+            manifest.state = 'failed';
+            writeJournal(ctx, manifest);
+            if (err instanceof apply_1.ImportStorageLimitError)
+                throw (0, toolRefusal_1.refusal)('storage_limit', err.message);
+            throw err;
+        }
+    });
+}
+// The owner changed what is on disk since the import, or the secret guard will not move the note (it stays live):
+// keep it and carry on undoing the rest of the batch.
+const UNDO_PRESERVES = new Set([
+    'imported note changed; preserved', 'memory path goes through a symbolic link', 'Unsafe import destination ancestor',
+]);
+/** Files can change independently of the journal. Inspect them without letting one bad path abort the batch. */
+function inspectUndoTarget(ctx, relPath) {
+    try {
+        const target = safeTarget(ctx.memoryDir, relPath);
+        const stat = fs_1.default.lstatSync(target, { throwIfNoEntry: false });
+        if (!stat)
+            return { state: 'gone' };
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return { state: 'preserved' };
+        const bytes = fs_1.default.readFileSync(target, 'utf8');
+        return { state: 'file', hash: crypto_1.default.createHash('sha256').update(bytes, 'utf8').digest('hex') };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { state: 'gone' };
+        return { state: 'preserved' };
+    }
+}
+/** Uses the existing journalled retirement, including FTS/vector removal. */
+function undoHostedImport(ctx, batchId) {
+    return serial(ctx.db, async () => {
+        const manifest = readJournal(ctx, batchId);
+        if (!manifest)
+            throw (0, toolRefusal_1.refusal)('batch_not_found', 'No applied batch has this batchId: it was only previewed (never applied), or it belongs to another workspace. undo_import only reverses an applied batch.');
+        // A batch that crashed while applying keeps its notes in its log, not its manifest (journalLog.ts). They move into the
+        // manifest before anything is undone, and the batch is then a failed one whose manifest is whole. A batch with no log
+        // is left as it is: an older engine wrote its notes into the manifest itself.
+        if (manifest.state === 'applying') {
+            const logged = (0, journalLog_1.readJournalLog)(journalLogPath(ctx, batchId));
+            if (logged) {
+                manifest.created = logged.filter(entry => entry.list === 'created').map(({ relPath, hash }) => ({ relPath, hash }));
+                manifest.reasserted = logged.filter(entry => entry.list === 'reasserted').map(({ relPath, hash }) => ({ relPath, hash }));
+                manifest.state = 'failed';
+                writeJournal(ctx, manifest);
+            }
+        }
+        const preserved = [];
+        const preservedReasons = {};
+        let retired = 0;
+        const all = manifests(ctx);
+        for (const note of manifest.created) {
+            if (note.retired)
+                continue;
+            // A batch can find a created note unchanged only after its creator wrote it, so no wall-clock ordering field is
+            // needed (and clock rollback cannot reverse ownership).
+            const heldLater = all.some(other => other.batchId !== batchId && other.state === 'applied'
+                && other.reasserted?.some(item => !item.retired && item.relPath === note.relPath && item.hash === note.hash));
+            if (heldLater) {
+                const target = inspectUndoTarget(ctx, note.relPath);
+                if (target.state === 'preserved') {
+                    preserved.push(note.relPath);
+                    continue;
+                }
+                if (target.state === 'file' && target.hash === note.hash) {
+                    preserved.push(note.relPath);
+                    preservedReasons[note.relPath] = 'kept: re-asserted by a later import';
+                    note.retired = true; // This creator released its assertion; the later batch now owns final retirement.
+                    writeJournal(ctx, manifest);
+                    continue;
+                }
+                if (target.state === 'gone') {
+                    note.retired = true;
+                    writeJournal(ctx, manifest);
+                    continue;
+                }
+            }
+            let outcome;
+            try {
+                const target = inspectUndoTarget(ctx, note.relPath);
+                if (target.state === 'gone')
+                    outcome = 'gone';
+                else if (target.state === 'preserved') {
+                    preserved.push(note.relPath);
+                    continue;
+                }
+                else {
+                    await (0, memoryMap_1.retireMemory)(ctx, `note:${note.relPath}`, note.hash);
+                    outcome = 'retired';
+                }
+            }
+            catch (err) {
+                if (err instanceof secretGuard_1.SecretRefusedError || (err instanceof Error && UNDO_PRESERVES.has(err.message))) {
+                    preserved.push(note.relPath);
+                    continue;
+                }
+                throw err;
+            }
+            // Outside the try: a journal fault must abort the undo, never read as a preserved note.
+            note.retired = true;
+            if (outcome === 'retired')
+                retired++;
+            writeJournal(ctx, manifest);
+        }
+        for (const note of manifest.reasserted ?? []) {
+            if (note.retired)
+                continue;
+            const creatorUndone = all.some(other => other.batchId !== batchId && other.state === 'undone'
+                && other.created.some(item => item.relPath === note.relPath && item.hash === note.hash));
+            const heldElsewhere = all.some(other => other.batchId !== batchId && other.state === 'applied'
+                && other.reasserted?.some(item => !item.retired && item.relPath === note.relPath && item.hash === note.hash));
+            if (creatorUndone && !heldElsewhere) {
+                const target = inspectUndoTarget(ctx, note.relPath);
+                if (target.state === 'preserved') {
+                    preserved.push(note.relPath);
+                    continue;
+                }
+                try {
+                    if (target.state === 'file') {
+                        await (0, memoryMap_1.retireMemory)(ctx, `note:${note.relPath}`, note.hash);
+                        retired++;
+                    }
+                }
+                catch (err) {
+                    if (err instanceof secretGuard_1.SecretRefusedError || (err instanceof Error && UNDO_PRESERVES.has(err.message))) {
+                        preserved.push(note.relPath);
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            note.retired = true;
+            writeJournal(ctx, manifest);
+        }
+        manifest.state = 'undone';
+        writeJournal(ctx, manifest);
+        return { ok: true, batchId, retired, preserved, ...(Object.keys(preservedReasons).length ? { preservedReasons } : {}), alreadyUndone: retired === 0 && preserved.length === 0 };
+    });
+}

package/dist/importing/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCarriedFact = exports.tryNormalizeScope = exports.toCanonicalInstant = exports.deterministicEventId = exports.renderNoteMarkdown = exports.destinationRelPath = exports.readExistingStreams = exports.applyImportPlan = exports.streamKey = exports.contentHash = exports.buildImportPlan = exports.toRelative = exports.isSelected = exports.readSource = exports.readRenorIndexSource = exports.readBundleSource = exports.readMarkdownSource = exports.BUNDLE_FORMAT = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "BUNDLE_FORMAT", { enumerable: true, get: function () { return types_1.BUNDLE_FORMAT; } });
+var markdown_1 = require("./markdown");
+Object.defineProperty(exports, "readMarkdownSource", { enumerable: true, get: function () { return markdown_1.readMarkdownSource; } });
+var source_1 = require("./source");
+Object.defineProperty(exports, "readBundleSource", { enumerable: true, get: function () { return source_1.readBundleSource; } });
+Object.defineProperty(exports, "readRenorIndexSource", { enumerable: true, get: function () { return source_1.readRenorIndexSource; } });
+Object.defineProperty(exports, "readSource", { enumerable: true, get: function () { return source_1.readSource; } });
+Object.defineProperty(exports, "isSelected", { enumerable: true, get: function () { return source_1.isSelected; } });
+Object.defineProperty(exports, "toRelative", { enumerable: true, get: function () { return source_1.toRelative; } });
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "buildImportPlan", { enumerable: true, get: function () { return plan_1.buildImportPlan; } });
+Object.defineProperty(exports, "contentHash", { enumerable: true, get: function () { return plan_1.contentHash; } });
+Object.defineProperty(exports, "streamKey", { enumerable: true, get: function () { return plan_1.streamKey; } });
+var apply_1 = require("./apply");
+Object.defineProperty(exports, "applyImportPlan", { enumerable: true, get: function () { return apply_1.applyImportPlan; } });
+var existing_1 = require("./existing");
+Object.defineProperty(exports, "readExistingStreams", { enumerable: true, get: function () { return existing_1.readExistingStreams; } });
+var serialize_1 = require("./serialize");
+Object.defineProperty(exports, "destinationRelPath", { enumerable: true, get: function () { return serialize_1.destinationRelPath; } });
+Object.defineProperty(exports, "renderNoteMarkdown", { enumerable: true, get: function () { return serialize_1.renderNoteMarkdown; } });
+var facts_1 = require("./facts");
+Object.defineProperty(exports, "deterministicEventId", { enumerable: true, get: function () { return facts_1.deterministicEventId; } });
+Object.defineProperty(exports, "toCanonicalInstant", { enumerable: true, get: function () { return facts_1.toCanonicalInstant; } });
+Object.defineProperty(exports, "tryNormalizeScope", { enumerable: true, get: function () { return facts_1.tryNormalizeScope; } });
+Object.defineProperty(exports, "validateCarriedFact", { enumerable: true, get: function () { return facts_1.validateCarriedFact; } });