@kentwynn/kgraph 0.2.9 → 0.2.11

package/dist/knowledge/atom-store.js

@@ -0,0 +1,484 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { KGraphError } from '../cli/errors.js';
+import { getCurrentCommit } from '../scanner/git-utils.js';
+import { readCognitionNotes } from '../storage/cognition-store.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+export const KNOWLEDGE_SCHEMA_VERSION = 1;
+export async function ensureKnowledgeStore(workspace) {
+    await mkdir(indexesPath(workspace), { recursive: true });
+    if (!(await pathExists(schemaPath(workspace)))) {
+        const now = new Date().toISOString();
+        await writeSchema(workspace, {
+            version: KNOWLEDGE_SCHEMA_VERSION,
+            createdAt: now,
+            updatedAt: now,
+            migrations: [{ id: 'init-knowledge-v1', appliedAt: now }],
+        });
+    }
+    if (!(await pathExists(atomsPath(workspace)))) {
+        await writeFile(atomsPath(workspace), '', 'utf8');
+    }
+}
+export async function readKnowledgeAtoms(workspace) {
+    await migrateLegacyCognitionToAtoms(workspace);
+    return readAtomsFile(workspace);
+}
+export async function readAtomsFile(workspace) {
+    await ensureKnowledgeStore(workspace);
+    const raw = await readFile(atomsPath(workspace), 'utf8');
+    return parseAtomsJsonl(raw);
+}
+export function parseAtomsJsonl(raw) {
+    const atoms = [];
+    for (const [index, line] of raw.split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            atoms.push(JSON.parse(line));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new KGraphError(`Invalid atoms.jsonl line ${index + 1}: ${message}`);
+        }
+    }
+    return atoms;
+}
+export async function writeKnowledgeAtoms(workspace, atoms) {
+    await ensureKnowledgeStore(workspace);
+    await writeFile(atomsPath(workspace), atoms.map((atom) => JSON.stringify(atom)).join('\n') +
+        (atoms.length > 0 ? '\n' : ''), 'utf8');
+    await writeKnowledgeIndexes(workspace, atoms);
+    await touchSchema(workspace);
+}
+export async function appendKnowledgeAtom(workspace, atom) {
+    const atoms = await readAtomsFile(workspace);
+    atoms.push(atom);
+    await writeKnowledgeAtoms(workspace, atoms);
+    return atom;
+}
+export async function createKnowledgeAtom(workspace, input, maps) {
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const commit = input.commit ?? (await getCurrentCommit(workspace.rootPath)) ?? undefined;
+    const evidenceRefs = buildEvidenceRefs(input, maps);
+    const status = evaluateAtomStatus(evidenceRefs, maps);
+    const atom = {
+        id: buildAtomId(createdAt, input.idSeed ?? input.topic),
+        type: input.type,
+        topic: input.topic,
+        claim: input.claim,
+        summary: input.summary,
+        confidence: computeConfidence(input.confidence ?? 'medium', status),
+        status,
+        evidenceRefs,
+        scopeRefs: {
+            files: input.files ?? [],
+            symbols: input.symbols ?? [],
+            domains: input.domains ?? [],
+            packages: input.packages ?? [],
+        },
+        provenance: {
+            sourceCommand: input.sourceCommand,
+            agent: input.agent,
+            sessionId: input.sessionId,
+            commit,
+            createdAt,
+        },
+        lifecycle: {
+            supersedes: [],
+        },
+    };
+    return appendKnowledgeAtom(workspace, atom);
+}
+export async function migrateLegacyCognitionToAtoms(workspace) {
+    await ensureKnowledgeStore(workspace);
+    const [existing, notes] = await Promise.all([
+        readAtomsFile(workspace),
+        readCognitionNotes(workspace),
+    ]);
+    const existingIds = new Set(existing.map((atom) => atom.id));
+    const migrated = [];
+    for (const note of notes) {
+        const id = legacyAtomId(note);
+        if (existingIds.has(id))
+            continue;
+        if (existing.some((atom) => atom.topic === note.title &&
+            atom.claim === (note.summary ?? note.title) &&
+            atom.provenance.createdAt === note.createdAt)) {
+            continue;
+        }
+        migrated.push(legacyNoteToAtom(note, id));
+    }
+    if (migrated.length > 0) {
+        await writeKnowledgeAtoms(workspace, [...existing, ...migrated]);
+    }
+    else {
+        await writeKnowledgeIndexes(workspace, existing);
+    }
+}
+export async function updateKnowledgeAtom(workspace, atomId, updater) {
+    const atoms = await readKnowledgeAtoms(workspace);
+    const index = atoms.findIndex((atom) => atom.id === atomId);
+    if (index === -1) {
+        throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+    }
+    atoms[index] = updater(atoms[index]);
+    await writeKnowledgeAtoms(workspace, atoms);
+    return atoms[index];
+}
+export async function refreshKnowledgeAtomStatuses(workspace, maps, dryRun = false) {
+    const atoms = await readKnowledgeAtoms(workspace);
+    const now = new Date().toISOString();
+    const updated = [];
+    const nextAtoms = atoms.map((atom) => {
+        if (atom.status === 'archived')
+            return atom;
+        const health = evaluateAtomHealth(atom.evidenceRefs, maps);
+        const nextConfidence = computeConfidence(atom.confidence, health.status, atom);
+        const nextLifecycle = {
+            ...atom.lifecycle,
+            ...(health.reasons.length > 0 ? { invalidatedBy: health.reasons } : {}),
+        };
+        if (health.status === 'active') {
+            delete nextLifecycle.invalidatedBy;
+        }
+        const statusChanged = health.status !== atom.status;
+        const confidenceChanged = nextConfidence !== atom.confidence;
+        const invalidationChanged = JSON.stringify(nextLifecycle.invalidatedBy ?? []) !==
+            JSON.stringify(atom.lifecycle.invalidatedBy ?? []);
+        const nextAtom = {
+            ...atom,
+            status: health.status,
+            confidence: nextConfidence,
+            lifecycle: nextLifecycle,
+            provenance: {
+                ...atom.provenance,
+                ...(statusChanged || confidenceChanged || invalidationChanged
+                    ? { updatedAt: now }
+                    : {}),
+            },
+        };
+        if (statusChanged || confidenceChanged || invalidationChanged) {
+            updated.push({
+                atomId: atom.id,
+                previousStatus: atom.status,
+                nextStatus: health.status,
+                reasons: health.reasons,
+            });
+        }
+        return nextAtom;
+    });
+    if (!dryRun && updated.length > 0) {
+        await writeKnowledgeAtoms(workspace, nextAtoms);
+    }
+    return { atoms: nextAtoms, updated };
+}
+export async function validateKnowledgeStore(workspace, maps) {
+    const issues = [];
+    if (!(await pathExists(schemaPath(workspace)))) {
+        issues.push({ code: 'missing-schema', message: 'missing knowledge/schema.json' });
+    }
+    else {
+        try {
+            const schema = JSON.parse(await readFile(schemaPath(workspace), 'utf8'));
+            if (schema.version < KNOWLEDGE_SCHEMA_VERSION) {
+                issues.push({
+                    code: 'old-schema',
+                    message: `knowledge schema ${schema.version} is older than ${KNOWLEDGE_SCHEMA_VERSION}`,
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push({ code: 'missing-schema', message: `invalid knowledge schema: ${message}` });
+        }
+    }
+    let atoms = [];
+    try {
+        atoms = await readKnowledgeAtoms(workspace);
+    }
+    catch (error) {
+        issues.push({
+            code: 'invalid-jsonl',
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return issues;
+    }
+    if (maps) {
+        const fileByPath = new Map(maps.fileMap.files.map((file) => [file.path, file]));
+        const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
+        const symbolIds = new Set(maps.symbolMap.symbols.map((symbol) => symbol.id));
+        for (const atom of atoms) {
+            for (const ref of atom.evidenceRefs) {
+                if (ref.type === 'file') {
+                    const file = fileByPath.get(ref.path);
+                    if (!file) {
+                        issues.push({
+                            code: 'broken-file-ref',
+                            atomId: atom.id,
+                            message: `${atom.id} references missing file ${ref.path}`,
+                        });
+                    }
+                    else if (ref.contentHash && ref.contentHash !== file.contentHash) {
+                        issues.push({
+                            code: 'stale-file-hash',
+                            atomId: atom.id,
+                            message: `${atom.id} references changed file ${ref.path}`,
+                        });
+                    }
+                }
+                if (ref.type === 'symbol') {
+                    const exists = (ref.symbolId && symbolIds.has(ref.symbolId)) ||
+                        symbolNames.has(ref.name);
+                    if (!exists) {
+                        issues.push({
+                            code: 'broken-symbol-ref',
+                            atomId: atom.id,
+                            message: `${atom.id} references missing symbol ${ref.name}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+export function atomToCognitionNote(atom) {
+    return {
+        id: atom.id,
+        title: atom.topic,
+        kind: atom.type,
+        confidence: atom.confidence,
+        domain: atom.scopeRefs.domains[0],
+        tags: [],
+        summary: atom.summary ?? atom.claim,
+        sections: { Summary: atom.summary ?? atom.claim },
+        relatedFiles: atom.scopeRefs.files,
+        relatedSymbols: atom.scopeRefs.symbols,
+        warnings: [],
+        sourceInboxPath: '',
+        processedPath: '',
+        createdAt: atom.provenance.createdAt,
+        updatedAt: atom.provenance.updatedAt,
+        source: atom.provenance.sourceCommand === 'legacy-migration' ||
+            atom.provenance.sourceCommand === 'update'
+            ? 'inbox'
+            : atom.provenance.sourceCommand,
+        supersedes: atom.lifecycle.supersedes,
+        supersededBy: atom.lifecycle.supersededBy,
+        referencesStatus: atom.status === 'active'
+            ? 'current'
+            : atom.status === 'needs-review'
+                ? 'mixed'
+                : atom.status === 'stale'
+                    ? 'stale'
+                    : 'unresolved',
+    };
+}
+export function knowledgePaths(workspace) {
+    return {
+        atoms: atomsPath(workspace),
+        schema: schemaPath(workspace),
+        indexes: indexesPath(workspace),
+        terms: path.join(indexesPath(workspace), 'terms.json'),
+        refs: path.join(indexesPath(workspace), 'refs.json'),
+        topics: path.join(indexesPath(workspace), 'topics.json'),
+    };
+}
+function buildEvidenceRefs(input, maps) {
+    const fileByPath = new Map(maps?.fileMap.files.map((file) => [file.path, file]) ?? []);
+    const symbolsByName = new Map(maps?.symbolMap.symbols.map((symbol) => [symbol.name, symbol]) ?? []);
+    const refs = [];
+    for (const filePath of input.files ?? []) {
+        const file = fileByPath.get(filePath);
+        refs.push({
+            type: 'file',
+            path: filePath,
+            ...(file?.contentHash ? { contentHash: file.contentHash } : {}),
+        });
+    }
+    for (const name of input.symbols ?? []) {
+        const symbol = symbolsByName.get(name);
+        refs.push({
+            type: 'symbol',
+            name,
+            ...(symbol?.filePath ? { filePath: symbol.filePath } : {}),
+            ...(symbol?.id ? { symbolId: symbol.id } : {}),
+            ...(symbol?.startLine ? { startLine: symbol.startLine } : {}),
+            ...(symbol?.endLine ? { endLine: symbol.endLine } : {}),
+        });
+    }
+    if (input.commit) {
+        refs.push({ type: 'git', commit: input.commit });
+    }
+    if (input.sessionId || input.agent) {
+        refs.push({ type: 'session', sessionId: input.sessionId, agent: input.agent });
+    }
+    return refs;
+}
+function evaluateAtomStatus(refs, maps) {
+    return evaluateAtomHealth(refs, maps).status;
+}
+function evaluateAtomHealth(refs, maps) {
+    if (!maps || refs.length === 0)
+        return { status: 'active', reasons: [] };
+    const fileByPath = new Map(maps.fileMap.files.map((file) => [file.path, file]));
+    const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
+    const symbolIds = new Set(maps.symbolMap.symbols.map((symbol) => symbol.id));
+    let stale = false;
+    let needsReview = false;
+    const reasons = [];
+    for (const ref of refs) {
+        if (ref.type === 'file') {
+            const file = fileByPath.get(ref.path);
+            if (!file) {
+                stale = true;
+                reasons.push(`missing file:${ref.path}`);
+            }
+            else if (ref.contentHash && ref.contentHash !== file.contentHash) {
+                needsReview = true;
+                reasons.push(`changed file:${ref.path}`);
+            }
+        }
+        if (ref.type === 'symbol') {
+            const exists = (ref.symbolId && symbolIds.has(ref.symbolId)) || symbolNames.has(ref.name);
+            if (!exists) {
+                stale = true;
+                reasons.push(`missing symbol:${ref.name}`);
+            }
+        }
+    }
+    if (stale)
+        return { status: 'stale', reasons };
+    if (needsReview)
+        return { status: 'needs-review', reasons };
+    return { status: 'active', reasons };
+}
+function computeConfidence(initial, status, atom) {
+    if (atom?.lifecycle.supersededBy || atom?.status === 'archived')
+        return 'low';
+    if (status === 'stale')
+        return 'low';
+    if (status === 'needs-review' && initial === 'high')
+        return 'medium';
+    if (atom?.provenance.sourceCommand === 'legacy-migration' && initial === 'high') {
+        return 'medium';
+    }
+    return initial;
+}
+function legacyNoteToAtom(note, id) {
+    return {
+        id,
+        type: note.kind,
+        topic: note.title,
+        claim: note.summary ?? note.title,
+        summary: note.summary,
+        confidence: note.confidence,
+        status: note.referencesStatus === 'current'
+            ? 'active'
+            : note.referencesStatus === 'mixed'
+                ? 'needs-review'
+                : note.referencesStatus === 'stale'
+                    ? 'stale'
+                    : 'needs-review',
+        evidenceRefs: [
+            ...note.relatedFiles.map((file) => ({ type: 'file', path: file })),
+            ...note.relatedSymbols.map((symbol) => ({
+                type: 'symbol',
+                name: symbol,
+            })),
+        ],
+        scopeRefs: {
+            files: note.relatedFiles,
+            symbols: note.relatedSymbols,
+            domains: note.domain ? [note.domain] : [],
+            packages: [],
+        },
+        provenance: {
+            sourceCommand: 'legacy-migration',
+            createdAt: note.createdAt,
+            updatedAt: note.updatedAt,
+        },
+        lifecycle: {
+            supersedes: note.supersedes ?? [],
+            supersededBy: note.supersededBy,
+        },
+    };
+}
+function legacyAtomId(note) {
+    return `legacy-${note.id}`;
+}
+async function writeKnowledgeIndexes(workspace, atoms) {
+    await mkdir(indexesPath(workspace), { recursive: true });
+    const indexes = buildIndexes(atoms);
+    await Promise.all([
+        writeFile(path.join(indexesPath(workspace), 'terms.json'), JSON.stringify(indexes.terms, null, 2) + '\n', 'utf8'),
+        writeFile(path.join(indexesPath(workspace), 'refs.json'), JSON.stringify(indexes.refs, null, 2) + '\n', 'utf8'),
+        writeFile(path.join(indexesPath(workspace), 'topics.json'), JSON.stringify(indexes.topics, null, 2) + '\n', 'utf8'),
+    ]);
+}
+function buildIndexes(atoms) {
+    const terms = {};
+    const refs = {};
+    const topics = {};
+    for (const atom of atoms) {
+        for (const term of tokenize([atom.topic, atom.claim, atom.summary ?? ''].join(' '))) {
+            addIndex(terms, term, atom.id);
+        }
+        addIndex(topics, atom.topic.toLowerCase(), atom.id);
+        for (const file of atom.scopeRefs.files)
+            addIndex(refs, `file:${file}`, atom.id);
+        for (const symbol of atom.scopeRefs.symbols)
+            addIndex(refs, `symbol:${symbol}`, atom.id);
+    }
+    return { terms, refs, topics };
+}
+function addIndex(index, key, atomId) {
+    const values = index[key] ?? [];
+    if (!values.includes(atomId))
+        values.push(atomId);
+    index[key] = values;
+}
+async function touchSchema(workspace) {
+    const schema = await readSchema(workspace);
+    await writeSchema(workspace, {
+        ...schema,
+        updatedAt: new Date().toISOString(),
+    });
+}
+async function readSchema(workspace) {
+    await ensureKnowledgeStore(workspace);
+    return JSON.parse(await readFile(schemaPath(workspace), 'utf8'));
+}
+async function writeSchema(workspace, schema) {
+    await mkdir(workspace.knowledgePath, { recursive: true });
+    await writeFile(schemaPath(workspace), JSON.stringify(schema, null, 2) + '\n', 'utf8');
+}
+function buildAtomId(createdAt, seed) {
+    return `${createdAt.replace(/[:.]/g, '-')}-${slugify(seed) || 'atom'}`;
+}
+function tokenize(value) {
+    return [
+        ...new Set(value
+            .toLowerCase()
+            .split(/[^a-z0-9_$./-]+/)
+            .map((token) => token.trim())
+            .filter((token) => token.length > 1)),
+    ];
+}
+function slugify(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function atomsPath(workspace) {
+    return path.join(workspace.knowledgePath, 'atoms.jsonl');
+}
+function schemaPath(workspace) {
+    return path.join(workspace.knowledgePath, 'schema.json');
+}
+function indexesPath(workspace) {
+    return path.join(workspace.knowledgePath, 'indexes');
+}

package/dist/storage/kgraph-paths.js

@@ -8,7 +8,9 @@ const WORKSPACE_DIRS = [
     "inbox",
     "interactions/processed",
     "context",
-    "sessions"
+    "sessions",
+    "knowledge",
+    "knowledge/indexes"
 ];
 export function resolveWorkspace(rootPath = process.cwd()) {
     const kgraphPath = path.join(rootPath, ".kgraph");
@@ -22,7 +24,8 @@ export function resolveWorkspace(rootPath = process.cwd()) {
         inboxPath: path.join(kgraphPath, "inbox"),
         processedInteractionsPath: path.join(kgraphPath, "interactions", "processed"),
         contextPath: path.join(kgraphPath, "context"),
-        sessionsPath: path.join(kgraphPath, "sessions")
+        sessionsPath: path.join(kgraphPath, "sessions"),
+        knowledgePath: path.join(kgraphPath, "knowledge")
     };
 }
 export async function pathExists(targetPath) {

package/dist/types/config.d.ts

@@ -31,4 +31,5 @@ export interface KGraphWorkspace {
     processedInteractionsPath: string;
     contextPath: string;
     sessionsPath: string;
+    knowledgePath: string;
 }

package/dist/types/knowledge.d.ts

@@ -0,0 +1,92 @@
+import type { CognitionConfidence, CognitionKind } from './cognition.js';
+export type KnowledgeAtomStatus = 'active' | 'stale' | 'needs-review' | 'archived';
+export type KnowledgeEvidenceRef = {
+    type: 'file';
+    path: string;
+    startLine?: number;
+    endLine?: number;
+    contentHash?: string;
+} | {
+    type: 'symbol';
+    name: string;
+    filePath?: string;
+    symbolId?: string;
+    startLine?: number;
+    endLine?: number;
+} | {
+    type: 'git';
+    commit?: string;
+    path?: string;
+} | {
+    type: 'session';
+    sessionId?: string;
+    agent?: string;
+};
+export interface KnowledgeScopeRefs {
+    files: string[];
+    symbols: string[];
+    domains: string[];
+    packages: string[];
+}
+export interface KnowledgeProvenance {
+    sourceCommand: 'update' | 'conclude' | 'session-conclude' | 'legacy-migration' | 'compact';
+    agent?: string;
+    sessionId?: string;
+    commit?: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+export interface KnowledgeLifecycle {
+    supersedes: string[];
+    supersededBy?: string;
+    invalidatedBy?: string[];
+    archivedAt?: string;
+}
+export interface KnowledgeAtom {
+    id: string;
+    type: CognitionKind;
+    topic: string;
+    claim: string;
+    summary?: string;
+    confidence: CognitionConfidence;
+    status: KnowledgeAtomStatus;
+    evidenceRefs: KnowledgeEvidenceRef[];
+    scopeRefs: KnowledgeScopeRefs;
+    provenance: KnowledgeProvenance;
+    lifecycle: KnowledgeLifecycle;
+}
+export interface KnowledgeSchema {
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    migrations: Array<{
+        id: string;
+        appliedAt: string;
+    }>;
+}
+export interface KnowledgeIndexes {
+    terms: Record<string, string[]>;
+    refs: Record<string, string[]>;
+    topics: Record<string, string[]>;
+}
+export interface KnowledgeValidationIssue {
+    code: 'missing-schema' | 'old-schema' | 'invalid-jsonl' | 'broken-file-ref' | 'broken-symbol-ref' | 'stale-file-hash';
+    message: string;
+    atomId?: string;
+}
+export interface ContextPackItem {
+    kind: 'file' | 'symbol' | 'atom' | 'relationship' | 'git-change';
+    id: string;
+    title: string;
+    tokenEstimate: number;
+    reasons: string[];
+    data: unknown;
+}
+export interface ContextPack {
+    task: string;
+    budget: number;
+    usedTokens: number;
+    items: ContextPackItem[];
+    omitted: ContextPackItem[];
+    warnings: string[];
+}

package/dist/types/knowledge.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {