@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/knowledge/catalog.d.ts

@@ -0,0 +1,47 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type DocumentCatalog, type DocumentLocation, type DocumentRecord } from '../schemas/document.js';
+import { type Outcome } from '../schemas/outcome.js';
+import type { KnowledgeContext } from './context.js';
+import { type KnowledgePaths } from './paths.js';
+export declare const DEFAULT_CATALOG_MAX_BYTES: number;
+export type CatalogScope = 'shared' | 'private';
+export interface CatalogFileState {
+    readonly scope: CatalogScope;
+    readonly path: string;
+    readonly exists: boolean;
+    readonly digest: string | null;
+    readonly catalog: DocumentCatalog | null;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly valid: boolean;
+}
+export interface KnowledgeCatalogs {
+    readonly paths: KnowledgePaths;
+    readonly shared: CatalogFileState;
+    readonly private: CatalogFileState;
+    readonly records: ReadonlyMap<string, DocumentRecord>;
+    readonly idConflicts: ReadonlySet<string>;
+    readonly locationConflicts: ReadonlySet<string>;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly catalogDigest: string;
+    readonly ok: boolean;
+}
+export declare function emptyCatalog(context: KnowledgeContext, updatedAt?: string): DocumentCatalog;
+export declare function catalogDigestFor(catalogs: KnowledgeCatalogs, scope: CatalogScope): string | null;
+export declare function catalogScopeFor(record: DocumentRecord): CatalogScope;
+export declare function locationKey(location: DocumentLocation): string;
+export declare function loadKnowledgeCatalogs(context: KnowledgeContext): Promise<KnowledgeCatalogs>;
+export declare function recordScope(catalogs: KnowledgeCatalogs, record: DocumentRecord): CatalogScope;
+export declare function catalogFor(catalogs: KnowledgeCatalogs, scope: CatalogScope, context: KnowledgeContext): DocumentCatalog;
+export declare function recordsForCatalog(catalog: DocumentCatalog, documentId: string, next: DocumentRecord | null): DocumentRecord[];
+export declare function setCatalogRecord(context: KnowledgeContext, catalogs: KnowledgeCatalogs, record: DocumentRecord): {
+    readonly scope: CatalogScope;
+    readonly catalog: DocumentCatalog;
+};
+export declare function removeCatalogRecord(context: KnowledgeContext, catalogs: KnowledgeCatalogs, record: DocumentRecord): {
+    readonly scope: CatalogScope;
+    readonly catalog: DocumentCatalog;
+};
+export declare function writeCatalogFile(context: KnowledgeContext, scope: CatalogScope, catalog: DocumentCatalog, expectedDigest: string | null): Promise<Outcome<{
+    readonly path: string;
+    readonly digest: string;
+}>>;

