@roackb2/heddle 1.5.0 → 1.7.0

package/dist/src/core/memory/note-service.js

@@ -0,0 +1,165 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { executeScopedEdit } from '../../core/tools/toolkits/coding-files/file-edit-core.js';
+import { MemoryPathUtils } from './path-utils.js';
+const DEFAULT_MAX_SEARCH_RESULTS = 100;
+/**
+ * Owns note-level memory reads, search, listing, and scoped note edits.
+ */
+export class MemoryNoteService {
+    memoryRoot;
+    constructor(memoryRoot) {
+        this.memoryRoot = memoryRoot;
+    }
+    async list(input = {}) {
+        const targetPath = this.resolvePath(input.path ?? '.');
+        if (!await MemoryPathUtils.pathExists(targetPath)) {
+            return [];
+        }
+        const info = await stat(targetPath);
+        if (info.isFile()) {
+            return [MemoryPathUtils.toMemoryRelativePath(this.resolveRoot(), targetPath)];
+        }
+        const notes = await this.listMarkdownNotes(targetPath);
+        return notes.map((path) => MemoryPathUtils.toMemoryRelativePath(this.resolveRoot(), path)).sort();
+    }
+    async read(input) {
+        const targetPath = this.resolvePath(input.path);
+        try {
+            return MemoryNoteService.pageText(await readFile(targetPath, 'utf8'), input.offset, input.maxLines);
+        }
+        catch (error) {
+            if (MemoryPathUtils.isErrorWithCode(error, 'EISDIR')) {
+                throw new Error(`Failed to read ${targetPath}: path is a directory, not a file. Use list_memory_notes to inspect memory directories.`, { cause: error });
+            }
+            throw new Error(`Failed to read ${targetPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    async search(input) {
+        const targetPath = this.resolvePath(input.path ?? '.');
+        if (!await MemoryPathUtils.pathExists(targetPath)) {
+            return 'No matches found.';
+        }
+        return await this.searchWithCli(targetPath, input.query, MemoryNoteService.sanitizeMaxResults(input.maxResults));
+    }
+    async edit(raw) {
+        return await executeScopedEdit(raw, {
+            toolName: 'edit_memory_note',
+            rootPath: this.resolveRoot(),
+            rootLabel: 'memory root',
+            subjectLabel: 'memory note',
+            creationHint: 'Set createIfMissing to true if you want edit_memory_note to create it.',
+            enforceRoot: true,
+        });
+    }
+    resolvePath(path) {
+        const result = MemoryPathUtils.resolveMemoryPath(this.resolveRoot(), path);
+        if (!result.ok) {
+            throw new Error(result.error);
+        }
+        return result.path;
+    }
+    async listMarkdownNotes(root) {
+        const results = [];
+        const entries = await readdir(root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === '_maintenance') {
+                continue;
+            }
+            const nextPath = resolve(root, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...await this.listMarkdownNotes(nextPath));
+                continue;
+            }
+            if (entry.isFile() && MemoryNoteService.isMarkdownPath(nextPath)) {
+                results.push(nextPath);
+            }
+        }
+        return results.sort();
+    }
+    async searchWithCli(targetPath, query, maxResults) {
+        const memoryRoot = this.resolveRoot();
+        const relativeTarget = MemoryPathUtils.toMemoryRelativePath(memoryRoot, targetPath);
+        const normalizedTarget = relativeTarget === '.' ? '.' : relativeTarget;
+        const rgResult = await MemoryNoteService.runSearchCommand('rg', ['-n', '--no-heading', '--glob', '*.md', query, normalizedTarget], memoryRoot);
+        if (rgResult.kind === 'ok') {
+            return MemoryNoteService.trimSearchOutput(rgResult.stdout, maxResults);
+        }
+        if (rgResult.kind === 'nonzero_no_match') {
+            return 'No matches found.';
+        }
+        if (rgResult.kind !== 'missing_binary') {
+            throw new Error(`Failed to search memory notes in ${targetPath}: ${rgResult.error}`);
+        }
+        const grepResult = await MemoryNoteService.runSearchCommand('grep', ['-R', '-n', '--include=*.md', query, normalizedTarget], memoryRoot);
+        if (grepResult.kind === 'ok') {
+            return MemoryNoteService.trimSearchOutput(grepResult.stdout, maxResults);
+        }
+        if (grepResult.kind === 'nonzero_no_match') {
+            return 'No matches found.';
+        }
+        throw new Error(`Failed to search memory notes in ${targetPath}: ${grepResult.error}`);
+    }
+    resolveRoot() {
+        return resolve(this.memoryRoot);
+    }
+    static pageText(content, offset, maxLines) {
+        const lines = content.split('\n');
+        const start = offset && offset > 0 ? Math.floor(offset) : 0;
+        const end = maxLines && maxLines > 0 ? start + Math.floor(maxLines) : undefined;
+        return start > 0 || end !== undefined ? lines.slice(start, end).join('\n') : content;
+    }
+    static sanitizeMaxResults(value) {
+        if (!value || !Number.isFinite(value) || value <= 0) {
+            return DEFAULT_MAX_SEARCH_RESULTS;
+        }
+        return Math.min(Math.floor(value), DEFAULT_MAX_SEARCH_RESULTS);
+    }
+    static isMarkdownPath(path) {
+        return /\.md$/i.test(path);
+    }
+    static trimSearchOutput(stdout, maxResults) {
+        const lines = stdout
+            .split('\n')
+            .map((line) => line.trimEnd().replace(/^\.\//, ''))
+            .filter((line) => line.length > 0)
+            .slice(0, maxResults);
+        return lines.length > 0 ? lines.join('\n') : 'No matches found.';
+    }
+    static async runSearchCommand(binary, args, cwd) {
+        return await new Promise((resolvePromise) => {
+            const child = spawn(binary, args, {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk.toString();
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk.toString();
+            });
+            child.on('error', (error) => {
+                if ('code' in error && error.code === 'ENOENT') {
+                    resolvePromise({ kind: 'missing_binary', error: `${binary} is not available in the environment.` });
+                    return;
+                }
+                resolvePromise({ kind: 'error', error: error.message });
+            });
+            child.on('close', (code) => {
+                if (code === 0) {
+                    resolvePromise({ kind: 'ok', stdout });
+                    return;
+                }
+                if (code === 1) {
+                    resolvePromise({ kind: 'nonzero_no_match', error: stderr.trim() || `${binary} returned exit code 1` });
+                    return;
+                }
+                resolvePromise({ kind: 'error', error: stderr.trim() || `${binary} returned exit code ${code ?? 'unknown'}` });
+            });
+        });
+    }
+}
+//# sourceMappingURL=note-service.js.map

package/dist/src/core/memory/note-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-service.js","sourceRoot":"","sources":["../../../../src/core/memory/note-service.ts"],"names":[],"mappings":"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"}

package/dist/src/core/memory/path-utils.d.ts

@@ -0,0 +1,15 @@
+export declare class MemoryPathUtils {
+    static resolveMemoryPath(memoryRoot: string, requestedPath: string): {
+        ok: true;
+        path: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    static toMemoryRelativePath(memoryRoot: string, filePath: string): string;
+    static pathExists(path: string): Promise<boolean>;
+    static isErrorWithCode(error: unknown, code: string): error is Error & {
+        code: string;
+    };
+}
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/src/core/memory/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/path-utils.ts"],"names":[],"mappings":"AAGA,qBAAa,eAAe;IAC1B,MAAM,CAAC,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAc9H,MAAM,CAAC,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;WAI5D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASvD,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE;CAGxF"}

package/dist/src/core/memory/path-utils.js

@@ -0,0 +1,31 @@
+import { access } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+export class MemoryPathUtils {
+    static resolveMemoryPath(memoryRoot, requestedPath) {
+        if (!requestedPath.trim()) {
+            return { ok: false, error: `Memory note paths must be non-empty and stay inside ${memoryRoot}.` };
+        }
+        const targetPath = resolve(memoryRoot, requestedPath);
+        const rel = relative(memoryRoot, targetPath);
+        if (rel.startsWith('..') || isAbsolute(rel)) {
+            return { ok: false, error: `Memory note paths must stay inside ${memoryRoot}. Refusing to access ${targetPath}.` };
+        }
+        return { ok: true, path: targetPath };
+    }
+    static toMemoryRelativePath(memoryRoot, filePath) {
+        return relative(memoryRoot, filePath) || '.';
+    }
+    static async pathExists(path) {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    static isErrorWithCode(error, code) {
+        return error instanceof Error && 'code' in error && error.code === code;
+    }
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/src/core/memory/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../../src/core/memory/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,OAAO,eAAe;IAC1B,MAAM,CAAC,iBAAiB,CAAC,UAAkB,EAAE,aAAqB;QAChE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uDAAuD,UAAU,GAAG,EAAE,CAAC;QACpG,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC7C,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sCAAsC,UAAU,wBAAwB,UAAU,GAAG,EAAE,CAAC;QACrH,CAAC;QAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,CAAC,oBAAoB,CAAC,UAAkB,EAAE,QAAgB;QAC9D,OAAO,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,MAAM,CAAC,eAAe,CAAC,KAAc,EAAE,IAAY;QACjD,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;IAC1E,CAAC;CACF"}

package/dist/src/core/memory/schemas.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare class MemorySchemas {
+    static readonly candidate: z.ZodObject<{
+        id: z.ZodString;
+        recordedAt: z.ZodString;
+        status: z.ZodLiteral<"pending">;
+        summary: z.ZodString;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        categoryHint: z.ZodOptional<z.ZodString>;
+        importance: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+        confidence: z.ZodOptional<z.ZodEnum<{
+            "user-stated": "user-stated";
+            "tool-verified": "tool-verified";
+            inferred: "inferred";
+            historical: "historical";
+        }>>;
+        sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    static readonly candidateStatus: z.ZodObject<{
+        kind: z.ZodLiteral<"candidate_status">;
+        candidateId: z.ZodString;
+        status: z.ZodLiteral<"processed">;
+        runId: z.ZodString;
+        recordedAt: z.ZodString;
+    }, z.core.$strip>;
+    static readonly candidateLogEntry: z.ZodUnion<readonly [z.ZodObject<{
+        id: z.ZodString;
+        recordedAt: z.ZodString;
+        status: z.ZodLiteral<"pending">;
+        summary: z.ZodString;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        categoryHint: z.ZodOptional<z.ZodString>;
+        importance: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+        confidence: z.ZodOptional<z.ZodEnum<{
+            "user-stated": "user-stated";
+            "tool-verified": "tool-verified";
+            inferred: "inferred";
+            historical: "historical";
+        }>>;
+        sourceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"candidate_status">;
+        candidateId: z.ZodString;
+        status: z.ZodLiteral<"processed">;
+        runId: z.ZodString;
+        recordedAt: z.ZodString;
+    }, z.core.$strip>]>;
+    static readonly maintenanceRun: z.ZodObject<{
+        id: z.ZodString;
+        startedAt: z.ZodString;
+        finishedAt: z.ZodString;
+        source: z.ZodString;
+        outcome: z.ZodEnum<{
+            error: "error";
+            done: "done";
+            max_steps: "max_steps";
+            interrupted: "interrupted";
+            skipped: "skipped";
+        }>;
+        summary: z.ZodString;
+        candidateIds: z.ZodArray<z.ZodString>;
+        processedCandidateIds: z.ZodArray<z.ZodString>;
+        failedCandidateIds: z.ZodArray<z.ZodString>;
+        catalogValid: z.ZodBoolean;
+        catalogMissing: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    static readonly maintenanceLock: z.ZodObject<{
+        id: z.ZodString;
+        pid: z.ZodOptional<z.ZodNumber>;
+        acquiredAt: z.ZodString;
+    }, z.core.$strip>;
+    static parseCandidateLogEntry(value: unknown): z.ZodSafeParseResult<{
+        id: string;
+        recordedAt: string;
+        status: "pending";
+        summary: string;
+        evidence?: string[] | undefined;
+        categoryHint?: string | undefined;
+        importance?: "low" | "medium" | "high" | undefined;
+        confidence?: "user-stated" | "tool-verified" | "inferred" | "historical" | undefined;
+        sourceRefs?: string[] | undefined;
+    } | {
+        kind: "candidate_status";
+        candidateId: string;
+        status: "processed";
+        runId: string;
+        recordedAt: string;
+    }>;
+    static parseMaintenanceRun(value: unknown): z.ZodSafeParseResult<{
+        id: string;
+        startedAt: string;
+        finishedAt: string;
+        source: string;
+        outcome: "error" | "done" | "max_steps" | "interrupted" | "skipped";
+        summary: string;
+        candidateIds: string[];
+        processedCandidateIds: string[];
+        failedCandidateIds: string[];
+        catalogValid: boolean;
+        catalogMissing: string[];
+    }>;
+    static parseMaintenanceLock(value: unknown): z.ZodSafeParseResult<{
+        id: string;
+        acquiredAt: string;
+        pid?: number | undefined;
+    }>;
+}
+//# sourceMappingURL=schemas.d.ts.map

package/dist/src/core/memory/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qBAAa,aAAa;IACxB,MAAM,CAAC,QAAQ,CAAC,SAAS;;;;;;;;;;;;;;;;;;;sBAUtB;IAEH,MAAM,CAAC,QAAQ,CAAC,eAAe;;;;;;sBAM5B;IAEH,MAAM,CAAC,QAAQ,CAAC,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;wBAG9B;IAEH,MAAM,CAAC,QAAQ,CAAC,cAAc;;;;;;;;;;;;;;;;;;sBAY3B;IAEH,MAAM,CAAC,QAAQ,CAAC,eAAe;;;;sBAI5B;IAEH,MAAM,CAAC,sBAAsB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;;;;;IAI5C,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;IAIzC,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,OAAO;;;;;CAG3C"}

package/dist/src/core/memory/schemas.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export class MemorySchemas {
+    static candidate = z.object({
+        id: z.string().describe('Stable id for a pending durable knowledge candidate.'),
+        recordedAt: z.string().describe('ISO timestamp when the candidate was recorded.'),
+        status: z.literal('pending').describe('Candidates in the JSONL log are pending until a status event marks them processed.'),
+        summary: z.string().describe('Concise durable fact or preference to preserve.'),
+        evidence: z.array(z.string()).optional().describe('Short supporting observations.'),
+        categoryHint: z.string().optional().describe('Suggested memory category.'),
+        importance: z.enum(['low', 'medium', 'high']).optional().describe('Expected future value.'),
+        confidence: z.enum(['user-stated', 'tool-verified', 'inferred', 'historical']).optional().describe('Why the candidate should be trusted.'),
+        sourceRefs: z.array(z.string()).optional().describe('Workspace-relative paths, commands, trace ids, or note references.'),
+    });
+    static candidateStatus = z.object({
+        kind: z.literal('candidate_status').describe('Discriminator for candidate status events in the candidate JSONL log.'),
+        candidateId: z.string().describe('Candidate id whose status changed.'),
+        status: z.literal('processed').describe('Processed candidates are hidden from pending reads.'),
+        runId: z.string().describe('Maintenance run that processed the candidate.'),
+        recordedAt: z.string().describe('ISO timestamp when the status event was recorded.'),
+    });
+    static candidateLogEntry = z.union([
+        MemorySchemas.candidate,
+        MemorySchemas.candidateStatus,
+    ]);
+    static maintenanceRun = z.object({
+        id: z.string().describe('Stable id for a memory maintenance run.'),
+        startedAt: z.string().describe('ISO timestamp when the run started.'),
+        finishedAt: z.string().describe('ISO timestamp when the run finished.'),
+        source: z.string().describe('Caller or workflow that triggered the run.'),
+        outcome: z.enum(['done', 'max_steps', 'error', 'interrupted', 'skipped']).describe('Agent-loop or maintenance outcome.'),
+        summary: z.string().describe('Human-readable run result summary.'),
+        candidateIds: z.array(z.string()).describe('All candidate ids considered by the run.'),
+        processedCandidateIds: z.array(z.string()).describe('Candidate ids successfully processed.'),
+        failedCandidateIds: z.array(z.string()).describe('Candidate ids skipped or not processed.'),
+        catalogValid: z.boolean().describe('Whether required memory catalogs existed after the run.'),
+        catalogMissing: z.array(z.string()).describe('Missing required catalog paths.'),
+    });
+    static maintenanceLock = z.object({
+        id: z.string().describe('Opaque lock owner id.'),
+        pid: z.number().optional().describe('Process id that acquired the lock.'),
+        acquiredAt: z.string().describe('ISO timestamp when the lock was acquired.'),
+    });
+    static parseCandidateLogEntry(value) {
+        return MemorySchemas.candidateLogEntry.safeParse(value);
+    }
+    static parseMaintenanceRun(value) {
+        return MemorySchemas.maintenanceRun.safeParse(value);
+    }
+    static parseMaintenanceLock(value) {
+        return MemorySchemas.maintenanceLock.safeParse(value);
+    }
+}
+//# sourceMappingURL=schemas.js.map

package/dist/src/core/memory/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../../src/core/memory/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,OAAO,aAAa;IACxB,MAAM,CAAU,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;QACnC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;QAC/E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QACjF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,oFAAoF,CAAC;QAC3H,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;QAC/E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;QACnF,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;QAC1E,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QAC3F,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;QAC1I,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oEAAoE,CAAC;KAC1H,CAAC,CAAC;IAEH,MAAM,CAAU,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;QACzC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,QAAQ,CAAC,uEAAuE,CAAC;QACrH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACtE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,qDAAqD,CAAC;QAC9F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;QAC3E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;KACrF,CAAC,CAAC;IAEH,MAAM,CAAU,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC;QAC1C,aAAa,CAAC,SAAS;QACvB,aAAa,CAAC,eAAe;KAC9B,CAAC,CAAC;IAEH,MAAM,CAAU,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;QACxC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;QAClE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QACrE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;QACvE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACzE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACxH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAClE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACtF,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QAC5F,kBAAkB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;QAC3F,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;QAC7F,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;KAChF,CAAC,CAAC;IAEH,MAAM,CAAU,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;QACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAChD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QACzE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;KAC7E,CAAC,CAAC;IAEH,MAAM,CAAC,sBAAsB,CAAC,KAAc;QAC1C,OAAO,aAAa,CAAC,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,KAAc;QACvC,OAAO,aAAa,CAAC,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,oBAAoB,CAAC,KAAc;QACxC,OAAO,aAAa,CAAC,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC"}

package/dist/src/core/memory/types.d.ts

@@ -0,0 +1,149 @@
+import type { LlmAdapter } from '../../core/llm/types.js';
+import type { RunResult, TraceEvent } from '../../core/types.js';
+export type MemoryCategory = {
+    path: string;
+    title: string;
+    purpose: string;
+    readWhen: string;
+};
+export type BootstrapMemoryWorkspaceResult = {
+    memoryRoot: string;
+    createdPaths: string[];
+};
+export type MemoryCatalogLoadResult = {
+    memoryRoot: string;
+    catalogPath: string;
+    exists: boolean;
+    content: string;
+    truncated: boolean;
+    originalBytes: number;
+    maxBytes: number;
+};
+export type MemoryCatalogShapeValidation = {
+    ok: boolean;
+    memoryRoot: string;
+    missing: string[];
+};
+export type KnowledgeCandidate = {
+    id: string;
+    recordedAt: string;
+    status: 'pending';
+    summary: string;
+    evidence?: string[];
+    categoryHint?: string;
+    importance?: 'low' | 'medium' | 'high';
+    confidence?: 'user-stated' | 'tool-verified' | 'inferred' | 'historical';
+    sourceRefs?: string[];
+};
+export type KnowledgeCandidateStatusRecord = {
+    kind: 'candidate_status';
+    candidateId: string;
+    status: 'processed';
+    runId: string;
+    recordedAt: string;
+};
+export type KnowledgeMaintenanceRunRecord = {
+    id: string;
+    startedAt: string;
+    finishedAt: string;
+    source: string;
+    outcome: RunResult['outcome'] | 'skipped';
+    summary: string;
+    candidateIds: string[];
+    processedCandidateIds: string[];
+    failedCandidateIds: string[];
+    catalogValid: boolean;
+    catalogMissing: string[];
+};
+export type RunKnowledgeMaintenanceOptions = {
+    memoryRoot: string;
+    observations: KnowledgeCandidate[];
+    llm: LlmAdapter;
+    source: string;
+    maxSteps?: number;
+    now?: () => Date;
+    nextRunId?: () => string;
+};
+export type RunKnowledgeMaintenanceResult = {
+    run: KnowledgeMaintenanceRunRecord;
+    result?: RunResult;
+};
+export type RunMaintenanceForRecordedCandidatesOptions = {
+    memoryRoot: string;
+    llm: LlmAdapter;
+    source: string;
+    trace: TraceEvent[];
+    maxSteps?: number;
+    lockTimeoutMs?: number;
+    lockStaleAfterMs?: number;
+    onTraceEvent?: (event: TraceEvent) => void;
+};
+export type RunMaintenanceForRecordedCandidatesResult = {
+    candidateIds: string[];
+    maintenance?: RunKnowledgeMaintenanceResult;
+    events: TraceEvent[];
+};
+export type MemoryStatusView = {
+    memoryRoot: string;
+    catalog: {
+        ok: boolean;
+        missing: string[];
+    };
+    notes: {
+        count: number;
+    };
+    candidates: {
+        pending: number;
+    };
+    runs: {
+        latest: KnowledgeMaintenanceRunRecord[];
+    };
+};
+export type MemoryValidationIssue = {
+    type: 'missing_catalog';
+    severity: 'error';
+    path: string;
+    message: string;
+} | {
+    type: 'oversized_catalog';
+    severity: 'warning';
+    path: string;
+    sizeBytes: number;
+    maxBytes: number;
+    message: string;
+} | {
+    type: 'orphan_note';
+    severity: 'warning';
+    path: string;
+    message: string;
+} | {
+    type: 'pending_candidates';
+    severity: 'info';
+    count: number;
+    message: string;
+};
+export type MemoryValidationResult = {
+    memoryRoot: string;
+    ok: boolean;
+    issueCount: number;
+    issues: MemoryValidationIssue[];
+};
+export type ListMemoryNotesInput = {
+    path?: string;
+};
+export type ReadMemoryNoteInput = {
+    path: string;
+    maxLines?: number;
+    offset?: number;
+};
+export type SearchMemoryNotesInput = {
+    query: string;
+    path?: string;
+    maxResults?: number;
+};
+export type MemoryMaintenanceLockRecord = {
+    id: string;
+    pid?: number;
+    acquiredAt: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/core/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/src/core/memory/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/core/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/memory/types.ts"],"names":[],"mappings":""}

package/dist/src/core/memory/validation.d.ts

@@ -1,39 +1,21 @@
-export type MemoryValidationIssue = {
-    type: 'missing_catalog';
-    severity: 'error';
-    path: string;
-    message: string;
-} | {
-    type: 'oversized_catalog';
-    severity: 'warning';
-    path: string;
-    sizeBytes: number;
-    maxBytes: number;
-    message: string;
-} | {
-    type: 'orphan_note';
-    severity: 'warning';
-    path: string;
-    message: string;
-} | {
-    type: 'pending_candidates';
-    severity: 'info';
-    count: number;
-    message: string;
-};
-export type MemoryValidationResult = {
-    memoryRoot: string;
-    ok: boolean;
-    issueCount: number;
-    issues: MemoryValidationIssue[];
-};
-export declare function validateMemoryWorkspace(options: {
-    memoryRoot: string;
-}): Promise<MemoryValidationResult>;
-export declare function repairMissingMemoryCatalogs(options: {
-    memoryRoot: string;
-}): Promise<{
-    memoryRoot: string;
-    createdPaths: string[];
-}>;
+import { MemoryCatalogService } from './catalog.js';
+import { MemoryMaintenanceRepository } from './maintenance-repository.js';
+import { MemoryVisibilityService } from './visibility.js';
+import type { MemoryValidationResult } from './types.js';
+/**
+ * Owns memory workspace health checks and lightweight repair actions.
+ */
+export declare class MemoryValidationService {
+    private readonly memoryRoot;
+    private readonly catalog;
+    private readonly visibility;
+    private readonly maintenance;
+    constructor(memoryRoot: string, catalog?: MemoryCatalogService, visibility?: MemoryVisibilityService, maintenance?: MemoryMaintenanceRepository);
+    validate(): Promise<MemoryValidationResult>;
+    repairMissingCatalogs(): import("./types.js").BootstrapMemoryWorkspaceResult;
+    private appendOversizedCatalogIssues;
+    private appendOrphanNoteIssues;
+    private static catalogPathForNote;
+    private static orphanNoteMessage;
+}
 //# sourceMappingURL=validation.d.ts.map

package/dist/src/core/memory/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/validation.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,qBAAqB,GAC7B;IACA,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GACC;IACA,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,GACC;IACA,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GACC;IACA,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEJ,MAAM,MAAM,sBAAsB,GAAG;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAiC9G;AAED,wBAAsB,2BAA2B,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAE1I"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/validation.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAyB,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEhF;;GAEG;AACH,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAHX,UAAU,EAAE,MAAM,EAClB,OAAO,uBAAuC,EAC9C,UAAU,0BAA0C,EACpD,WAAW,8BAA8C;IAGtE,QAAQ,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAmCjD,qBAAqB;YAIP,4BAA4B;YAoB5B,sBAAsB;IA+BpC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAKjC,OAAO,CAAC,MAAM,CAAC,iBAAiB;CAKjC"}