@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/knowledge/catalog.js

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, open, rename, rm } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, open, readdir, rename, rm, unlink } from 'node:fs/promises';
+import { ensurePrivateState } from '../infra/private-state.js';
+import { dirname, join } from 'node:path';
 import { createDiagnostic } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
-import { DOCUMENT_CATALOG_SCHEMA, documentCatalogSchema, } from '../schemas/document.js';
+import { DOCUMENT_CATALOG_SCHEMA, documentCatalogSchema, documentRecordFileSchema, } from '../schemas/document.js';
 import { failed, succeeded } from '../schemas/outcome.js';
 import { observePath, readFileBounded, readTextFileBounded, sha256Digest, } from '../infra/fs.js';
 import { ensureKnowledgePathBoundary, knowledgePaths, } from './paths.js';
@@ -34,6 +35,8 @@ function isUnknownRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 async function readCatalogFile(context, scope, path) {
+    if (scope === 'shared')
+        return readSharedRecords(context, path);
     let observation;
     try {
         observation = await observePath(path);
@@ -156,6 +159,85 @@ async function readCatalogFile(context, scope, path) {
         valid: diagnostics.length === 0,
     };
 }
+async function readSharedRecords(context, path) {
+    const diagnostics = [];
+    const invalid = (message) => ({
+        scope: 'shared',
+        path,
+        exists: true,
+        digest: null,
+        catalog: null,
+        diagnostics: [
+            catalogDiagnostic(diagnosticCodes.document_catalog_invalid, message, path, 'Inspect the per-document records; malformed state is preserved. Legacy catalog.json requires an explicit reset, not an automatic migration.'),
+        ],
+        valid: false,
+    });
+    try {
+        const legacy = await observePath(join(dirname(path), 'catalog.json'));
+        if (legacy.kind !== 'missing')
+            return invalid('Legacy shared catalog.json is unsupported; preserve or export it and explicitly reset the shared catalog before using per-document records.');
+        const observation = await observePath(path);
+        if (observation.kind === 'missing')
+            return {
+                scope: 'shared',
+                path,
+                exists: false,
+                digest: null,
+                catalog: null,
+                diagnostics: [],
+                valid: true,
+            };
+        if (observation.kind !== 'directory')
+            return invalid('Shared document records must be a real directory.');
+        const names = (await readdir(path))
+            .filter((name) => name !== '.DS_Store' && name !== 'Thumbs.db')
+            .sort();
+        if (names.length > 2048)
+            return invalid('Shared document record limit exceeded (2048).');
+        const records = [];
+        const digests = [];
+        const recordDigests = new Map();
+        let totalBytes = 0;
+        for (const name of names) {
+            if (/^[0-9a-f-]{36}\.json\.tmp-[0-9a-f-]{36}$/i.test(name))
+                continue;
+            if (!/^[0-9a-f-]{36}\.json$/i.test(name))
+                return invalid(`Unexpected file in shared records directory: ${name}`);
+            const file = join(path, name);
+            const read = await readTextFileBounded(file, DEFAULT_CATALOG_MAX_BYTES);
+            if (!read.ok)
+                return invalid(`Cannot safely read shared document record: ${name}`);
+            totalBytes += Buffer.byteLength(read.value.text);
+            if (totalBytes > DEFAULT_CATALOG_MAX_BYTES)
+                return invalid('Shared document records exceed the catalog byte budget.');
+            const parsed = documentRecordFileSchema.safeParse(JSON.parse(read.value.text));
+            if (!parsed.success ||
+                `${parsed.data.record.documentId}.json` !== name ||
+                parsed.data.workspaceId !== context.config.workspaceId ||
+                parsed.data.record.visibility !== 'shareable')
+                return invalid(`Invalid document identity, scope or schema in shared record: ${name}`);
+            records.push(parsed.data.record);
+            digests.push(`${name}:${read.value.digest}`);
+            recordDigests.set(parsed.data.record.documentId, read.value.digest);
+        }
+        return {
+            scope: 'shared',
+            path,
+            exists: true,
+            digest: sha256Digest(digests.join('\n')),
+            catalog: {
+                ...emptyCatalog(context, '1970-01-01T00:00:00.000Z'),
+                records,
+            },
+            diagnostics,
+            valid: true,
+            recordDigests,
+        };
+    }
+    catch (error) {
+        return invalid(`Cannot read shared document records: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function combineDiagnostics(shared, privateState) {
     return [...shared.diagnostics, ...privateState.diagnostics];
 }
@@ -180,6 +262,8 @@ export async function loadKnowledgeCatalogs(context) {
             else {
                 records.set(record.documentId, record);
             }
+            if (record.lifecycle === 'archived')
+                continue;
             const key = locationKey(record.location);
             const owner = locations.get(key);
             if (owner !== undefined && owner !== record.documentId) {
@@ -248,6 +332,58 @@ export async function writeCatalogFile(context, scope, catalog, expectedDigest)
     const path = scope === 'shared'
         ? knowledgePaths(context.root).sharedCatalog
         : knowledgePaths(context.root).privateCatalog;
+    const parsed = documentCatalogSchema.safeParse(catalog);
+    if (!parsed.success || catalog.workspaceId !== context.config.workspaceId)
+        return failed(diagnosticCodes.document_record_invalid, 'Refusing to write an invalid catalog or foreign workspace identity.');
+    if (scope === 'shared') {
+        try {
+            return await writeSharedRecords(context, path, parsed.data, expectedDigest);
+        }
+        catch (error) {
+            return failed(diagnosticCodes.fileUnreadable, `Cannot commit shared document records: ${error instanceof Error ? error.message : String(error)}`, {
+                nextAction: 'Inspect permissions and any individually committed records; rerun scan to reconcile without replacing document content.',
+            });
+        }
+    }
+    return writeCatalogBytes(context, path, Buffer.from(`${JSON.stringify(parsed.data, null, 2)}\n`), expectedDigest, scope);
+}
+async function writeSharedRecords(context, path, catalog, expectedDigest) {
+    const boundary = await ensureKnowledgePathBoundary(context.root, path);
+    if (!boundary.ok)
+        return boundary;
+    const before = await readSharedRecords(context, path);
+    if (!before.valid || before.digest !== expectedDigest)
+        return failed(diagnosticCodes.document_catalog_conflict, 'Shared document records changed before commit; reload before retrying.');
+    await mkdir(path, { recursive: true });
+    const previous = new Map(before.catalog?.records.map((record) => [record.documentId, record]) ?? []);
+    for (const record of catalog.records) {
+        const old = previous.get(record.documentId);
+        previous.delete(record.documentId);
+        if (old && JSON.stringify(old) === JSON.stringify(record))
+            continue;
+        const recordPath = join(path, `${record.documentId}.json`);
+        const bytes = Buffer.from(`${JSON.stringify({ schema: 'pappra/document-record-file/1', workspaceId: context.config.workspaceId, record }, null, 2)}\n`);
+        const written = await writeCatalogBytes(context, recordPath, bytes, before.recordDigests?.get(record.documentId) ?? null, 'shared');
+        if (!written.ok)
+            return written;
+    }
+    for (const record of previous.values()) {
+        const file = join(path, `${record.documentId}.json`);
+        const boundary = await ensureKnowledgePathBoundary(context.root, file);
+        if (!boundary.ok)
+            return boundary;
+        const current = await readTextFileBounded(file, DEFAULT_CATALOG_MAX_BYTES);
+        if (!current.ok ||
+            JSON.stringify(JSON.parse(current.value.text).record) !== JSON.stringify(record))
+            return failed(diagnosticCodes.document_catalog_conflict, 'Shared document record changed before removal.');
+        await unlink(file);
+    }
+    const after = await readSharedRecords(context, path);
+    return after.valid && after.digest !== null
+        ? succeeded({ path, digest: after.digest })
+        : failed(diagnosticCodes.document_catalog_conflict, 'Shared catalog commit is incomplete; inspect the per-document files and retry.');
+}
+async function writeCatalogBytes(context, path, bytes, expectedDigest, scope) {
     const boundary = await ensureKnowledgePathBoundary(context.root, path);
     if (!boundary.ok)
         return boundary;
@@ -255,14 +391,11 @@ export async function writeCatalogFile(context, scope, catalog, expectedDigest)
     if (current.kind !== 'missing' && current.kind !== 'file') {
         return failed(diagnosticCodes.document_path_unsafe, `Catalog path is not a regular file: ${path}`, { nextAction: 'Inspect the catalog path; it was not replaced.' });
     }
-    if (catalog.workspaceId !== context.config.workspaceId) {
-        return failed(diagnosticCodes.document_catalog_conflict, 'Refusing to write a catalog for a different workspace id.', { nextAction: 'Inspect the workspace and catalog identity.' });
-    }
-    const parsed = documentCatalogSchema.safeParse(catalog);
-    if (!parsed.success) {
-        return failed(diagnosticCodes.document_record_invalid, `Refusing to write an invalid catalog: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`, { nextAction: 'Fix the record; no catalog bytes were written.' });
+    if (scope === 'private') {
+        const prepared = await ensurePrivateState(context.root);
+        if (!prepared.ok)
+            return prepared;
     }
-    const bytes = Buffer.from(`${JSON.stringify(parsed.data, null, 2)}\n`);
     const temporary = `${path}.tmp-${randomUUID()}`;
     let handle;
     try {

package/dist/knowledge/journal.js

@@ -5,6 +5,9 @@ import { diagnosticCodes } from '../schemas/errors.js';
 import { errorMessage, failed, succeeded } from '../schemas/outcome.js';
 import { knowledgeJournalSchema, knowledgeLockSchema, } from '../schemas/document.js';
 import { readTextFileBounded } from '../infra/fs.js';
+import { ensurePrivateState } from '../infra/private-state.js';
+import { publishPrivateLock } from '../infra/private-lock.js';
+import { captureProcessIdentity } from '../infra/process-identity.js';
 import { ensureKnowledgePathBoundary, knowledgePaths } from './paths.js';
 function lockFailure(path, status, message) {
     return { ok: false, status, lock: null, path, message };
@@ -15,6 +18,9 @@ export async function acquireKnowledgeLock(context, operation) {
     if (!boundary.ok) {
         return lockFailure(path, 'failed', boundary.message);
     }
+    const prepared = await ensurePrivateState(context.root);
+    if (!prepared.ok)
+        return lockFailure(path, 'failed', prepared.message);
     try {
         await mkdir(dirname(path), { recursive: true });
     }
@@ -26,19 +32,20 @@ export async function acquireKnowledgeLock(context, operation) {
         token: randomUUID(),
         operation,
         pid: process.pid,
+        ...(captureProcessIdentity() === null
+            ? {}
+            : { process_identity: captureProcessIdentity() }),
         createdAt: new Date().toISOString(),
     };
-    let handle;
     try {
-        handle = await open(path, 'wx', 0o600);
-        await handle.writeFile(Buffer.from(`${JSON.stringify(lock, null, 2)}\n`));
-        await handle.sync();
-        await handle.close();
-        handle = undefined;
+        await publishPrivateLock(path, Buffer.from(`${JSON.stringify(lock, null, 2)}\n`), async () => {
+            const current = await ensureKnowledgePathBoundary(context.root, path);
+            if (!current.ok)
+                throw new Error(current.message);
+        });
         return { ok: true, status: 'acquired', lock, path, message: null };
     }
     catch (error) {
-        await handle?.close().catch(() => undefined);
         const code = typeof error === 'object' &&
             error !== null &&
             'code' in error &&
@@ -88,6 +95,9 @@ export async function writeKnowledgeJournal(context, journal) {
     const boundary = await ensureKnowledgePathBoundary(context.root, path);
     if (!boundary.ok)
         return boundary;
+    const prepared = await ensurePrivateState(context.root);
+    if (!prepared.ok)
+        return prepared;
     const temporary = `${path}.tmp-${randomUUID()}`;
     const bytes = Buffer.from(`${JSON.stringify(parsed.data, null, 2)}\n`);
     let handle;

package/dist/knowledge/paths.js

@@ -6,7 +6,7 @@ import { observePath, readFileBounded, resolveRealpath } from '../infra/fs.js';
 export function knowledgePaths(root) {
     const localDir = join(root, '.pappra', 'local', 'knowledge');
     return {
-        sharedCatalog: join(root, '.pappra', 'knowledge', 'catalog.json'),
+        sharedCatalog: join(root, '.pappra', 'knowledge', 'records'),
         privateCatalog: join(localDir, 'catalog.json'),
         localDir,
         lockPath: join(localDir, 'apply.lock'),
@@ -17,6 +17,7 @@ const managedStatePrefixes = [
     '.pappra/local',
     '.pappra/generated',
     '.pappra/knowledge/catalog.json',
+    '.pappra/knowledge/records',
 ];
 /**
  * Rejects a path if its final component or any existing ancestor resolves

package/dist/knowledge/refs.js

@@ -10,6 +10,8 @@ export function findRecord(catalogs, documentId) {
 }
 export async function findCanonicalAlias(context, catalogs, target, ignoreDocumentId = null) {
     for (const record of catalogs.records.values()) {
+        if (record.lifecycle === 'archived')
+            continue;
         if (record.documentId === ignoreDocumentId)
             continue;
         const resolved = await resolveKnowledgeLocation(context, record.location);
@@ -24,6 +26,8 @@ export function findRecordByLocation(catalogs, key) {
     if (catalogs.locationConflicts.has(key))
         return null;
     for (const record of catalogs.records.values()) {
+        if (record.lifecycle === 'archived')
+            continue;
         const recordKey = record.location.kind === 'workspace'
             ? `workspace:${record.location.path}`
             : `source:${record.location.sourceId}:${record.location.path}`;

package/dist/knowledge/register-batch.d.ts

@@ -0,0 +1,4 @@
+import { type KnowledgeContext } from './context.js';
+import type { RegisterDocumentInput, RegisterDocumentResult } from './types.js';
+/** One context, catalog snapshot and lock for a bounded discovery batch. */
+export declare function registerDocumentBatch(context: KnowledgeContext, inputs: readonly RegisterDocumentInput[]): Promise<readonly RegisterDocumentResult[]>;

package/dist/knowledge/register-batch.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { samePath } from '../schemas/paths.js';
+import { observePath } from '../infra/fs.js';
+import { loadKnowledgeContext, sameRootIdentity, } from './context.js';
+import { catalogDigestFor, catalogFor, catalogScopeFor, loadKnowledgeCatalogs, locationKey, writeCatalogFile, } from './catalog.js';
+import { acquireKnowledgeLock, releaseKnowledgeLock, writeKnowledgeJournal, } from './journal.js';
+import { readKnowledgeFile, resolveKnowledgeLocation } from './paths.js';
+import { validateSources } from './refs.js';
+import { validateAndBuildRecord } from './write.js';
+/** One context, catalog snapshot and lock for a bounded discovery batch. */
+export async function registerDocumentBatch(context, inputs) {
+    if (inputs.length === 0)
+        return [];
+    const fail = (message, diagnostics = []) => inputs.map(() => ({
+        ok: false,
+        status: 'failed',
+        record: null,
+        diagnostics: [
+            ...diagnostics,
+            createDiagnostic({
+                code: diagnosticCodes.document_write_conflict,
+                severity: 'error',
+                message,
+                source: context.configPath,
+            }),
+        ],
+    }));
+    const held = await acquireKnowledgeLock(context, 'write-document');
+    if (!held.ok || !held.lock)
+        return fail(held.message ?? 'Knowledge lock is unavailable.');
+    try {
+        const freshContext = await loadKnowledgeContext(context.root);
+        if (!freshContext.ok ||
+            !freshContext.context ||
+            !sameRootIdentity(freshContext.context, context.rootIdentity))
+            return fail('Workspace identity changed before batch registration.', freshContext.diagnostics);
+        context = freshContext.context;
+        const catalogs = await loadKnowledgeCatalogs(context);
+        if (!catalogs.ok)
+            return fail('Catalog conflicts prevent registration.', catalogs.diagnostics);
+        const records = new Map(catalogs.records);
+        const resolvedRecords = [];
+        for (const record of records.values()) {
+            if (record.lifecycle === 'archived')
+                continue;
+            const resolved = await resolveKnowledgeLocation(context, record.location);
+            const observation = resolved.ok
+                ? await observePath(resolved.value.absolutePath).catch(() => null)
+                : null;
+            resolvedRecords.push({
+                record,
+                canonical: resolved.ok && observation?.kind === 'file'
+                    ? resolved.value.canonicalPath
+                    : null,
+                missing: (!resolved.ok &&
+                    resolved.code === diagnosticCodes.document_not_found) ||
+                    observation?.kind === 'missing',
+            });
+        }
+        const results = [];
+        for (const input of inputs) {
+            const diagnostics = [];
+            const conflict = (message) => ({
+                ok: false,
+                status: 'conflict',
+                record: null,
+                diagnostics: [
+                    createDiagnostic({
+                        code: diagnosticCodes.document_location_conflict,
+                        severity: 'error',
+                        message,
+                        source: input.location.path,
+                    }),
+                ],
+            });
+            const resolved = await resolveKnowledgeLocation(context, input.location);
+            if (!resolved.ok) {
+                results.push(conflict(resolved.message));
+                continue;
+            }
+            const file = await readKnowledgeFile(resolved.value.absolutePath, 8 * 1024 * 1024);
+            if (!file.ok) {
+                results.push(conflict(file.message));
+                continue;
+            }
+            const existing = [...records.values()].find((record) => record.lifecycle !== 'archived' &&
+                locationKey(record.location) === locationKey(input.location));
+            if (existing) {
+                results.push(existing.digest === file.value.digest &&
+                    (input.documentId === undefined ||
+                        input.documentId === existing.documentId)
+                    ? { ok: true, status: 'existing', record: existing, diagnostics }
+                    : conflict('An active registration exists with different content; review and update it explicitly.'));
+                continue;
+            }
+            const aliases = resolvedRecords.filter((entry) => entry.canonical !== null &&
+                samePath(entry.canonical, resolved.value.canonicalPath));
+            const moved = aliases.length === 1 ? aliases[0] : undefined;
+            const byDigest = resolvedRecords.filter((entry) => entry.missing && entry.record.digest === file.value.digest);
+            const previous = moved ?? (byDigest.length === 1 ? byDigest[0] : undefined);
+            if (aliases.length > 1 || byDigest.length > 1) {
+                results.push(conflict('Several registrations could identify this path; use docs relocate with an explicit document id.'));
+                continue;
+            }
+            if (previous) {
+                if (previous.record.digest !== file.value.digest ||
+                    (input.documentId !== undefined &&
+                        input.documentId !== previous.record.documentId)) {
+                    results.push(conflict('The canonical document changed; review it before relocation.'));
+                    continue;
+                }
+                const record = {
+                    ...previous.record,
+                    location: resolved.value.location,
+                };
+                records.set(record.documentId, record);
+                previous.record = record;
+                previous.canonical = resolved.value.canonicalPath;
+                previous.missing = false;
+                results.push({ ok: true, status: 'existing', record, diagnostics });
+                continue;
+            }
+            const built = await validateAndBuildRecord(context, input, resolved.value);
+            if (!built.ok) {
+                results.push(conflict(built.message));
+                continue;
+            }
+            const record = { ...built.value, digest: file.value.digest };
+            if (records.has(record.documentId)) {
+                results.push(conflict('Document id is already registered; batch discovery never replaces another document identity.'));
+                continue;
+            }
+            diagnostics.push(...validateSources(context, catalogs, record.documentId, record.visibility, record.sources));
+            if (diagnostics.some((entry) => entry.severity === 'error')) {
+                results.push({
+                    ok: false,
+                    status: 'failed',
+                    record: null,
+                    diagnostics,
+                });
+                continue;
+            }
+            records.set(record.documentId, record);
+            resolvedRecords.push({
+                record,
+                canonical: resolved.value.canonicalPath,
+                missing: false,
+            });
+            results.push({ ok: true, status: 'registered', record, diagnostics });
+        }
+        const changedScopes = ['shared', 'private'].filter((scope) => {
+            const previous = catalogFor(catalogs, scope, context);
+            const next = [...records.values()]
+                .filter((record) => catalogScopeFor(record) === scope)
+                .sort((a, b) => a.documentId < b.documentId
+                ? -1
+                : a.documentId > b.documentId
+                    ? 1
+                    : 0);
+            return JSON.stringify(previous.records) !== JSON.stringify(next);
+        });
+        if (changedScopes.length === 0)
+            return results;
+        const timestamp = new Date().toISOString();
+        const journal = {
+            schema: 'pappra/knowledge-journal/1',
+            operationId: randomUUID(),
+            operation: 'write-document',
+            stage: 'prepared',
+            documentId: null,
+            targetPath: null,
+            catalogScope: null,
+            expectedDigest: null,
+            fileDigest: null,
+            catalogDigest: catalogs.catalogDigest,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            residualPaths: [],
+            detail: `Batch registration of ${inputs.length} discovered documents. Document content is preserved; rerun scan after interruption to reconcile committed metadata.`,
+        };
+        const prepared = await writeKnowledgeJournal(context, journal);
+        if (!prepared.ok)
+            return fail(`Cannot prepare batch registration journal: ${prepared.message}`);
+        for (const scope of changedScopes) {
+            const previous = catalogFor(catalogs, scope, context);
+            const next = [...records.values()]
+                .filter((record) => catalogScopeFor(record) === scope)
+                .sort((a, b) => a.documentId < b.documentId
+                ? -1
+                : a.documentId > b.documentId
+                    ? 1
+                    : 0);
+            if (JSON.stringify(previous.records) === JSON.stringify(next))
+                continue;
+            const written = await writeCatalogFile(context, scope, { ...previous, records: next }, catalogDigestFor(catalogs, scope));
+            if (!written.ok) {
+                await writeKnowledgeJournal(context, {
+                    ...journal,
+                    stage: 'failed',
+                    updatedAt: new Date().toISOString(),
+                    residualPaths: [
+                        catalogs.paths.sharedCatalog,
+                        catalogs.paths.privateCatalog,
+                    ],
+                });
+                return fail(`Batch registration was interrupted: ${written.message}. Rerun scan to reconcile already committed records; document files were not changed.`);
+            }
+        }
+        const completed = await writeKnowledgeJournal(context, {
+            ...journal,
+            stage: 'complete',
+            updatedAt: new Date().toISOString(),
+        });
+        if (!completed.ok)
+            return fail(`Registrations committed but their completion journal could not be saved: ${completed.message}. Rerun scan before treating coverage as complete.`);
+        return results;
+    }
+    finally {
+        const released = await releaseKnowledgeLock(held.lock, held.path);
+        if (!released.ok)
+            return fail('Registration may have committed, but its lock could not be released; inspect the catalog before retrying.');
+    }
+}

package/dist/knowledge/relocate.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentLocation } from '../schemas/document.js';
+import type { KnowledgeContext } from './context.js';
+import { type CatalogScope } from './catalog.js';
+import type { RegisterDocumentResult } from './types.js';
+export declare function relocateOrForgetDocument(context: KnowledgeContext, documentId: string, location: DocumentLocation | null, scope?: CatalogScope): Promise<RegisterDocumentResult>;

package/dist/knowledge/relocate.js

@@ -0,0 +1,92 @@
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { loadKnowledgeContext, sameRootIdentity } from './context.js';
+import { catalogDigestFor, catalogFor, loadKnowledgeCatalogs, recordScope, recordsForCatalog, setCatalogRecord, writeCatalogFile, } from './catalog.js';
+import { acquireKnowledgeLock, releaseKnowledgeLock } from './journal.js';
+import { findCanonicalAlias, findRecord, findRegisteredReferences, } from './refs.js';
+import { readKnowledgeFile, resolveKnowledgeLocation } from './paths.js';
+export async function relocateOrForgetDocument(context, documentId, location, scope) {
+    const failure = (message) => ({
+        ok: false,
+        status: 'conflict',
+        record: null,
+        diagnostics: [
+            createDiagnostic({
+                code: diagnosticCodes.document_write_conflict,
+                severity: 'error',
+                message,
+                source: context.configPath,
+                hint: 'No document content is changed by relocate or forget.',
+            }),
+        ],
+    });
+    if (scope !== undefined &&
+        (!['shared', 'private'].includes(scope) || location !== null))
+        return failure('An explicit shared/private scope is accepted only for forget.');
+    const held = await acquireKnowledgeLock(context, 'write-document');
+    if (!held.ok || !held.lock)
+        return failure(held.message ?? 'Knowledge state is locked.');
+    try {
+        const loaded = await loadKnowledgeContext(context.root);
+        if (!loaded.ok ||
+            !loaded.context ||
+            !sameRootIdentity(loaded.context, context.rootIdentity))
+            return failure('Workspace identity changed.');
+        context = loaded.context;
+        const catalogs = await loadKnowledgeCatalogs(context);
+        if (!catalogs.shared.valid ||
+            !catalogs.private.valid ||
+            (scope === undefined && catalogs.idConflicts.size > 0))
+            return {
+                ok: false,
+                status: 'conflict',
+                record: null,
+                diagnostics: [...catalogs.diagnostics],
+            };
+        const scoped = scope === undefined
+            ? null
+            : catalogFor(catalogs, scope, context).records.filter((entry) => entry.documentId === documentId);
+        const record = scoped === null
+            ? findRecord(catalogs, documentId)
+            : scoped.length === 1
+                ? scoped[0]
+                : null;
+        if (!record)
+            return failure('Document id is not registered or is ambiguous.');
+        if (record.taskId !== null)
+            return failure('Task-linked records require explicit task ownership review before relocating or forgetting.');
+        if (location === null) {
+            const retainedInOtherScope = scope === 'private' &&
+                catalogFor(catalogs, 'shared', context).records.some((entry) => entry.documentId === documentId);
+            if (!retainedInOtherScope &&
+                findRegisteredReferences(catalogs, documentId).length > 0)
+                return failure('Other documents reference this id; update their references before forgetting it.');
+            const removedScope = scope ?? recordScope(catalogs, record);
+            const catalog = catalogFor(catalogs, removedScope, context);
+            const written = await writeCatalogFile(context, removedScope, { ...catalog, records: recordsForCatalog(catalog, documentId, null) }, catalogDigestFor(catalogs, removedScope));
+            return written.ok
+                ? { ok: true, status: 'existing', record, diagnostics: [] }
+                : failure(written.message);
+        }
+        const resolved = await resolveKnowledgeLocation(context, location);
+        if (!resolved.ok)
+            return failure(resolved.message);
+        const file = await readKnowledgeFile(resolved.value.absolutePath, 8 * 1024 * 1024);
+        if (!file.ok || file.value.digest !== record.digest)
+            return failure('Relocation target does not match the registered content digest.');
+        const alias = await findCanonicalAlias(context, catalogs, resolved.value, record.documentId);
+        if (alias)
+            return failure('Relocation target is owned by another active document.');
+        const next = { ...record, location: resolved.value.location };
+        const update = setCatalogRecord(context, catalogs, next);
+        const written = await writeCatalogFile(context, update.scope, update.catalog, catalogDigestFor(catalogs, update.scope));
+        return written.ok
+            ? { ok: true, status: 'existing', record: next, diagnostics: [] }
+            : failure(written.message);
+    }
+    finally {
+        const released = await releaseKnowledgeLock(held.lock, held.path);
+        if (!released.ok)
+            return failure('Metadata may have committed, but its lock could not be released; inspect the catalog before retrying.');
+    }
+}