@theihtisham/agent-shadow-brain 7.1.0 → 7.1.3

package/dist/brain/mcp-stdio.d.ts

@@ -0,0 +1,12 @@
+import type { Readable, Writable } from 'node:stream';
+import { MCPServer } from './mcp-server.js';
+/** Newline-delimited MCP, with bounded input and sequential backpressure. */
+export declare function serveMCPStdio(server: Pick<MCPServer, 'handleRequest'>, input: Readable, output: Writable): Promise<void>;
+/** Provider-free entry point: no orchestrator, client-profile scan, or config merge. */
+export declare function runMemoryMCPStdio(options?: {
+    dbPath?: string;
+    settingsPath?: string;
+    projectDir?: string;
+    projectId?: string;
+}): Promise<void>;
+//# sourceMappingURL=mcp-stdio.d.ts.map

package/dist/brain/mcp-stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio.d.ts","sourceRoot":"","sources":["../../src/brain/mcp-stdio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAS5C,6EAA6E;AAC7E,wBAAsB,aAAa,CACjC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EACxC,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC,IAAI,CAAC,CAoFf;AAED,wFAAwF;AACxF,wBAAsB,iBAAiB,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxJ"}

package/dist/brain/mcp-stdio.js

@@ -0,0 +1,134 @@
+import { StringDecoder } from 'node:string_decoder';
+import * as path from 'node:path';
+import { MCPServer } from './mcp-server.js';
+import { getGlobalBrain } from './global-brain.js';
+import { FeatureSettingsStore } from './feature-settings.js';
+const MAX_MESSAGE_BYTES = 1024 * 1024;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Newline-delimited MCP, with bounded input and sequential backpressure. */
+export async function serveMCPStdio(server, input, output) {
+    const decoder = new StringDecoder('utf8');
+    let pending = '';
+    let initialized = false;
+    let ready = false;
+    // Node emits a stream error after invoking a failed write callback. Keep a
+    // lifetime listener until those queued events settle, even after send rejects.
+    const consumeOutputError = () => { };
+    output.on('error', consumeOutputError);
+    const send = async (message) => {
+        let payload = JSON.stringify(message) + '\n';
+        if (Buffer.byteLength(payload) > MAX_RESPONSE_BYTES) {
+            payload = JSON.stringify({ jsonrpc: '2.0', id: message.id ?? null,
+                error: { code: -32001, message: 'Result exceeds 4 MiB. Request fewer memories or a smaller context.' } }) + '\n';
+        }
+        await new Promise((resolve, reject) => {
+            if (output.destroyed || output.writableEnded)
+                return reject(new Error('MCP output is closed.'));
+            const timeout = setTimeout(() => finish(new Error('MCP output write timed out.')), 30000);
+            const closed = () => finish(new Error('MCP output closed before delivery.'));
+            const finish = (error) => {
+                clearTimeout(timeout);
+                output.off('close', closed);
+                output.off('error', finish);
+                error ? reject(error) : resolve();
+            };
+            output.once('close', closed);
+            output.once('error', finish);
+            output.write(payload, finish);
+        });
+    };
+    const error = (id, code, message) => send({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+    const dispatch = async (line) => {
+        if (!line.trim())
+            return;
+        if (Buffer.byteLength(line) > MAX_MESSAGE_BYTES)
+            throw new Error('MCP message exceeds 1 MiB.');
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            await error(null, -32700, 'Invalid JSON.');
+            return;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            await error(null, -32600, 'Expected one JSON-RPC message.');
+            return;
+        }
+        const request = value;
+        const valid = request.jsonrpc === '2.0' && typeof request.method === 'string' &&
+            (request.id === undefined || typeof request.id === 'string' || (typeof request.id === 'number' && Number.isFinite(request.id))) &&
+            (request.params === undefined || (request.params !== null && typeof request.params === 'object' && !Array.isArray(request.params)));
+        if (!valid) {
+            await error(null, -32600, 'Invalid JSON-RPC request.');
+            return;
+        }
+        // Notifications never receive responses and never dispatch mutating tool calls.
+        if (request.id === undefined) {
+            if (request.method === 'notifications/initialized' && initialized)
+                ready = true;
+            return;
+        }
+        if (request.method === 'initialize') {
+            if (initialized) {
+                await error(request.id, -32600, 'Already initialized.');
+                return;
+            }
+            if (typeof request.params?.protocolVersion !== 'string' || !record(request.params.clientInfo) || !record(request.params.capabilities) ||
+                typeof request.params.clientInfo.name !== 'string' || !request.params.clientInfo.name.trim() ||
+                typeof request.params.clientInfo.version !== 'string' || !request.params.clientInfo.version.trim()) {
+                await error(request.id, -32602, 'Initialization requires protocolVersion, clientInfo, and capabilities.');
+                return;
+            }
+            const response = await server.handleRequest(request);
+            if (!response.error)
+                initialized = true;
+            await send(response);
+            return;
+        }
+        if (request.method !== 'ping' && !ready) {
+            await error(request.id, -32002, 'Initialize and send notifications/initialized before using tools.');
+            return;
+        }
+        const response = await server.handleRequest(request);
+        await send(response);
+    };
+    try {
+        for await (const chunk of input) {
+            pending += decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            let newline;
+            while ((newline = pending.indexOf('\n')) >= 0) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                await dispatch(line);
+            }
+            if (Buffer.byteLength(pending) > MAX_MESSAGE_BYTES)
+                throw new Error('MCP message exceeds 1 MiB.');
+        }
+        pending += decoder.end();
+        if (pending.trim())
+            await error(null, -32700, 'Connection ended before the message newline.');
+    }
+    finally {
+        await new Promise(resolve => setImmediate(resolve));
+        output.off('error', consumeOutputError);
+    }
+}
+/** Provider-free entry point: no orchestrator, client-profile scan, or config merge. */
+export async function runMemoryMCPStdio(options = {}) {
+    if (options.projectId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(options.projectId))
+        throw new TypeError('Project ID must be a bounded identifier.');
+    const brain = getGlobalBrain(options.dbPath ? { dbPath: path.resolve(options.dbPath) } : undefined);
+    const settings = new FeatureSettingsStore({ filePath: options.settingsPath ??
+            (options.dbPath ? path.join(path.dirname(path.resolve(options.dbPath)), 'feature-settings.json') : undefined) });
+    const server = new MCPServer(null, { authToken: '', toolProfile: 'memory' }, { brain, settings, projectDir: options.projectDir, projectId: options.projectId });
+    try {
+        await serveMCPStdio(server, process.stdin, process.stdout);
+    }
+    finally {
+        await server.finishMemorySession();
+        await brain.shutdown();
+    }
+}
+//# sourceMappingURL=mcp-stdio.js.map

