shieldcortex 4.28.0 → 4.29.0

package/dist/license/store.js

@@ -9,7 +9,7 @@
  *
  * License is cached in memory after first read.
  */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { verifyLicenseKey } from './verify.js';
@@ -22,10 +22,32 @@ function getLicenseFilePath() {
     return join(getConfigDir(), 'license.json');
 }
 // ── Cache ────────────────────────────────────────────────
+//
+// In-memory cache of the parsed/verified licence. Refreshed automatically
+// when the on-disk file mtime changes (v4.27.2). This lets long-running
+// workers pick up `shieldcortex license activate <key>` without a process
+// restart — previously the worker held the old tier cached for its
+// lifetime and any cloud_sync / heartbeat feature gate stayed stuck on
+// the value at startup. The mtime check is a single stat() per call
+// (microseconds); cheap enough to run on every gate hit.
 let cachedLicense = null;
+let cachedLicenseFileMtimeMs = null;
+/**
+ * Read the licence file's current mtime (ms). Returns null if the file
+ * doesn't exist — that's a valid cached state too (= FREE).
+ */
+function readLicenseFileMtimeMs() {
+    try {
+        return statSync(getLicenseFilePath()).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
 /** Clear the in-memory cache (useful for testing or after activation). */
 export function clearLicenseCache() {
     cachedLicense = null;
+    cachedLicenseFileMtimeMs = null;
     clearTrialCache();
 }
 // ── Read ─────────────────────────────────────────────────
@@ -34,6 +56,15 @@ export function clearLicenseCache() {
  * Returns a LicenseInfo with tier='free' if no license exists or verification fails.
  */
 export function getLicense() {
+    // Hot-reload: if the licence file's mtime has changed since the value
+    // was cached (or the file appeared/disappeared), drop the cache so the
+    // new tier takes effect immediately. This is what makes long-running
+    // workers see `shieldcortex license activate <key>` without a restart.
+    const currentMtimeMs = readLicenseFileMtimeMs();
+    if (cachedLicense !== null && cachedLicenseFileMtimeMs !== currentMtimeMs) {
+        cachedLicense = null;
+        clearTrialCache();
+    }
     if (cachedLicense)
         return cachedLicense;
     const FREE = {
@@ -49,11 +80,13 @@ export function getLicense() {
         const licenseFile = getLicenseFilePath();
         if (!existsSync(licenseFile)) {
             cachedLicense = FREE;
+            cachedLicenseFileMtimeMs = null;
             return FREE;
         }
         const raw = JSON.parse(readFileSync(licenseFile, 'utf-8'));
         if (!raw.key) {
             cachedLicense = FREE;
+            cachedLicenseFileMtimeMs = currentMtimeMs;
             return FREE;
         }
         // Check if previously marked as revoked or expired by online validation.
@@ -62,15 +95,18 @@ export function getLicense() {
         // so we only hard-block on revoked here.
         if (raw.validationStatus === 'revoked') {
             cachedLicense = FREE;
+            cachedLicenseFileMtimeMs = currentMtimeMs;
             return FREE;
         }
         // Verify the key cryptographically (checks exp + grace period)
         const info = verifyLicenseKey(raw.key);
         cachedLicense = info;
+        cachedLicenseFileMtimeMs = currentMtimeMs;
         return info;
     }
     catch {
         cachedLicense = FREE;
+        cachedLicenseFileMtimeMs = currentMtimeMs;
         return FREE;
     }
 }
@@ -126,8 +162,10 @@ export function activateLicense(key) {
     const licenseFile = getLicenseFilePath();
     mkdirSync(configDir, { recursive: true });
     writeFileSync(licenseFile, JSON.stringify(file, null, 2) + '\n', { mode: 0o600 });
-    // Invalidate cache
+    // Refresh cache + mtime so the next getLicense() call in this process
+    // doesn't trigger a re-read for no reason.
     cachedLicense = info;
+    cachedLicenseFileMtimeMs = readLicenseFileMtimeMs();
     return info;
 }
 /**
@@ -144,6 +182,7 @@ export function deactivateLicense() {
         // Best effort
     }
     cachedLicense = null;
+    cachedLicenseFileMtimeMs = null;
     clearTrialCache();
 }
 /**
@@ -162,6 +201,7 @@ export function updateValidationStatus(status) {
         // If revoked or expired, invalidate cache so next getLicense() re-verifies
         if (status === 'revoked' || status === 'expired') {
             cachedLicense = null;
+            cachedLicenseFileMtimeMs = null;
         }
     }
     catch {

package/dist/memory/consolidate.d.ts

@@ -27,8 +27,42 @@ export declare function findDuplicateMemoryPairs(options?: {
     limit?: number;
 }): DuplicateMemoryPair[];
 /**
- * Find memories with very similar titles/content and merge them.
- * Keeps the newer one, appends unique content from the older one.
+ * De-duplicate long-term memories found as duplicate PAIRS by
+ * findDuplicateMemoryPairs (same project|category, similar title + >0.5 content
+ * overlap). Runs every ~4h on the auto path: server.ts setInterval → fullCleanup
+ * → consolidate → deduplicateMemories.
+ *
+ * B11 (memory-quality fix): the previous implementation built
+ * `kept.content + "\n\nMerged from duplicate:\n" + uniqueSentences` and wrote it
+ * back with `UPDATE memories SET content = ?`. That was the SECOND lossy-append
+ * site (mergeSimilarMemories was the first) and kept generating ever-growing
+ * "frankenmemories" on this path even after the first site was fixed. The kept
+ * memory's `content` is now NEVER modified.
+ *
+ * New policy (identical to mergeSimilarMemories — one source of truth):
+ *   - KEEP the higher-EFFECTIVE-salience member of the pair (computeEffectiveSalience
+ *     via the shared salience.mjs — recency/access/pin/downvote, same ranking as
+ *     recall and the downvote CLI). NOTE: this can differ from the pair's raw
+ *     `recommendedKeepId`, which only considered raw salience + recency.
+ *   - Dispose the loser via the shared disposeLoser: combined similarity
+ *     (re-measured vs the kept row) ≥ 0.85 → DELETE; below → DOWNVOTE (reversible).
+ *   - Tags are unioned onto the kept row (metadata only, non-lossy). The kept
+ *     content and salience are untouched.
+ *
+ * Defence re-scan removed (B11): the old re-scan existed ONLY to validate the
+ * SYNTHESIZED concatenated merged body before persisting it (two individually-
+ * clean rows could straddle a credential pattern across the join). Now that no
+ * concatenation happens here, there is no synthesized content to scan — the kept
+ * row's bytes are written verbatim and unchanged, exactly as they already exist
+ * in `memories`. So this pass introduces no new bytes to validate. (This is a
+ * narrow claim about THIS path: it does not assume every row was scanned at write
+ * time — e.g. importMemories inserts rows with no scan — only that the dedup no
+ * longer fabricates a new body that would need scanning.) Dropping the re-scan
+ * also avoids re-auditing unchanged content on every 4h pass.
+ *
+ * Only rows clustered in THIS pass are acted on; historical merged rows are not
+ * rewritten (effective salience demotes them over time). STM→LTM promotion is
+ * handled separately by processDecay/promoteMemory in consolidate().
  */
 export declare function deduplicateMemories(options?: {
     dryRun?: boolean;
@@ -55,10 +89,32 @@ export declare function clusterAndSummarise(options?: {
  */
 export declare function enforceMemoryLimits(config?: MemoryConfig): number;
 /**
- * Find and merge similar short-term memories into coherent long-term entries.
- * Groups memories by project|category, then clusters by Jaccard similarity
- * on content (0.6 weight) + title (0.4 weight).
- * Returns count of deleted (merged) memories.
+ * Find clusters of similar short-term memories within each project|category,
+ * KEEP the single highest-effective-salience member, and demote the rest
+ * WITHOUT destroying or concatenating their content.
+ *
+ * B11 (memory-quality fix): the previous implementation appended every loser's
+ * body into the kept memory ("Consolidated context:" bullets) and deleted the
+ * losers. Over ~417 live rows this produced 188 ever-growing "frankenmemories"
+ * — exactly the garbled content users complained about. The kept memory's
+ * `content` is now NEVER modified.
+ *
+ * Disposition per loser (see NEAR_IDENTICAL_DELETE_THRESHOLD):
+ *   - combined ≥ 0.85  → DELETE (near-identical; content already in the kept row)
+ *   - combined < 0.85  → DOWNVOTE (reversible; sinks via effective salience)
+ *
+ * Why the split exists at all: NO reaping path (decay.ts shouldDelete,
+ * prune.ts, expiry.ts, enforceMemoryLimits) reads `downvote_count` or effective
+ * salience — they all order by raw `salience`. So downvote-ONLY would leave the
+ * store unbounded (the dups sink in recall but never get pruned). Deleting the
+ * near-identical losers keeps the store bounded with zero information loss; the
+ * moderate near-dups are preserved and merely demoted.
+ *
+ * Tags are unioned onto the kept row and access counts summed (metadata only,
+ * non-lossy). STM→LTM promotion is handled separately by processDecay/
+ * promoteMemory in consolidate(); this function only de-duplicates.
+ *
+ * Returns the count of deleted (near-identical) losers.
  */
 export declare function mergeSimilarMemories(project?: string, similarityThreshold?: number): number;
 /**
@@ -144,5 +200,25 @@ export interface DreamModeResult {
  * 1. Find near-duplicates by embedding similarity >0.9, merge them
  * 2. Flag memories >30 days old with no access as archival candidates
  * 3. Detect and flag contradictions
+ *
+ * DISPOSAL POLICY — deliberately DIVERGES from the auto path:
+ * This is the EXPLICIT, user-invoked `shieldcortex consolidate` command (and the
+ * public `consolidateMemories` export). Because the user has actively asked for a
+ * consolidation, aggressive cleanup is the intended behaviour: the loser of every
+ * duplicate pair is HARD-DELETED. This is on purpose and must NOT be replaced with
+ * the gentle `disposeLoser` policy.
+ *
+ * Contrast with the 4-hourly AUTO path (deduplicateMemories / mergeSimilarMemories),
+ * which runs UNATTENDED and therefore uses the conservative `disposeLoser`: it only
+ * deletes near-identical losers (combined ≥ 0.85, content already contained in the
+ * kept row) and merely DOWNVOTES (reversible) the moderate near-dups. That caution
+ * is right for an unsupervised background job, but wrong for a deliberate manual
+ * cleanup the user explicitly triggered.
+ *
+ * The two paths DO share keep-selection: both pick the kept row by EFFECTIVE
+ * salience (effectiveSalienceOfRow — recency/access/pin/downvote), so the row that
+ * survives is consistent across all three dedup sites. Effective salience also
+ * discriminates where the pair's raw `recommendedKeepId` (raw salience + recency)
+ * ties at 1.0.
  */
 export declare function consolidateMemories(): DreamModeResult;