@ngockhoale/ukit 3.0.11 → 3.1.0

package/src/core/memory/store.js

@@ -19,9 +19,9 @@ async function storeV2() {
   return import('./storeV2.js');
 }
 
-async function v2Active(projectRoot) {
+async function v2Active(projectRoot, { homeDir } = {}) {
   try {
-    const config = await loadRuntimeConfig(projectRoot);
+    const config = await loadRuntimeConfig(projectRoot, { homeDir });
     if (config?.memoryV2?.enabled === false) return false;
   } catch {
     // unreadable config → default enabled, keep going
@@ -30,7 +30,7 @@ async function v2Active(projectRoot) {
   const v2 = await storeV2();
   // loadRecords triggers ensureMigrated (lazy migration) when autoMigrate is
   // on; records.json existing afterwards — or already — means v2 mode.
-  await v2.loadRecords(projectRoot);
+  await v2.loadRecords(projectRoot, { homeDir });
   try {
     await fs.access(buildRuntimePaths(projectRoot).memoryV2RecordsPath);
     return true;
@@ -271,15 +271,15 @@ function createSearchableText(type, content) {
   ].filter(Boolean).join('\n');
 }
 
-export async function exportMemory(projectRoot) {
+export async function exportMemory(projectRoot, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   // FR-023/025: export is a bulk read lane — redact at the store boundary so
   // every caller (CLI, future lanes) gets defense-in-depth, not just the CLI.
-  const config = await loadRuntimeConfig(projectRoot);
+  const config = await loadRuntimeConfig(projectRoot, { homeDir });
   const redact = (data) => redactWritePayload({ meta: data }, { config }).payload.meta;
-  if (await v2Active(projectRoot)) {
+  if (await v2Active(projectRoot, { homeDir })) {
     const v2 = await storeV2();
-    const items = recordsToMemoryItems(await v2.loadRecords(projectRoot), runtimePaths);
+    const items = recordsToMemoryItems(await v2.loadRecords(projectRoot, { homeDir }), runtimePaths);
     const user = items.find((item) => item.type === 'user')?.content ?? defaultUserMemory();
     return redact({
       user,
@@ -314,11 +314,11 @@ async function warnOnCorruptLegacyFiles(runtimePaths) {
   }
 }
 
-export async function listMemoryItems(projectRoot) {
+export async function listMemoryItems(projectRoot, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (await v2Active(projectRoot)) {
+  if (await v2Active(projectRoot, { homeDir })) {
     const v2 = await storeV2();
-    const records = await v2.loadRecords(projectRoot);
+    const records = await v2.loadRecords(projectRoot, { homeDir });
     await warnOnCorruptLegacyFiles(runtimePaths);
     return recordsToMemoryItems(records, runtimePaths);
   }
@@ -355,7 +355,7 @@ export async function listMemoryItems(projectRoot) {
   ];
 }
 
-async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
+async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths, { homeDir } = {}) {
   const v2 = await storeV2();
   const { mutateMemory } = await import('./mutateMemory.js');
   const archiveAll = async (records) => {
@@ -363,7 +363,7 @@ async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
     for (const record of records) {
       if (record.status !== 'archived') {
         const res = await mutateMemory(
-          { kind: 'project', projectRoot },
+          { kind: 'project', projectRoot, homeDir },
           { op: 'forget', payload: { id: record.id } },
         );
         if (res.status === 'ok') archived += 1;
@@ -373,7 +373,7 @@ async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
   };
 
   if (memoryId === 'user:user' || memoryId === 'user') {
-    const userRecords = await v2.queryRecords(projectRoot, { scope: 'user' });
+    const userRecords = await v2.queryRecords(projectRoot, { scope: 'user', homeDir });
     await archiveAll(userRecords);
     await writeJson(runtimePaths.userMemoryPath, defaultUserMemory());
     // The reset above always removes user memory — `removed` reports that the
@@ -392,7 +392,7 @@ async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
     return { removed: false, type, path: null };
   }
 
-  const records = await v2.loadRecords(projectRoot);
+  const records = await v2.loadRecords(projectRoot, { homeDir });
   const matched = type === 'session'
     ? records.filter((r) => r.type === 'episode' && (r.meta?.legacyId === rawId || r.id === rawId))
     : type === 'project'
@@ -420,10 +420,10 @@ async function forgetMemoryItemV2(projectRoot, memoryId, runtimePaths) {
   return { removed: archived > 0 || legacyRemoved, type: baseDir ? type : null, path: null };
 }
 
-export async function forgetMemoryItem(projectRoot, memoryId) {
+export async function forgetMemoryItem(projectRoot, memoryId, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (await v2Active(projectRoot)) {
-    return forgetMemoryItemV2(projectRoot, memoryId, runtimePaths);
+  if (await v2Active(projectRoot, { homeDir })) {
+    return forgetMemoryItemV2(projectRoot, memoryId, runtimePaths, { homeDir });
   }
   if (memoryId === 'user:user' || memoryId === 'user') {
     await writeJson(runtimePaths.userMemoryPath, defaultUserMemory());
@@ -576,14 +576,14 @@ function patternCandidateFromRecord(record) {
   };
 }
 
-async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
+async function proposePatternCandidateV2(projectRoot, projectId, candidate, { homeDir } = {}) {
   const v2 = await storeV2();
   const normalizedText = normalizePatternText(candidate?.text);
   if (!normalizedText) {
     throw new Error('proposePatternCandidate requires candidate.text');
   }
 
-  const existing = (await v2.queryRecords(projectRoot, { projectId }))
+  const existing = (await v2.queryRecords(projectRoot, { projectId, homeDir }))
     .filter((record) => record.provenance === 'pattern-candidate'
       || String(record.provenance ?? '').includes('pattern-candidate'))
     .find((record) => record.meta?.legacyStatus === 'pending'
@@ -612,13 +612,13 @@ async function proposePatternCandidateV2(projectRoot, projectId, candidate) {
     createdBy: 'propose',
     projectId,
     meta: { ...entry, legacyStatus: 'pending' },
-  });
+  }, { homeDir });
   return entry;
 }
 
-async function listPendingPatternCandidatesV2(projectRoot, projectId) {
+async function listPendingPatternCandidatesV2(projectRoot, projectId, { homeDir } = {}) {
   const v2 = await storeV2();
-  return (await v2.queryRecords(projectRoot, { projectId }))
+  return (await v2.queryRecords(projectRoot, { projectId, homeDir }))
     .filter((record) => record.type === 'derived_fact'
       && record.status !== 'archived'
       && (record.meta?.legacyStatus === 'pending'
@@ -628,9 +628,9 @@ async function listPendingPatternCandidatesV2(projectRoot, projectId) {
     .map(patternCandidateFromRecord);
 }
 
-async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision) {
+async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision, { homeDir } = {}) {
   const v2 = await storeV2();
-  const records = await v2.queryRecords(projectRoot, { projectId });
+  const records = await v2.queryRecords(projectRoot, { projectId, homeDir });
   // Only candidate records are resolvable — matching every record by meta.id
   // let a delta-overlay (meta.id 'ov_*') be "approved" into a project_rule or
   // archived, corrupting the overlay store.
@@ -658,7 +658,7 @@ async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, de
         // Keep the C11 status field in sync for learning candidates.
         ...(isLearningCandidate ? { status: 'approved' } : {}),
       },
-    });
+    }, { homeDir });
   } else {
     updated = await v2.updateRecord(projectRoot, target.id, {
       status: 'archived',
@@ -667,15 +667,15 @@ async function resolvePatternCandidateV2(projectRoot, projectId, candidateId, de
         legacyStatus: 'rejected',
         ...(isLearningCandidate ? { status: 'rejected' } : {}),
       },
-    });
+    }, { homeDir });
   }
   return patternCandidateFromRecord(updated ?? target);
 }
 
-export async function proposePatternCandidate(projectRoot, projectId, candidate) {
+export async function proposePatternCandidate(projectRoot, projectId, candidate, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (await v2Active(projectRoot)) {
-    const entry = await proposePatternCandidateV2(projectRoot, projectId, candidate);
+  if (await v2Active(projectRoot, { homeDir })) {
+    const entry = await proposePatternCandidateV2(projectRoot, projectId, candidate, { homeDir });
     // Mirror into the legacy project file (hygiene + conventions) so the
     // untouched-on-disk legacy format stays read-compatible.
     const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
@@ -719,10 +719,10 @@ export async function proposePatternCandidate(projectRoot, projectId, candidate)
   return entry;
 }
 
-export async function listPendingPatternCandidates(projectRoot, projectId) {
+export async function listPendingPatternCandidates(projectRoot, projectId, { homeDir } = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (await v2Active(projectRoot)) {
-    return listPendingPatternCandidatesV2(projectRoot, projectId);
+  if (await v2Active(projectRoot, { homeDir })) {
+    return listPendingPatternCandidatesV2(projectRoot, projectId, { homeDir });
   }
 
   const { memory } = await readProjectMemoryForId(runtimePaths, projectId);
@@ -730,14 +730,14 @@ export async function listPendingPatternCandidates(projectRoot, projectId) {
   return patternCandidates.filter((entry) => entry.status === 'pending');
 }
 
-export async function resolvePatternCandidate(projectRoot, projectId, candidateId, decision) {
+export async function resolvePatternCandidate(projectRoot, projectId, candidateId, decision, { homeDir } = {}) {
   if (decision !== 'approve' && decision !== 'reject') {
     throw new Error(`Unknown decision: ${decision}`);
   }
 
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (await v2Active(projectRoot)) {
-    const resolved = await resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision);
+  if (await v2Active(projectRoot, { homeDir })) {
+    const resolved = await resolvePatternCandidateV2(projectRoot, projectId, candidateId, decision, { homeDir });
     // Mirror the resolution into the legacy project file.
     const { filePath, memory } = await readProjectMemoryForId(runtimePaths, projectId);
     const patternCandidates = Array.isArray(memory.patternCandidates) ? memory.patternCandidates : [];
@@ -781,8 +781,8 @@ export async function resolvePatternCandidate(projectRoot, projectId, candidateI
   return target;
 }
 
-export async function countMemoryItems(projectRoot) {
-  const exported = await exportMemory(projectRoot);
+export async function countMemoryItems(projectRoot, { homeDir } = {}) {
+  const exported = await exportMemory(projectRoot, { homeDir });
   return {
     projectCount: exported.projects.length,
     sessionCount: exported.sessions.length,

package/src/core/memory/storeV2.js

@@ -26,8 +26,11 @@ const migrationPromises = new Map();
 
 
 
-async function ensureMigrated(projectRoot) {
-  const key = String(projectRoot);
+async function ensureMigrated(projectRoot, { homeDir } = {}) {
+  // Keyed on root+home: the registry consulted for alias-collision checks is
+  // per-home, so identical roots under different homes must not share an
+  // in-flight migration.
+  const key = `${String(projectRoot)}::${String(homeDir ?? '')}`;
   const existing = migrationPromises.get(key);
   if (existing) {
     await existing.promise;
@@ -37,7 +40,7 @@ async function ensureMigrated(projectRoot) {
   const entry = { promise: null, failed: false };
   entry.promise = (async () => {
     try {
-      const config = await loadRuntimeConfig(projectRoot);
+      const config = await loadRuntimeConfig(projectRoot, { homeDir });
       if (config?.memoryV2?.autoMigrate === false) return;
 
       const migrate = await import('./migrate.js');
@@ -45,7 +48,7 @@ async function ensureMigrated(projectRoot) {
       // records.json stranded v1 data forever whenever the file existed
       // without the marker (a pre-migration write, a crashed first run).
       if (await migrate.needsMigration(projectRoot)) {
-        await migrate.runMigration(projectRoot);
+        await migrate.runMigration(projectRoot, { homeDir });
       }
     } catch {
       // Lazy migration is best-effort: a failed auto-run must not break reads.
@@ -67,16 +70,16 @@ async function ensureMigrated(projectRoot) {
  * 'migrating' (auto-migration in-flight or failed), otherwise the
  * readRecordStore state ('ok'|'empty'|'missing'|'corrupt').
  */
-export async function loadRecordsDetailed(projectRoot) {
+export async function loadRecordsDetailed(projectRoot, { homeDir } = {}) {
   try {
-    const config = await loadRuntimeConfig(projectRoot);
+    const config = await loadRuntimeConfig(projectRoot, { homeDir });
     if (config?.memoryV2?.enabled === false) {
       return { state: 'disabled', records: [] };
     }
   } catch {
     // unreadable config → default enabled, keep going
   }
-  const migration = await ensureMigrated(projectRoot);
+  const migration = await ensureMigrated(projectRoot, { homeDir });
   if (migration.failed) {
     return { state: 'migrating', records: [] };
   }
@@ -89,8 +92,8 @@ export async function loadRecordsDetailed(projectRoot) {
 /**
  * loadRecords(projectRoot) → record[] — tolerant: invalid entries skipped.
  */
-export async function loadRecords(projectRoot) {
-  const { records } = await loadRecordsDetailed(projectRoot);
+export async function loadRecords(projectRoot, { homeDir } = {}) {
+  const { records } = await loadRecordsDetailed(projectRoot, { homeDir });
   return records;
 }
 
@@ -103,10 +106,10 @@ async function readStore(projectRoot) {
  * saveRecords(projectRoot, records) → void — explicit restore path
  * (mutateMemory op:'restore'); drops unrecoverable entries.
  */
-export async function saveRecords(projectRoot, records) {
-  await ensureMigrated(projectRoot);
+export async function saveRecords(projectRoot, records, { homeDir } = {}) {
+  await ensureMigrated(projectRoot, { homeDir });
   const res = await mutateMemory(
-    { kind: 'project', projectRoot },
+    { kind: 'project', projectRoot, homeDir },
     { op: 'restore', payload: { records } },
   );
   if (res.status === 'rejected' || res.status === 'conflict' || res.status === 'corrupt') {
@@ -120,16 +123,16 @@ export async function saveRecords(projectRoot, records) {
  * Runs ensureMigrated first — a first v2 write must not create records.json
  * ahead of the v1→v2 migration and strand legacy data.
  */
-export async function addRecord(projectRoot, recordInput) {
+export async function addRecord(projectRoot, recordInput, { homeDir } = {}) {
   const record = isRawRecord(recordInput)
     ? normalizeRecord(recordInput)
     : createRecord(recordInput);
   if (!record) {
     throw new Error('addRecord: input could not be normalized into a valid record');
   }
-  await ensureMigrated(projectRoot);
+  await ensureMigrated(projectRoot, { homeDir });
   const res = await mutateMemory(
-    { kind: 'project', projectRoot },
+    { kind: 'project', projectRoot, homeDir },
     { op: 'add', payload: record },
   );
   if (res.status === 'ok' || res.status === 'duplicate') return res.record ?? record;
@@ -140,10 +143,10 @@ export async function addRecord(projectRoot, recordInput) {
 /**
  * updateRecord(projectRoot, id, patch) → record | null
  */
-export async function updateRecord(projectRoot, id, patch = {}) {
-  await ensureMigrated(projectRoot);
+export async function updateRecord(projectRoot, id, patch = {}, { homeDir } = {}) {
+  await ensureMigrated(projectRoot, { homeDir });
   const res = await mutateMemory(
-    { kind: 'project', projectRoot },
+    { kind: 'project', projectRoot, homeDir },
     { op: 'update', payload: { id, patch } },
   );
   if (res.status === 'ok') return res.record;
@@ -154,17 +157,17 @@ export async function updateRecord(projectRoot, id, patch = {}) {
 /**
  * getRecord(projectRoot, id) → record | null
  */
-export async function getRecord(projectRoot, id) {
-  await ensureMigrated(projectRoot);
+export async function getRecord(projectRoot, id, { homeDir } = {}) {
+  await ensureMigrated(projectRoot, { homeDir });
   const { records } = await readStore(projectRoot);
   return records.find((r) => r.id === id) ?? null;
 }
 
 /**
- * queryRecords(projectRoot, { type?, scope?, status?, projectId? }) → record[]
+ * queryRecords(projectRoot, { type?, scope?, status?, projectId?, homeDir? }) → record[]
  */
-export async function queryRecords(projectRoot, { type, scope, status, projectId } = {}) {
-  const records = await loadRecords(projectRoot);
+export async function queryRecords(projectRoot, { type, scope, status, projectId, homeDir } = {}) {
+  const records = await loadRecords(projectRoot, { homeDir });
   return records.filter((r) => (type == null || r.type === type)
     && (scope == null || r.scope === scope)
     && (status == null || r.status === status)
@@ -174,8 +177,8 @@ export async function queryRecords(projectRoot, { type, scope, status, projectId
 /**
  * stats(projectRoot) → { total, byType, byStatus, invalidSkipped }
  */
-export async function stats(projectRoot) {
-  await ensureMigrated(projectRoot);
+export async function stats(projectRoot, { homeDir } = {}) {
+  await ensureMigrated(projectRoot, { homeDir });
   const { records, invalidSkipped } = await readStore(projectRoot);
   const byType = {};
   const byStatus = {};

package/src/core/memory/storeV2Loader.js

@@ -15,7 +15,7 @@ import { resolveMemoryStage } from './memoryFlags.js';
  * unlisted canary project) reports 'missing' so callers take the legacy
  * lane exactly as if the v2 store were absent.
  */
-export async function loadV2Records(projectRoot, filter = {}, { config, projectId } = {}) {
+export async function loadV2Records(projectRoot, filter = {}, { config, projectId, homeDir } = {}) {
   if (config && resolveMemoryStage(config, 'eligibility', { projectId }) === 'off') {
     return { state: 'missing', records: [] };
   }
@@ -25,7 +25,7 @@ export async function loadV2Records(projectRoot, filter = {}, { config, projectI
       || typeof storeV2?.loadRecordsDetailed !== 'function') {
       return { state: 'missing', records: [] };
     }
-    const { state, records, generation } = await storeV2.loadRecordsDetailed(projectRoot);
+    const { state, records, generation } = await storeV2.loadRecordsDetailed(projectRoot, { homeDir });
     const { type, scope, status, projectId } = filter ?? {};
     const filtered = (Array.isArray(records) ? records : []).filter((r) => (
       (type == null || r.type === type)