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

package/dist/knowledge/service.js

@@ -0,0 +1,393 @@
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { loadKnowledgeContext } from './context.js';
+import { loadKnowledgeCatalogs } from './catalog.js';
+import { inspectFreshness, findRecord } from './refs.js';
+import { resolveKnowledgeLocation, readKnowledgeFile } from './paths.js';
+import { applyWrite, proposeWrite, registerDocument } from './write.js';
+import { archiveDocument, deleteExplicit, previewDelete, shareDocument, supersedeDocument, } from './lifecycle.js';
+const MAX_DOCUMENT_BYTES = 8 * 1024 * 1024;
+function outcomeDiagnostic(failure, source) {
+    return createDiagnostic({
+        code: failure.code,
+        severity: 'error',
+        message: failure.message,
+        source,
+        hint: failure.nextAction,
+    });
+}
+function contextFailure(diagnostics) {
+    return { ok: false, diagnostics };
+}
+async function getContext(root) {
+    const loaded = await loadKnowledgeContext(root);
+    if (!loaded.ok || loaded.context === null) {
+        return contextFailure(loaded.diagnostics);
+    }
+    return { ok: true, context: loaded.context };
+}
+function supersessionDiagnostics(records) {
+    const diagnostics = [];
+    const byId = new Map(records.map((record) => [record.documentId, record]));
+    for (const record of records) {
+        if (record.supersededBy === null)
+            continue;
+        const seen = new Set([record.documentId]);
+        let current = record;
+        while (current !== null && current.supersededBy !== null) {
+            if (seen.has(current.supersededBy) &&
+                current.documentId !== record.documentId) {
+                diagnostics.push(createDiagnostic({
+                    code: diagnosticCodes.document_supersede_invalid,
+                    severity: 'error',
+                    message: `Supersession chain contains a cycle at ${current.supersededBy}.`,
+                    source: 'knowledge catalog',
+                    hint: 'Repair the chain manually; Pappra does not rewrite historical decisions.',
+                }));
+                break;
+            }
+            seen.add(current.supersededBy);
+            const next = byId.get(current.supersededBy);
+            if (next === undefined) {
+                diagnostics.push(createDiagnostic({
+                    code: diagnosticCodes.document_supersede_invalid,
+                    severity: 'error',
+                    message: `Supersession target ${current.supersededBy} is missing.`,
+                    source: 'knowledge catalog',
+                    hint: 'Keep superseded documents until their replacement is registered.',
+                }));
+                break;
+            }
+            if (current.visibility === 'shareable' && next.visibility === 'private') {
+                diagnostics.push(createDiagnostic({
+                    code: diagnosticCodes.document_visibility_invalid,
+                    severity: 'error',
+                    message: 'A shareable supersession record points to a private document.',
+                    source: 'knowledge catalog',
+                    hint: 'Keep shared supersession chains within the shared catalog.',
+                }));
+            }
+            current = next;
+        }
+    }
+    return diagnostics;
+}
+function filteredDiagnostics(context, catalogs, includePrivate) {
+    const diagnostics = [...context.diagnostics, ...catalogs.diagnostics];
+    if (includePrivate)
+        return diagnostics;
+    const privatePrefix = `${context.root}/.pappra/local/knowledge`;
+    return diagnostics.filter((entry) => entry.source !== privatePrefix &&
+        !entry.source.startsWith(`${privatePrefix}/`));
+}
+export class KnowledgeService {
+    root;
+    #options;
+    constructor(root, options = {}) {
+        this.root = root;
+        this.#options = options;
+    }
+    async register(input) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        return registerDocument(loaded.context, input);
+    }
+    async read(documentId) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                content: null,
+                text: null,
+                digest: null,
+                freshness: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        const context = loaded.context;
+        const catalogs = await loadKnowledgeCatalogs(context);
+        const diagnostics = filteredDiagnostics(context, catalogs, true);
+        if (!catalogs.ok) {
+            return {
+                ok: false,
+                status: 'conflict',
+                record: null,
+                content: null,
+                text: null,
+                digest: null,
+                freshness: null,
+                diagnostics,
+            };
+        }
+        const record = findRecord(catalogs, documentId);
+        if (record === null) {
+            return {
+                ok: false,
+                status: 'not-found',
+                record: null,
+                content: null,
+                text: null,
+                digest: null,
+                freshness: null,
+                diagnostics,
+            };
+        }
+        const resolved = await resolveKnowledgeLocation(context, record.location);
+        if (!resolved.ok) {
+            diagnostics.push(outcomeDiagnostic(resolved, context.configPath));
+            return {
+                ok: false,
+                status: 'failed',
+                record,
+                content: null,
+                text: null,
+                digest: null,
+                freshness: null,
+                diagnostics,
+            };
+        }
+        const file = await readKnowledgeFile(resolved.value.absolutePath, MAX_DOCUMENT_BYTES);
+        if (!file.ok) {
+            diagnostics.push(outcomeDiagnostic(file, resolved.value.absolutePath));
+            return {
+                ok: false,
+                status: 'failed',
+                record,
+                content: null,
+                text: null,
+                digest: null,
+                freshness: null,
+                diagnostics,
+            };
+        }
+        let text = null;
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(file.value.bytes);
+        }
+        catch {
+            text = null;
+        }
+        const freshness = await inspectFreshness(context, catalogs, record, MAX_DOCUMENT_BYTES);
+        return {
+            ok: true,
+            status: 'ok',
+            record,
+            content: file.value.bytes,
+            text,
+            digest: file.value.digest,
+            freshness,
+            diagnostics,
+        };
+    }
+    async list(options = {}) {
+        const includePrivate = options.includePrivate === true;
+        const includeArchived = options.includeArchived === true;
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                records: [],
+                diagnostics: [...loaded.diagnostics],
+                catalogDigest: '',
+                includePrivate,
+                includeArchived,
+            };
+        }
+        const context = loaded.context;
+        const catalogs = await loadKnowledgeCatalogs(context);
+        const diagnostics = filteredDiagnostics(context, catalogs, includePrivate);
+        const records = [...catalogs.records.values()]
+            .filter((record) => (includePrivate || record.visibility === 'shareable') &&
+            (includeArchived || record.lifecycle === 'active'))
+            .sort((left, right) => left.documentId.localeCompare(right.documentId));
+        return {
+            ok: catalogs.ok,
+            records,
+            diagnostics,
+            catalogDigest: catalogs.catalogDigest,
+            includePrivate,
+            includeArchived,
+        };
+    }
+    async check(options = {}) {
+        const includePrivate = options.includePrivate === true;
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                checkedAt: new Date().toISOString(),
+                catalogDigest: '',
+                entries: [],
+                diagnostics: [...loaded.diagnostics],
+                summary: { total: 0, current: 0, needsReview: 0, unknown: 0 },
+                coverage: {
+                    catalogs: includePrivate ? 'shared-and-private' : 'shared',
+                    pathReferences: 'unchecked',
+                    repositoryContent: 'not-scanned',
+                    taskExecution: 'unknown',
+                },
+            };
+        }
+        const context = loaded.context;
+        const catalogs = await loadKnowledgeCatalogs(context);
+        const diagnostics = filteredDiagnostics(context, catalogs, includePrivate);
+        const selected = [...catalogs.records.values()].filter((record) => includePrivate || record.visibility === 'shareable');
+        diagnostics.push(...supersessionDiagnostics(selected));
+        const entries = [];
+        const canonicalPaths = new Map();
+        for (const record of selected) {
+            const resolved = await resolveKnowledgeLocation(context, record.location);
+            let fileDigest = null;
+            if (resolved.ok) {
+                const canonicalKey = process.platform === 'win32'
+                    ? resolved.value.canonicalPath.toLowerCase()
+                    : resolved.value.canonicalPath;
+                const existing = canonicalPaths.get(canonicalKey);
+                if (existing !== undefined && existing !== record.documentId) {
+                    diagnostics.push(createDiagnostic({
+                        code: diagnosticCodes.document_location_conflict,
+                        severity: 'error',
+                        message: `Canonical document path is registered by both ${existing} and ${record.documentId}.`,
+                        source: resolved.value.absolutePath,
+                        hint: 'Keep one documentId per real file; representation aliases are a location conflict.',
+                    }));
+                }
+                else {
+                    canonicalPaths.set(canonicalKey, record.documentId);
+                }
+                const file = await readKnowledgeFile(resolved.value.absolutePath, MAX_DOCUMENT_BYTES);
+                if (file.ok)
+                    fileDigest = file.value.digest;
+                else
+                    diagnostics.push(outcomeDiagnostic(file, resolved.value.absolutePath));
+            }
+            else {
+                diagnostics.push(outcomeDiagnostic(resolved, context.configPath));
+            }
+            const freshness = await inspectFreshness(context, catalogs, record, MAX_DOCUMENT_BYTES);
+            entries.push({
+                documentId: record.documentId,
+                scope: record.visibility === 'shareable' ? 'shared' : 'private',
+                lifecycle: record.lifecycle,
+                maturity: record.maturity,
+                fileDigest,
+                recordDigest: record.digest,
+                freshness: freshness.freshness,
+                reasons: freshness.reasons,
+                sourceChecks: freshness.sourceChecks,
+            });
+        }
+        const current = entries.filter((entry) => entry.freshness === 'current').length;
+        const needsReview = entries.filter((entry) => entry.freshness === 'needs-review').length;
+        const unknown = entries.filter((entry) => entry.freshness === 'unknown').length;
+        const ok = diagnostics.every((entry) => entry.severity !== 'error') &&
+            current === entries.length;
+        return {
+            ok,
+            checkedAt: new Date().toISOString(),
+            catalogDigest: catalogs.catalogDigest,
+            entries,
+            diagnostics,
+            summary: {
+                total: entries.length,
+                current,
+                needsReview,
+                unknown,
+            },
+            coverage: {
+                catalogs: includePrivate ? 'shared-and-private' : 'shared',
+                pathReferences: 'unchecked',
+                repositoryContent: 'not-scanned',
+                taskExecution: 'unknown',
+            },
+        };
+    }
+    async proposeWrite(input) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                proposal: null,
+                content: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        return proposeWrite(loaded.context, input);
+    }
+    async applyWrite(input) {
+        return applyWrite(input, this.root, this.#options);
+    }
+    async archive(documentId) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        return archiveDocument(loaded.context, documentId);
+    }
+    async supersede(input) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        return supersedeDocument(loaded.context, input);
+    }
+    async share(documentId) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: [...loaded.diagnostics],
+                residualPaths: [],
+            };
+        }
+        return shareDocument(loaded.context, documentId);
+    }
+    async previewDelete(input) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                plan: null,
+                diagnostics: [...loaded.diagnostics],
+            };
+        }
+        return previewDelete(loaded.context, input);
+    }
+    async deleteExplicit(input) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok) {
+            return {
+                ok: false,
+                status: 'failed',
+                documentId: null,
+                diagnostics: [...loaded.diagnostics],
+                residualPaths: [],
+                journalPath: null,
+            };
+        }
+        return deleteExplicit(loaded.context, input.plan);
+    }
+}