package/dist/brain/mcp-stdio.js.map

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

package/dist/brain/memory-annotations.d.ts

@@ -0,0 +1,97 @@
+export declare const MEMORY_ANNOTATIONS_FILENAME = "memory-annotations.json";
+export declare const MEMORY_ANNOTATION_LIMITS: Readonly<{
+    reviews: 5000;
+    links: 5000;
+    history: 500;
+    note: 1000;
+    bytes: number;
+}>;
+export declare const MEMORY_REVIEW_STATES: readonly ["active", "archived", "contested"];
+export declare const MEMORY_RELATION_TYPES: readonly ["related", "supports", "contradicts", "supersedes"];
+export type MemoryReviewState = typeof MEMORY_REVIEW_STATES[number];
+export type MemoryRelationType = typeof MEMORY_RELATION_TYPES[number];
+export type EffectiveMemoryState = MemoryReviewState | 'superseded';
+export interface MemoryReview {
+    projectId: string;
+    state: MemoryReviewState;
+    note: string;
+    updatedAt: string;
+}
+export interface MemoryRelation {
+    id: string;
+    projectId: string;
+    fromId: string;
+    toId: string;
+    type: MemoryRelationType;
+    note: string;
+    createdAt: string;
+}
+export type MemoryAnnotationCommand = {
+    kind: 'review';
+    projectId: string;
+    memoryId: string;
+    state: MemoryReviewState;
+    note?: string;
+} | {
+    kind: 'link';
+    projectId: string;
+    fromId: string;
+    toId: string;
+    type: MemoryRelationType;
+    note?: string;
+} | {
+    kind: 'unlink';
+    linkId: string;
+};
+export interface MemoryAnnotationEvent {
+    revision: number;
+    at: string;
+    projectId: string;
+    command: MemoryAnnotationCommand;
+    relationId?: string;
+    relation?: MemoryRelation;
+    previousReview?: MemoryReview;
+}
+export interface MemoryAnnotationSnapshot {
+    schemaVersion: 1;
+    revision: number;
+    updatedAt: string | null;
+    reviews: Record<string, MemoryReview>;
+    links: MemoryRelation[];
+    history: MemoryAnnotationEvent[];
+}
+type MemoryIdentity = {
+    id: string;
+    projectId: string;
+};
+export interface MemoryAnnotationsOptions {
+    filePath?: string;
+    lockTimeoutMs?: number;
+    resolveMemory: (id: string) => MemoryIdentity | undefined;
+}
+export declare class MemoryAnnotationsError extends Error {
+    readonly code: 'ANNOTATIONS_INVALID_COMMAND' | 'ANNOTATIONS_INVALID_STORE' | 'ANNOTATIONS_CONFLICT' | 'ANNOTATIONS_NOT_FOUND' | 'ANNOTATIONS_LOCK_TIMEOUT' | 'ANNOTATIONS_LOCK_FAILED' | 'ANNOTATIONS_READ_FAILED' | 'ANNOTATIONS_WRITE_FAILED';
+    constructor(code: 'ANNOTATIONS_INVALID_COMMAND' | 'ANNOTATIONS_INVALID_STORE' | 'ANNOTATIONS_CONFLICT' | 'ANNOTATIONS_NOT_FOUND' | 'ANNOTATIONS_LOCK_TIMEOUT' | 'ANNOTATIONS_LOCK_FAILED' | 'ANNOTATIONS_READ_FAILED' | 'ANNOTATIONS_WRITE_FAILED', message: string);
+}
+/** Use the latest review and replacement relation for the supplied project and memory. */
+export declare function memoryState(snapshot: MemoryAnnotationSnapshot, projectId: string, memoryId: string): EffectiveMemoryState;
+/** Independent local curation state. The original memory store remains schema version 1. */
+export declare class MemoryAnnotationsStore {
+    readonly filePath: string;
+    private readonly resolveMemory;
+    private readonly lockTimeout;
+    constructor(options: MemoryAnnotationsOptions);
+    get(): MemoryAnnotationSnapshot;
+    update(raw: unknown, expectedRevision?: number): Promise<MemoryAnnotationSnapshot>;
+    private requireMemory;
+    private apply;
+    private acquireLock;
+    private unlinkOwnedLock;
+    private replace;
+}
+export declare function memoryAnnotationsFor(brain: {
+    dbPath: string;
+    getEntry(id: string): MemoryIdentity | undefined;
+}): MemoryAnnotationsStore;
+export {};
+//# sourceMappingURL=memory-annotations.d.ts.map