package/dist/knowledge/catalog.js

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, rename, rm } from 'node:fs/promises';
+import { dirname } 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 { failed, succeeded } from '../schemas/outcome.js';
+import { observePath, readFileBounded, readTextFileBounded, sha256Digest, } from '../infra/fs.js';
+import { ensureKnowledgePathBoundary, knowledgePaths, } from './paths.js';
+export const DEFAULT_CATALOG_MAX_BYTES = 8 * 1024 * 1024;
+export function emptyCatalog(context, updatedAt = new Date().toISOString()) {
+    return {
+        schema: DOCUMENT_CATALOG_SCHEMA,
+        workspaceId: context.config.workspaceId,
+        updatedAt,
+        records: [],
+    };
+}
+export function catalogDigestFor(catalogs, scope) {
+    return scope === 'shared' ? catalogs.shared.digest : catalogs.private.digest;
+}
+export function catalogScopeFor(record) {
+    return record.visibility === 'shareable' ? 'shared' : 'private';
+}
+export function locationKey(location) {
+    return location.kind === 'workspace'
+        ? `workspace:${location.path}`
+        : `source:${location.sourceId}:${location.path}`;
+}
+function catalogDiagnostic(code, message, source, hint) {
+    return createDiagnostic({ code, severity: 'error', message, source, hint });
+}
+function isUnknownRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+async function readCatalogFile(context, scope, path) {
+    let observation;
+    try {
+        observation = await observePath(path);
+    }
+    catch (error) {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: null,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(diagnosticCodes.fileUnreadable, `Cannot inspect document catalog ${path}: ${error instanceof Error ? error.message : String(error)}`, path, 'Check permissions; Pappra does not overwrite an unreadable catalog.'),
+            ],
+            valid: false,
+        };
+    }
+    if (observation.kind === 'missing') {
+        return {
+            scope,
+            path,
+            exists: false,
+            digest: null,
+            catalog: null,
+            diagnostics: [],
+            valid: true,
+        };
+    }
+    if (observation.kind !== 'file') {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: null,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(diagnosticCodes.document_catalog_invalid, `Document catalog is not a regular file: ${path}`, path, 'Inspect the catalog; Pappra does not follow or replace it automatically.'),
+            ],
+            valid: false,
+        };
+    }
+    const read = await readTextFileBounded(path, DEFAULT_CATALOG_MAX_BYTES);
+    if (!read.ok) {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: null,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(read.code, read.message, path, read.nextAction ?? 'Inspect the catalog file.'),
+            ],
+            valid: false,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(read.value.text);
+    }
+    catch (error) {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: null,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(diagnosticCodes.document_catalog_invalid, `Document catalog is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, path, 'Repair the catalog manually; Pappra does not overwrite corrupted records.'),
+            ],
+            valid: false,
+        };
+    }
+    if (isUnknownRecord(raw) &&
+        'schema' in raw &&
+        typeof raw.schema === 'string' &&
+        raw.schema !== DOCUMENT_CATALOG_SCHEMA) {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: read.value.digest,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(diagnosticCodes.document_catalog_unsupported, `Unsupported document catalog schema: ${raw.schema}`, path, 'Keep the catalog read-only until a migration is explicitly reviewed.'),
+            ],
+            valid: false,
+        };
+    }
+    const parsed = documentCatalogSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            scope,
+            path,
+            exists: true,
+            digest: read.value.digest,
+            catalog: null,
+            diagnostics: [
+                catalogDiagnostic(diagnosticCodes.document_catalog_invalid, `Document catalog is invalid: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`, path, 'Repair the catalog manually; Pappra does not migrate or overwrite it.'),
+            ],
+            valid: false,
+        };
+    }
+    const diagnostics = [];
+    if (parsed.data.workspaceId !== context.config.workspaceId) {
+        diagnostics.push(catalogDiagnostic(diagnosticCodes.document_catalog_conflict, `Catalog belongs to workspace ${parsed.data.workspaceId}, not ${context.config.workspaceId}.`, path, 'Inspect the catalog identity; do not reuse a catalog from another workspace.'));
+    }
+    for (const record of parsed.data.records) {
+        const expectedScope = catalogScopeFor(record);
+        if (expectedScope !== scope) {
+            diagnostics.push(catalogDiagnostic(diagnosticCodes.document_catalog_conflict, `${scope} catalog contains a ${record.visibility} record ${record.documentId}.`, path, 'Private and shareable records belong in their respective catalogs.'));
+        }
+    }
+    return {
+        scope,
+        path,
+        exists: true,
+        digest: read.value.digest,
+        catalog: parsed.data,
+        diagnostics,
+        valid: diagnostics.length === 0,
+    };
+}
+function combineDiagnostics(shared, privateState) {
+    return [...shared.diagnostics, ...privateState.diagnostics];
+}
+export async function loadKnowledgeCatalogs(context) {
+    const paths = knowledgePaths(context.root);
+    const shared = await readCatalogFile(context, 'shared', paths.sharedCatalog);
+    const privateState = await readCatalogFile(context, 'private', paths.privateCatalog);
+    const diagnostics = combineDiagnostics(shared, privateState);
+    const records = new Map();
+    const locations = new Map();
+    const idConflicts = new Set();
+    const locationConflicts = new Set();
+    for (const file of [shared, privateState]) {
+        if (file.catalog === null)
+            continue;
+        for (const record of file.catalog.records) {
+            const existing = records.get(record.documentId);
+            if (existing !== undefined) {
+                idConflicts.add(record.documentId);
+                diagnostics.push(catalogDiagnostic(diagnosticCodes.document_duplicate_id, `Document id ${record.documentId} appears more than once.`, file.path, 'Resolve the duplicate manually; Pappra does not choose a record.'));
+            }
+            else {
+                records.set(record.documentId, record);
+            }
+            const key = locationKey(record.location);
+            const owner = locations.get(key);
+            if (owner !== undefined && owner !== record.documentId) {
+                locationConflicts.add(key);
+                diagnostics.push(catalogDiagnostic(diagnosticCodes.document_location_conflict, `Location ${key} is registered by both ${owner} and ${record.documentId}.`, file.path, 'Resolve the location conflict manually; Pappra does not overwrite either record.'));
+            }
+            else {
+                locations.set(key, record.documentId);
+            }
+        }
+    }
+    const catalogDigest = sha256Digest(`${shared.digest ?? 'missing'}\n${privateState.digest ?? 'missing'}\n`);
+    return {
+        paths,
+        shared,
+        private: privateState,
+        records,
+        idConflicts,
+        locationConflicts,
+        diagnostics,
+        catalogDigest,
+        ok: diagnostics.every((entry) => entry.severity !== 'error'),
+    };
+}
+export function recordScope(catalogs, record) {
+    if (catalogs.shared.catalog?.records.some((entry) => entry.documentId === record.documentId) === true) {
+        return 'shared';
+    }
+    return 'private';
+}
+export function catalogFor(catalogs, scope, context) {
+    const file = scope === 'shared' ? catalogs.shared : catalogs.private;
+    return file.catalog ?? emptyCatalog(context);
+}
+export function recordsForCatalog(catalog, documentId, next) {
+    const records = catalog.records.filter((record) => record.documentId !== documentId);
+    if (next !== null)
+        records.push(next);
+    return records.sort((left, right) => left.documentId.localeCompare(right.documentId));
+}
+export function setCatalogRecord(context, catalogs, record) {
+    const scope = catalogScopeFor(record);
+    const catalog = catalogFor(catalogs, scope, context);
+    return {
+        scope,
+        catalog: {
+            ...catalog,
+            updatedAt: new Date().toISOString(),
+            records: recordsForCatalog(catalog, record.documentId, record),
+        },
+    };
+}
+export function removeCatalogRecord(context, catalogs, record) {
+    const scope = recordScope(catalogs, record);
+    const catalog = catalogFor(catalogs, scope, context);
+    return {
+        scope,
+        catalog: {
+            ...catalog,
+            updatedAt: new Date().toISOString(),
+            records: recordsForCatalog(catalog, record.documentId, null),
+        },
+    };
+}
+export async function writeCatalogFile(context, scope, catalog, expectedDigest) {
+    const path = scope === 'shared'
+        ? knowledgePaths(context.root).sharedCatalog
+        : knowledgePaths(context.root).privateCatalog;
+    const boundary = await ensureKnowledgePathBoundary(context.root, path);
+    if (!boundary.ok)
+        return boundary;
+    const current = await observePath(path);
+    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.' });
+    }
+    const bytes = Buffer.from(`${JSON.stringify(parsed.data, null, 2)}\n`);
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    let handle;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        handle = await open(temporary, 'wx', scope === 'shared' ? 0o644 : 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        const currentObservation = await observePath(path).catch(() => null);
+        let currentDigest = null;
+        if (currentObservation?.kind === 'missing') {
+            currentDigest = null;
+        }
+        else if (currentObservation?.kind === 'file') {
+            const current = await readFileBounded(path, DEFAULT_CATALOG_MAX_BYTES);
+            if (!current.ok) {
+                await rm(temporary, { force: true }).catch(() => undefined);
+                return current;
+            }
+            currentDigest = current.value.digest;
+        }
+        else {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            return failed(diagnosticCodes.document_catalog_conflict, `Catalog path changed to a non-regular file during commit: ${path}`, { nextAction: 'Inspect the catalog; no replacement was committed.' });
+        }
+        if (currentDigest !== expectedDigest) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            return failed(diagnosticCodes.document_catalog_conflict, `Catalog changed before commit: ${path}`, {
+                nextAction: 'Reload the catalog and regenerate the proposal; no catalog replacement was committed.',
+            });
+        }
+        await rename(temporary, path);
+        return succeeded({ path, digest: sha256Digest(bytes) });
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        return failed(diagnosticCodes.fileUnreadable, `Cannot write document catalog ${path}: ${error instanceof Error ? error.message : String(error)}`, {
+            nextAction: 'Inspect permissions and available disk space; no catalog replacement was claimed.',
+        });
+    }
+}

package/dist/knowledge/context.d.ts

@@ -0,0 +1,28 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { MachineConfig } from '../schemas/machine.js';
+import type { WorkspaceConfig } from '../schemas/workspace.js';
+import type { DiscoveredRepository } from '../workspace/types.js';
+export interface KnowledgeContext {
+    readonly root: string;
+    readonly config: WorkspaceConfig;
+    readonly machine: MachineConfig | null;
+    readonly configPath: string;
+    readonly machinePath: string;
+    readonly repositories: readonly DiscoveredRepository[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly observedAt: string;
+    readonly rootIdentity: {
+        readonly dev: number;
+        readonly ino: number;
+    };
+}
+export interface KnowledgeContextResult {
+    readonly ok: boolean;
+    readonly context: KnowledgeContext | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function loadKnowledgeContext(inputRoot: string): Promise<KnowledgeContextResult>;
+export declare function sameRootIdentity(context: KnowledgeContext, identity: {
+    readonly dev: number;
+    readonly ino: number;
+}): boolean;

package/dist/knowledge/context.js

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
+import { discoverRepositories } from '../workspace/repositories.js';
+import { observePath } from '../infra/fs.js';
+const repositoryDiscoveryOptions = {
+    scanDepth: 0,
+    maxDirectories: 1,
+    maxDocuments: 1,
+    maxEntriesPerDirectory: 1,
+    gitTimeoutMs: 5_000,
+};
+export async function loadKnowledgeContext(inputRoot) {
+    const workspace = await inspectWorkspaceConfig(inputRoot);
+    const diagnostics = [...workspace.diagnostics];
+    if (workspace.value === null) {
+        return { ok: false, context: null, diagnostics };
+    }
+    const machineInspection = await inspectMachineConfig(workspace.root);
+    diagnostics.push(...machineInspection.diagnostics);
+    const machine = machineInspection.value;
+    const discovered = await discoverRepositories({
+        root: workspace.root,
+        config: workspace.value,
+        machine,
+        configPath: workspace.path,
+        options: repositoryDiscoveryOptions,
+    });
+    diagnostics.push(...discovered.diagnostics);
+    const rootObservation = await observePath(workspace.root);
+    if (rootObservation.stats === null) {
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.document_path_unsafe,
+            severity: 'error',
+            message: `Cannot observe workspace root identity: ${workspace.root}`,
+            source: workspace.root,
+            hint: 'Use an existing readable workspace directory.',
+        }));
+        return { ok: false, context: null, diagnostics };
+    }
+    const context = {
+        root: workspace.root,
+        config: workspace.value,
+        machine,
+        configPath: workspace.path,
+        machinePath: join(workspace.root, '.pappra', 'local', 'machine.json'),
+        repositories: discovered.repositories,
+        diagnostics,
+        observedAt: new Date().toISOString(),
+        rootIdentity: {
+            dev: rootObservation.stats.dev,
+            ino: rootObservation.stats.ino,
+        },
+    };
+    return { ok: true, context, diagnostics };
+}
+export function sameRootIdentity(context, identity) {
+    return (context.rootIdentity.dev === identity.dev &&
+        context.rootIdentity.ino === identity.ino);
+}

package/dist/knowledge/index.d.ts

@@ -0,0 +1,3 @@
+export { KnowledgeService } from './service.js';
+export type { ApplyWriteResult, ArchiveDocumentResult, DeleteExplicitInput, DeleteExplicitResult, DocumentCheckEntry, DocumentCheckResult, KnowledgeServiceOptions, ListDocumentsOptions, ListDocumentsResult, PreviewDeleteInput, PreviewDeleteResult, ProposeWriteInput, ProposeWriteResult, ReadDocumentResult, RegisterDocumentInput, RegisterDocumentResult, ShareDocumentResult, SupersedeDocumentInput, SupersedeDocumentResult, } from './types.js';
+export type { FreshnessReport, Freshness } from './refs.js';

package/dist/knowledge/index.js

@@ -0,0 +1 @@
+export { KnowledgeService } from './service.js';

package/dist/knowledge/journal.d.ts

@@ -0,0 +1,16 @@
+import type { Outcome } from '../schemas/outcome.js';
+import { type KnowledgeJournal, type KnowledgeLock } from '../schemas/document.js';
+import type { KnowledgeContext } from './context.js';
+export interface KnowledgeLockAcquireResult {
+    readonly ok: boolean;
+    readonly status: 'acquired' | 'locked' | 'failed';
+    readonly lock: KnowledgeLock | null;
+    readonly path: string;
+    readonly message: string | null;
+}
+export declare function acquireKnowledgeLock(context: KnowledgeContext, operation: KnowledgeLock['operation']): Promise<KnowledgeLockAcquireResult>;
+export declare function releaseKnowledgeLock(lock: KnowledgeLock, path: string): Promise<Outcome<null>>;
+export declare function knowledgeJournalPath(context: KnowledgeContext, operationId: string): string;
+export declare function writeKnowledgeJournal(context: KnowledgeContext, journal: KnowledgeJournal): Promise<Outcome<{
+    readonly path: string;
+}>>;

package/dist/knowledge/journal.js

@@ -0,0 +1,109 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, rename, rm, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+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 { ensureKnowledgePathBoundary, knowledgePaths } from './paths.js';
+function lockFailure(path, status, message) {
+    return { ok: false, status, lock: null, path, message };
+}
+export async function acquireKnowledgeLock(context, operation) {
+    const path = knowledgePaths(context.root).lockPath;
+    const boundary = await ensureKnowledgePathBoundary(context.root, path);
+    if (!boundary.ok) {
+        return lockFailure(path, 'failed', boundary.message);
+    }
+    try {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    catch (error) {
+        return lockFailure(path, 'failed', `Cannot create knowledge state directory: ${errorMessage(error)}`);
+    }
+    const lock = {
+        schema: 'pappra/knowledge-lock/1',
+        token: randomUUID(),
+        operation,
+        pid: process.pid,
+        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;
+        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 &&
+            typeof error.code === 'string'
+            ? error.code
+            : null;
+        return code === 'EEXIST'
+            ? lockFailure(path, 'locked', `Knowledge mutation is already locked: ${path}`)
+            : lockFailure(path, 'failed', `Cannot acquire knowledge lock ${path}: ${errorMessage(error)}`);
+    }
+}
+export async function releaseKnowledgeLock(lock, path) {
+    const read = await readTextFileBounded(path);
+    if (!read.ok) {
+        return failed(diagnosticCodes.document_locked, `Cannot verify knowledge lock ${path}: ${read.message}`, { nextAction: 'Inspect the lock manually; it was not removed.' });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.value.text);
+    }
+    catch {
+        return failed(diagnosticCodes.document_locked, `Knowledge lock is not valid JSON: ${path}`, { nextAction: 'Inspect the lock manually; it was not removed.' });
+    }
+    const valid = knowledgeLockSchema.safeParse(parsed);
+    if (!valid.success || valid.data.token !== lock.token) {
+        return failed(diagnosticCodes.document_locked, `Knowledge lock ownership changed: ${path}`, { nextAction: 'Inspect the lock manually; it was not removed.' });
+    }
+    try {
+        await unlink(path);
+        return succeeded(null);
+    }
+    catch (error) {
+        return failed(diagnosticCodes.document_locked, `Cannot release knowledge lock ${path}: ${errorMessage(error)}`, { nextAction: 'Inspect the lock manually; it remains as evidence.' });
+    }
+}
+export function knowledgeJournalPath(context, operationId) {
+    return join(knowledgePaths(context.root).journalsDir, `${operationId}.json`);
+}
+export async function writeKnowledgeJournal(context, journal) {
+    const parsed = knowledgeJournalSchema.safeParse(journal);
+    if (!parsed.success) {
+        return failed(diagnosticCodes.document_journal_failed, `Knowledge journal is invalid: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`, {
+            nextAction: 'Inspect the operation state; no recovery state was written.',
+        });
+    }
+    const path = knowledgeJournalPath(context, parsed.data.operationId);
+    const boundary = await ensureKnowledgePathBoundary(context.root, path);
+    if (!boundary.ok)
+        return boundary;
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    const bytes = Buffer.from(`${JSON.stringify(parsed.data, null, 2)}\n`);
+    let handle;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        handle = await open(temporary, 'wx', 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, path);
+        return succeeded({ path });
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        return failed(diagnosticCodes.document_journal_failed, `Cannot write knowledge journal ${path}: ${errorMessage(error)}`, { nextAction: 'Resolve the local state write failure before retrying.' });
+    }
+}

package/dist/knowledge/lifecycle.d.ts

@@ -0,0 +1,8 @@
+import { type KnowledgeDeletePlan } from '../schemas/document.js';
+import type { KnowledgeContext } from './context.js';
+import type { ArchiveDocumentResult, DeleteExplicitResult, PreviewDeleteInput, PreviewDeleteResult, ShareDocumentResult, SupersedeDocumentInput, SupersedeDocumentResult } from './types.js';
+export declare function archiveDocument(context: KnowledgeContext, documentId: string): Promise<ArchiveDocumentResult>;
+export declare function supersedeDocument(context: KnowledgeContext, input: SupersedeDocumentInput): Promise<SupersedeDocumentResult>;
+export declare function shareDocument(context: KnowledgeContext, documentId: string): Promise<ShareDocumentResult>;
+export declare function previewDelete(context: KnowledgeContext, input: PreviewDeleteInput): Promise<PreviewDeleteResult>;
+export declare function deleteExplicit(context: KnowledgeContext, plan: KnowledgeDeletePlan): Promise<DeleteExplicitResult>;