package/dist/knowledge/types.d.ts

@@ -0,0 +1,171 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { DocumentCatalog, DocumentKind, DocumentLocation, DocumentMaturity, DocumentOwner, DocumentRecord, DocumentSource, DocumentVisibility, DocumentWriteProposal, KnowledgeDeletePlan } from '../schemas/document.js';
+import type { FreshnessReason, FreshnessReport, SourceCheck } from './refs.js';
+export interface RegisterDocumentInput {
+    readonly location: DocumentLocation;
+    readonly kind: DocumentKind;
+    readonly maturity: DocumentMaturity;
+    readonly owner: DocumentOwner;
+    readonly taskId?: string | null;
+    readonly sources?: readonly DocumentSource[];
+    readonly lastReviewedAt?: string | null;
+    readonly visibility?: DocumentVisibility;
+    /** Advanced/migration use only; the service never derives IDs from paths. */
+    readonly documentId?: string;
+}
+export interface RegisterDocumentResult {
+    readonly ok: boolean;
+    readonly status: 'registered' | 'existing' | 'conflict' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ReadDocumentResult {
+    readonly ok: boolean;
+    readonly status: 'ok' | 'not-found' | 'conflict' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly content: Buffer | null;
+    readonly text: string | null;
+    readonly digest: string | null;
+    readonly freshness: FreshnessReport | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ListDocumentsOptions {
+    readonly includePrivate?: boolean;
+    readonly includeArchived?: boolean;
+}
+export interface ListDocumentsResult {
+    readonly ok: boolean;
+    readonly records: readonly DocumentRecord[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly catalogDigest: string;
+    readonly includePrivate: boolean;
+    readonly includeArchived: boolean;
+}
+export interface DocumentCheckEntry {
+    readonly documentId: string;
+    readonly scope: 'shared' | 'private';
+    readonly lifecycle: DocumentRecord['lifecycle'];
+    readonly maturity: DocumentRecord['maturity'];
+    readonly fileDigest: string | null;
+    readonly recordDigest: string;
+    readonly freshness: FreshnessReport['freshness'];
+    readonly reasons: readonly FreshnessReason[];
+    readonly sourceChecks: readonly SourceCheck[];
+}
+export interface DocumentCheckResult {
+    readonly ok: boolean;
+    readonly checkedAt: string;
+    readonly catalogDigest: string;
+    readonly entries: readonly DocumentCheckEntry[];
+    readonly diagnostics: readonly Diagnostic[];
+    readonly summary: {
+        readonly total: number;
+        readonly current: number;
+        readonly needsReview: number;
+        readonly unknown: number;
+    };
+    readonly coverage: {
+        readonly catalogs: 'shared' | 'shared-and-private';
+        readonly pathReferences: 'unchecked';
+        readonly repositoryContent: 'not-scanned';
+        readonly taskExecution: 'unknown';
+    };
+}
+export interface CreateDocumentWriteInput {
+    readonly mode: 'create';
+    readonly location: DocumentLocation;
+    readonly kind: DocumentKind;
+    readonly maturity: DocumentMaturity;
+    readonly owner: DocumentOwner;
+    readonly taskId?: string | null;
+    readonly sources?: readonly DocumentSource[];
+    readonly lastReviewedAt?: string | null;
+    readonly visibility?: DocumentVisibility;
+    readonly documentId?: string;
+    readonly content: Uint8Array | string;
+    readonly expectedDigest: null;
+}
+export interface UpdateDocumentWriteInput {
+    readonly mode: 'update';
+    readonly documentId: string;
+    readonly content: Uint8Array | string;
+    readonly expectedDigest: string;
+}
+export type ProposeWriteInput = CreateDocumentWriteInput | UpdateDocumentWriteInput;
+export interface ProposeWriteResult {
+    readonly ok: boolean;
+    readonly status: 'proposed' | 'conflict' | 'stale' | 'failed';
+    readonly proposal: DocumentWriteProposal | null;
+    readonly content: Buffer | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface KnowledgeServiceOptions {
+    /** Test/fault-injection seam; the CLI never supplies these hooks. */
+    readonly beforeFileSync?: (path: string) => Promise<void> | void;
+    readonly failFileSync?: boolean;
+}
+export interface ApplyWriteInput {
+    readonly proposal: DocumentWriteProposal;
+    readonly content: Uint8Array | string;
+}
+export interface ApplyWriteResult {
+    readonly ok: boolean;
+    readonly status: 'applied' | 'conflict' | 'stale' | 'locked' | 'partial' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly residualPaths: readonly string[];
+    readonly journalPath: string | null;
+}
+export interface ArchiveDocumentResult {
+    readonly ok: boolean;
+    readonly status: 'archived' | 'unchanged' | 'not-found' | 'conflict' | 'locked' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface SupersedeDocumentInput {
+    readonly documentId: string;
+    readonly supersededBy: string;
+}
+export interface SupersedeDocumentResult {
+    readonly ok: boolean;
+    readonly status: 'superseded' | 'unchanged' | 'not-found' | 'conflict' | 'locked' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ShareDocumentResult {
+    readonly ok: boolean;
+    readonly status: 'shared' | 'unchanged' | 'not-found' | 'conflict' | 'locked' | 'partial' | 'failed';
+    readonly record: DocumentRecord | null;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly residualPaths: readonly string[];
+}
+export interface PreviewDeleteInput {
+    readonly documentId: string;
+    readonly removeFile: boolean;
+}
+export interface PreviewDeleteResult {
+    readonly ok: boolean;
+    readonly status: 'ready' | 'blocked' | 'not-found' | 'stale' | 'failed';
+    readonly plan: KnowledgeDeletePlan | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface DeleteExplicitInput {
+    readonly plan: KnowledgeDeletePlan;
+}
+export interface DeleteExplicitResult {
+    readonly ok: boolean;
+    readonly status: 'deleted' | 'unregistered' | 'blocked' | 'stale' | 'locked' | 'partial' | 'failed';
+    readonly documentId: string | null;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly residualPaths: readonly string[];
+    readonly journalPath: string | null;
+}
+export interface CatalogInspection {
+    readonly scope: 'shared' | 'private';
+    readonly path: string;
+    readonly exists: boolean;
+    readonly valid: boolean;
+    readonly recordCount: number;
+    readonly catalog: DocumentCatalog | null;
+}
+export type { FreshnessReport };

package/dist/knowledge/types.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/write.d.ts

@@ -0,0 +1,8 @@
+import { type DocumentWriteProposal } from '../schemas/document.js';
+import type { KnowledgeContext } from './context.js';
+import type { ApplyWriteInput, ApplyWriteResult, KnowledgeServiceOptions, ProposeWriteInput, ProposeWriteResult, RegisterDocumentInput, RegisterDocumentResult } from './types.js';
+export declare function defaultVisibility(context: KnowledgeContext): 'private' | 'shareable';
+export declare function registerDocument(context: KnowledgeContext, input: RegisterDocumentInput): Promise<RegisterDocumentResult>;
+export declare function proposeWrite(context: KnowledgeContext, input: ProposeWriteInput): Promise<ProposeWriteResult>;
+export declare function applyWrite(input: ApplyWriteInput, root: string, options?: KnowledgeServiceOptions): Promise<ApplyWriteResult>;
+export declare function applyWriteAt(inputContext: KnowledgeContext, proposal: DocumentWriteProposal, content: Buffer, options?: KnowledgeServiceOptions): Promise<ApplyWriteResult>;