package/dist/brain/memory-annotations.d.ts.map

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

package/dist/brain/memory-annotations.js

@@ -0,0 +1,388 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+export const MEMORY_ANNOTATIONS_FILENAME = 'memory-annotations.json';
+export const MEMORY_ANNOTATION_LIMITS = Object.freeze({
+    reviews: 5000, links: 5000, history: 500, note: 1000, bytes: 16 * 1024 * 1024,
+});
+export const MEMORY_REVIEW_STATES = ['active', 'archived', 'contested'];
+export const MEMORY_RELATION_TYPES = ['related', 'supports', 'contradicts', 'supersedes'];
+export class MemoryAnnotationsError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MemoryAnnotationsError';
+    }
+}
+const LOCK_TIMEOUT = 3000;
+const LOCK_POLL = 20;
+const MAX_IDENTIFIER = 256;
+const FORBIDDEN_IDS = new Set(['__proto__', 'constructor', 'prototype']);
+function errno(error) {
+    return error?.code;
+}
+function record(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function identifier(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= MAX_IDENTIFIER &&
+        value === value.trim() && !/[\u0000-\u001f\u007f]/.test(value) && !FORBIDDEN_IDS.has(value);
+}
+function note(value) {
+    return typeof value === 'string' && value.length <= MEMORY_ANNOTATION_LIMITS.note;
+}
+function instant(value) {
+    if (typeof value !== 'string')
+        return false;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+function reviewState(value) {
+    return MEMORY_REVIEW_STATES.some(state => state === value);
+}
+function relationType(value) {
+    return MEMORY_RELATION_TYPES.some(type => type === value);
+}
+function keysOnly(input, allowed) {
+    return Object.keys(input).every(key => allowed.includes(key));
+}
+function parseCommand(value) {
+    if (!record(value))
+        return undefined;
+    const raw = { ...value };
+    if (raw.kind === 'unlink' && identifier(raw.linkId) && keysOnly(raw, ['kind', 'linkId'])) {
+        return { kind: 'unlink', linkId: raw.linkId };
+    }
+    if (!identifier(raw.projectId) || (raw.note !== undefined && !note(raw.note)))
+        return undefined;
+    const reviewNote = typeof raw.note === 'string' ? raw.note.trim() : '';
+    if (raw.kind === 'review' && identifier(raw.memoryId) && reviewState(raw.state) &&
+        keysOnly(raw, ['kind', 'projectId', 'memoryId', 'state', 'note'])) {
+        return { kind: 'review', projectId: raw.projectId, memoryId: raw.memoryId, state: raw.state, note: reviewNote };
+    }
+    if (raw.kind === 'link' && identifier(raw.fromId) && identifier(raw.toId) && relationType(raw.type) &&
+        raw.fromId !== raw.toId && keysOnly(raw, ['kind', 'projectId', 'fromId', 'toId', 'type', 'note'])) {
+        return {
+            kind: 'link', projectId: raw.projectId, fromId: raw.fromId, toId: raw.toId,
+            type: raw.type, note: reviewNote,
+        };
+    }
+    return undefined;
+}
+function key(projectId, id) {
+    return JSON.stringify([projectId, id]);
+}
+function relationKey(link) {
+    const symmetric = link.type === 'related' || link.type === 'contradicts';
+    const endpoints = symmetric ? [link.fromId, link.toId].sort() : [link.fromId, link.toId];
+    return JSON.stringify([link.projectId, link.type, ...endpoints]);
+}
+function graphProblem(links) {
+    const ids = new Set();
+    const relationKeys = new Set();
+    const replacementOf = new Map();
+    for (const link of links) {
+        const relation = relationKey(link);
+        if (ids.has(link.id) || relationKeys.has(relation))
+            return 'This memory relation already exists.';
+        ids.add(link.id);
+        relationKeys.add(relation);
+        if (link.type !== 'supersedes')
+            continue;
+        const target = key(link.projectId, link.toId);
+        if (replacementOf.has(target))
+            return 'This memory already has a replacement. Remove that relation first.';
+        replacementOf.set(target, key(link.projectId, link.fromId));
+    }
+    const complete = new Set();
+    for (const start of replacementOf.keys()) {
+        const seen = new Set();
+        for (let current = start; current !== undefined && !complete.has(current); current = replacementOf.get(current)) {
+            if (seen.has(current))
+                return 'A supersession chain cannot contain a cycle.';
+            seen.add(current);
+        }
+        for (const id of seen)
+            complete.add(id);
+    }
+    return undefined;
+}
+function validReview(value) {
+    return record(value) && keysOnly(value, ['projectId', 'state', 'note', 'updatedAt']) &&
+        identifier(value.projectId) && reviewState(value.state) && note(value.note) && instant(value.updatedAt);
+}
+function validLink(value) {
+    return record(value) && keysOnly(value, ['id', 'projectId', 'fromId', 'toId', 'type', 'note', 'createdAt']) &&
+        identifier(value.id) && identifier(value.projectId) &&
+        identifier(value.fromId) && identifier(value.toId) && value.fromId !== value.toId &&
+        relationType(value.type) && note(value.note) && instant(value.createdAt);
+}
+function validHistory(history, revision) {
+    if (!Array.isArray(history) || history.length !== Math.min(revision, MEMORY_ANNOTATION_LIMITS.history))
+        return false;
+    const first = revision - history.length + 1;
+    return history.every((event, index) => {
+        if (!record(event) || !keysOnly(event, ['revision', 'at', 'projectId', 'command', 'relationId', 'relation', 'previousReview']) ||
+            event.revision !== first + index || !instant(event.at) || !identifier(event.projectId))
+            return false;
+        const command = parseCommand(event.command);
+        if (!command)
+            return false;
+        if (command.kind === 'review') {
+            return command.projectId === event.projectId && event.relationId === undefined && event.relation === undefined &&
+                (event.previousReview === undefined || (validReview(event.previousReview) && event.previousReview.projectId === event.projectId));
+        }
+        if (event.previousReview !== undefined || !validLink(event.relation) ||
+            event.relation.id !== event.relationId || event.relation.projectId !== event.projectId)
+            return false;
+        if (command.kind === 'unlink')
+            return event.relationId === command.linkId;
+        return command.projectId === event.projectId && command.type === event.relation.type &&
+            command.fromId === event.relation.fromId && command.toId === event.relation.toId;
+    });
+}
+function emptySnapshot() {
+    return { schemaVersion: 1, revision: 0, updatedAt: null, reviews: {}, links: [], history: [] };
+}
+function parseSnapshot(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (record(data) && keysOnly(data, ['schemaVersion', 'revision', 'updatedAt', 'reviews', 'links', 'history']) &&
+            data.schemaVersion === 1 && typeof data.revision === 'number' &&
+            Number.isSafeInteger(data.revision) && data.revision >= 1 && instant(data.updatedAt) &&
+            record(data.reviews) && Object.keys(data.reviews).length <= MEMORY_ANNOTATION_LIMITS.reviews &&
+            Object.entries(data.reviews).every(([id, review]) => identifier(id) && validReview(review)) &&
+            Array.isArray(data.links) && data.links.length <= MEMORY_ANNOTATION_LIMITS.links &&
+            data.links.every(validLink) && !graphProblem(data.links) && validHistory(data.history, data.revision) &&
+            data.history[data.history.length - 1].at === data.updatedAt) {
+            return {
+                schemaVersion: 1, revision: data.revision, updatedAt: data.updatedAt,
+                reviews: data.reviews, links: data.links, history: data.history,
+            };
+        }
+    }
+    catch { /* Preserve store bytes and report the schema error without content. */ }
+    throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_STORE', 'Memory annotations are malformed or use an unsupported schema.');
+}
+/** Use the latest review and replacement relation for the supplied project and memory. */
+export function memoryState(snapshot, projectId, memoryId) {
+    if (snapshot.links.some(link => link.type === 'supersedes' && link.projectId === projectId && link.toId === memoryId)) {
+        return 'superseded';
+    }
+    const review = snapshot.reviews[memoryId];
+    return review?.projectId === projectId ? review.state : 'active';
+}
+/** Independent local curation state. The original memory store remains schema version 1. */
+export class MemoryAnnotationsStore {
+    constructor(options) {
+        this.filePath = path.resolve(options.filePath ?? path.join(os.homedir(), '.shadow-brain', MEMORY_ANNOTATIONS_FILENAME));
+        this.resolveMemory = options.resolveMemory;
+        this.lockTimeout = typeof options.lockTimeoutMs === 'number' && Number.isFinite(options.lockTimeoutMs)
+            ? Math.max(0, Math.min(60000, options.lockTimeoutMs))
+            : LOCK_TIMEOUT;
+    }
+    get() {
+        let raw;
+        try {
+            const stat = fs.lstatSync(this.filePath, { throwIfNoEntry: false });
+            if (!stat)
+                return emptySnapshot();
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_STORE', 'Memory annotations must be a regular local file.');
+            }
+            if (stat.size > MEMORY_ANNOTATION_LIMITS.bytes) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_STORE', 'Memory annotation file exceeds its size limit.');
+            }
+            const fd = fs.openSync(this.filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+            try {
+                const current = fs.fstatSync(fd);
+                if (!current.isFile() || current.nlink !== 1 || current.size > MEMORY_ANNOTATION_LIMITS.bytes) {
+                    throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_STORE', 'Memory annotation file changed or exceeds its size limit.');
+                }
+                raw = fs.readFileSync(fd, 'utf8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch (error) {
+            if (error instanceof MemoryAnnotationsError)
+                throw error;
+            throw new MemoryAnnotationsError('ANNOTATIONS_READ_FAILED', 'Could not read memory annotations.');
+        }
+        return parseSnapshot(raw);
+    }
+    async update(raw, expectedRevision) {
+        const command = parseCommand(raw);
+        if (!command || (expectedRevision !== undefined &&
+            (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0))) {
+            throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_COMMAND', 'Invalid memory annotation command or revision.');
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        }
+        catch {
+            throw new MemoryAnnotationsError('ANNOTATIONS_WRITE_FAILED', 'Could not open the memory annotation directory.');
+        }
+        const release = await this.acquireLock();
+        try {
+            const snapshot = this.get();
+            if (expectedRevision !== undefined && expectedRevision !== snapshot.revision) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_CONFLICT', 'Memory annotations changed. Refresh and retry the update.');
+            }
+            if (snapshot.revision === Number.MAX_SAFE_INTEGER) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_STORE', 'Memory annotation revision has reached its limit.');
+            }
+            const at = new Date().toISOString();
+            const revision = snapshot.revision + 1;
+            const event = this.apply(snapshot, command, revision, at);
+            snapshot.revision = revision;
+            snapshot.updatedAt = at;
+            snapshot.history = [...snapshot.history, event].slice(-MEMORY_ANNOTATION_LIMITS.history);
+            this.replace(snapshot);
+            return snapshot;
+        }
+        finally {
+            release();
+        }
+    }
+    requireMemory(id, projectId) {
+        const memory = this.resolveMemory(id);
+        if (memory?.id !== id || memory.projectId !== projectId) {
+            throw new MemoryAnnotationsError('ANNOTATIONS_NOT_FOUND', 'Memory was not found in the selected project.');
+        }
+    }
+    apply(snapshot, command, revision, at) {
+        if (command.kind === 'unlink') {
+            const index = snapshot.links.findIndex(link => link.id === command.linkId);
+            if (index < 0)
+                throw new MemoryAnnotationsError('ANNOTATIONS_NOT_FOUND', 'Memory relation was not found.');
+            const [removed] = snapshot.links.splice(index, 1);
+            return { command, revision, at, projectId: removed.projectId, relationId: removed.id, relation: removed };
+        }
+        const { projectId } = command;
+        if (command.kind === 'review') {
+            this.requireMemory(command.memoryId, projectId);
+            const previous = snapshot.reviews[command.memoryId];
+            if (previous && previous.projectId !== projectId) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_CONFLICT', 'Memory identity no longer matches its recorded project.');
+            }
+            if (!previous && Object.keys(snapshot.reviews).length >= MEMORY_ANNOTATION_LIMITS.reviews) {
+                throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_COMMAND', 'Memory review storage limit reached.');
+            }
+            snapshot.reviews[command.memoryId] = { projectId, state: command.state, note: command.note ?? '', updatedAt: at };
+            return { command, revision, at, projectId, ...(previous ? { previousReview: previous } : {}) };
+        }
+        this.requireMemory(command.fromId, projectId);
+        this.requireMemory(command.toId, projectId);
+        if (snapshot.links.length >= MEMORY_ANNOTATION_LIMITS.links) {
+            throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_COMMAND', 'Memory relation storage limit reached.');
+        }
+        const relation = {
+            id: randomUUID(), projectId, fromId: command.fromId, toId: command.toId,
+            type: command.type, note: command.note ?? '', createdAt: at,
+        };
+        snapshot.links.push(relation);
+        const problem = graphProblem(snapshot.links);
+        if (problem)
+            throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_COMMAND', problem);
+        return { command, revision, at, projectId, relationId: relation.id, relation };
+    }
+    async acquireLock() {
+        const lock = this.filePath + '.lock';
+        const deadline = performance.now() + this.lockTimeout;
+        for (;;) {
+            let fd;
+            try {
+                fd = fs.openSync(lock, 'wx', 0o600);
+            }
+            catch (error) {
+                if (errno(error) !== 'EEXIST')
+                    throw new MemoryAnnotationsError('ANNOTATIONS_LOCK_FAILED', 'Could not acquire the memory annotation lock.');
+                const remaining = deadline - performance.now();
+                if (remaining <= 0)
+                    break;
+                await delay(Math.min(remaining, LOCK_POLL));
+                if (performance.now() >= deadline)
+                    break;
+                continue;
+            }
+            let owner;
+            try {
+                owner = fs.fstatSync(fd, { bigint: true });
+                fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }));
+                fs.closeSync(fd);
+            }
+            catch {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* retain the original lock failure */ }
+                try {
+                    if (owner)
+                        this.unlinkOwnedLock(lock, owner);
+                }
+                catch { /* preserve an unfamiliar lock */ }
+                throw new MemoryAnnotationsError('ANNOTATIONS_LOCK_FAILED', 'Could not initialize the memory annotation lock.');
+            }
+            const owned = owner;
+            return () => this.unlinkOwnedLock(lock, owned);
+        }
+        throw new MemoryAnnotationsError('ANNOTATIONS_LOCK_TIMEOUT', 'Timed out waiting for the memory annotation lock.');
+    }
+    unlinkOwnedLock(lock, owner) {
+        try {
+            const current = fs.lstatSync(lock, { bigint: true, throwIfNoEntry: false });
+            if (current?.dev !== owner.dev || current.ino !== owner.ino)
+                throw new Error('Lock ownership changed.');
+            fs.unlinkSync(lock);
+        }
+        catch {
+            throw new MemoryAnnotationsError('ANNOTATIONS_LOCK_FAILED', 'Could not release the memory annotation lock.');
+        }
+    }
+    replace(snapshot) {
+        const payload = JSON.stringify(snapshot, null, 2) + '\n';
+        if (Buffer.byteLength(payload) > MEMORY_ANNOTATION_LIMITS.bytes) {
+            throw new MemoryAnnotationsError('ANNOTATIONS_INVALID_COMMAND', 'Memory annotation storage limit reached.');
+        }
+        const temporary = this.filePath + '.' + randomUUID() + '.tmp';
+        let created = false;
+        try {
+            const fd = fs.openSync(temporary, 'wx', 0o600);
+            created = true;
+            try {
+                fs.writeFileSync(fd, payload);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(temporary, this.filePath);
+            created = false;
+        }
+        catch {
+            throw new MemoryAnnotationsError('ANNOTATIONS_WRITE_FAILED', 'Could not save memory annotations.');
+        }
+        finally {
+            if (created) {
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch { /* retain the original write failure */ }
+            }
+        }
+    }
+}
+export function memoryAnnotationsFor(brain) {
+    return new MemoryAnnotationsStore({
+        filePath: path.join(path.dirname(brain.dbPath), MEMORY_ANNOTATIONS_FILENAME),
+        resolveMemory: id => brain.getEntry(id),
+    });
+}
+//# sourceMappingURL=memory-annotations.js.map