feat(gc): incremental GC with importance scoring and protection rules (STA-314)

Add generational garbage collection: importance_score column, score-based
eviction ordering, active frame and session protection via protectedRunIds,
dedicated GC timer (60s default), and score recomputation in maintenance.

Author: StackMemory Bot (CLI)

src/core/context/frame-database.ts

@@ -118,6 +118,7 @@ export class FrameDatabase {
           created_at INTEGER NOT NULL DEFAULT (unixepoch()),
           closed_at INTEGER,
           retention_policy TEXT DEFAULT 'default',
+          importance_score REAL DEFAULT 0.5,
           FOREIGN KEY (parent_frame_id) REFERENCES frames(frame_id)
         );
       `);
@@ -160,6 +161,15 @@ export class FrameDatabase {
         // Column already exists — safe to ignore
       }
 
+      // Migration: add importance_score column if missing (pre-v1.3 databases)
+      try {
+        this.db.exec(
+          'ALTER TABLE frames ADD COLUMN importance_score REAL DEFAULT 0.5'
+        );
+      } catch {
+        // Column already exists — safe to ignore
+      }
+
       // Create indexes for performance
       this.db.exec(`
         CREATE INDEX IF NOT EXISTS idx_frames_run ON frames(run_id);
@@ -170,6 +180,7 @@ export class FrameDatabase {
         CREATE INDEX IF NOT EXISTS idx_frames_project_state ON frames(project_id, state);
         CREATE INDEX IF NOT EXISTS idx_frames_project_created ON frames(project_id, created_at DESC);
         CREATE INDEX IF NOT EXISTS idx_frames_retention_created ON frames(retention_policy, created_at);
+        CREATE INDEX IF NOT EXISTS idx_frames_gc_score ON frames(state, retention_policy, importance_score ASC, created_at ASC);
         CREATE INDEX IF NOT EXISTS idx_events_frame ON events(frame_id);
         CREATE INDEX IF NOT EXISTS idx_events_seq ON events(frame_id, seq);
         CREATE INDEX IF NOT EXISTS idx_anchors_frame ON anchors(frame_id);

src/core/database/__tests__/gc.test.ts

@@ -30,22 +30,30 @@ describe('Garbage Collection', () => {
   });
 
   /**
-   * Helper: insert a frame with a specific created_at timestamp and retention_policy
+   * Helper: insert a frame with configurable created_at, retention_policy, state, importance_score, run_id
    */
   function insertFrame(opts: {
     frameId: string;
     createdAt: number;
     retentionPolicy?: string;
+    state?: string;
+    importanceScore?: number;
+    runId?: string;
+    digestText?: string | null;
   }): void {
     const db = adapter.getRawDatabase()!;
     db.prepare(
-      `INSERT INTO frames (frame_id, run_id, project_id, type, name, state, depth, inputs, outputs, digest_json, created_at, retention_policy)
-       VALUES (?, 'run-1', 'test-project', 'task', ?, 'active', 0, '{}', '{}', '{}', ?, ?)`
+      `INSERT INTO frames (frame_id, run_id, project_id, type, name, state, depth, inputs, outputs, digest_text, digest_json, created_at, retention_policy, importance_score)
+       VALUES (?, ?, 'test-project', 'task', ?, ?, 0, '{}', '{}', ?, '{}', ?, ?, ?)`
     ).run(
       opts.frameId,
+      opts.runId ?? 'run-1',
       `frame-${opts.frameId}`,
+      opts.state ?? 'closed',
+      opts.digestText ?? null,
       opts.createdAt,
-      opts.retentionPolicy ?? 'default'
+      opts.retentionPolicy ?? 'default',
+      opts.importanceScore ?? 0.5
     );
   }
 
@@ -57,12 +65,16 @@ describe('Garbage Collection', () => {
     ).run(eventId, frameId);
   }
 
-  function insertAnchor(frameId: string, anchorId: string): void {
+  function insertAnchor(
+    frameId: string,
+    anchorId: string,
+    type: string = 'pin'
+  ): void {
     const db = adapter.getRawDatabase()!;
     db.prepare(
       `INSERT INTO anchors (anchor_id, frame_id, project_id, type, text, priority)
-       VALUES (?, ?, 'test-project', 'pin', 'test anchor', 0)`
-    ).run(anchorId, frameId);
+       VALUES (?, ?, 'test-project', ?, 'test anchor', 0)`
+    ).run(anchorId, frameId, type);
   }
 
   function countRows(table: string): number {
@@ -74,9 +86,20 @@ describe('Garbage Collection', () => {
     ).count;
   }
 
+  function getImportanceScore(frameId: string): number {
+    const db = adapter.getRawDatabase()!;
+    return (
+      db
+        .prepare('SELECT importance_score FROM frames WHERE frame_id = ?')
+        .get(frameId) as { importance_score: number }
+    ).importance_score;
+  }
+
   const nowSec = Math.floor(Date.now() / 1000);
   const daysAgo = (d: number) => nowSec - d * 86400;
 
+  // --- Existing retention-based tests (updated for state='closed') ---
+
   it('should delete frames older than retention period', async () => {
     insertFrame({ frameId: 'old-1', createdAt: daysAgo(100) });
     insertFrame({ frameId: 'old-2', createdAt: daysAgo(95) });
@@ -240,12 +263,11 @@ describe('Garbage Collection', () => {
       digest_text: 'this frame will be garbage collected',
     });
 
-    // Backdate it so it qualifies for GC
+    // Backdate and close it so it qualifies for GC
     const db = adapter.getRawDatabase()!;
-    db.prepare('UPDATE frames SET created_at = ? WHERE frame_id = ?').run(
-      daysAgo(100),
-      frameId
-    );
+    db.prepare(
+      "UPDATE frames SET created_at = ?, state = 'closed' WHERE frame_id = ?"
+    ).run(daysAgo(100), frameId);
 
     // Verify it is searchable before GC
     let results = await adapter.search({ query: 'searchable' });
@@ -257,4 +279,243 @@ describe('Garbage Collection', () => {
     results = await adapter.search({ query: 'searchable' });
     expect(results.length).toBe(0);
   });
+
+  // --- Protection rules ---
+
+  describe('Protection rules', () => {
+    it('should not delete active frames', async () => {
+      insertFrame({
+        frameId: 'active-old',
+        createdAt: daysAgo(100),
+        state: 'active',
+      });
+      insertFrame({
+        frameId: 'closed-old',
+        createdAt: daysAgo(100),
+        state: 'closed',
+      });
+
+      const result = await adapter.runGC({ retentionDays: 90 });
+
+      expect(result.framesDeleted).toBe(1);
+      const active = await adapter.getFrame('active-old');
+      expect(active).not.toBeNull();
+      const closed = await adapter.getFrame('closed-old');
+      expect(closed).toBeNull();
+    });
+
+    it('should not delete frames with protected run_id', async () => {
+      insertFrame({
+        frameId: 'protected-1',
+        createdAt: daysAgo(100),
+        runId: 'active-session',
+      });
+      insertFrame({
+        frameId: 'unprotected-1',
+        createdAt: daysAgo(100),
+        runId: 'old-session',
+      });
+
+      const result = await adapter.runGC({
+        retentionDays: 90,
+        protectedRunIds: ['active-session'],
+      });
+
+      expect(result.framesDeleted).toBe(1);
+      const kept = await adapter.getFrame('protected-1');
+      expect(kept).not.toBeNull();
+      const deleted = await adapter.getFrame('unprotected-1');
+      expect(deleted).toBeNull();
+    });
+
+    it('should still delete closed frames past retention when not protected', async () => {
+      insertFrame({
+        frameId: 'closed-expired',
+        createdAt: daysAgo(100),
+        state: 'closed',
+      });
+
+      const result = await adapter.runGC({ retentionDays: 90 });
+
+      expect(result.framesDeleted).toBe(1);
+    });
+  });
+
+  // --- Score-based eviction ---
+
+  describe('Score-based eviction', () => {
+    it('should evict lowest importance_score first', async () => {
+      insertFrame({
+        frameId: 'low-score',
+        createdAt: daysAgo(100),
+        importanceScore: 0.2,
+      });
+      insertFrame({
+        frameId: 'mid-score',
+        createdAt: daysAgo(100),
+        importanceScore: 0.5,
+      });
+      insertFrame({
+        frameId: 'high-score',
+        createdAt: daysAgo(100),
+        importanceScore: 0.8,
+      });
+
+      const result = await adapter.runGC({
+        retentionDays: 90,
+        batchSize: 1,
+      });
+
+      expect(result.framesDeleted).toBe(1);
+      // Lowest score should be deleted first
+      const low = await adapter.getFrame('low-score');
+      expect(low).toBeNull();
+      const mid = await adapter.getFrame('mid-score');
+      expect(mid).not.toBeNull();
+      const high = await adapter.getFrame('high-score');
+      expect(high).not.toBeNull();
+    });
+
+    it('should evict by created_at when scores are equal', async () => {
+      insertFrame({
+        frameId: 'older',
+        createdAt: daysAgo(200),
+        importanceScore: 0.3,
+      });
+      insertFrame({
+        frameId: 'newer',
+        createdAt: daysAgo(100),
+        importanceScore: 0.3,
+      });
+
+      const result = await adapter.runGC({
+        retentionDays: 90,
+        batchSize: 1,
+      });
+
+      expect(result.framesDeleted).toBe(1);
+      // Older frame should be deleted first when scores are equal
+      const older = await adapter.getFrame('older');
+      expect(older).toBeNull();
+      const newer = await adapter.getFrame('newer');
+      expect(newer).not.toBeNull();
+    });
+  });
+
+  // --- Importance scoring ---
+
+  describe('Importance scoring', () => {
+    it('should compute base score for empty frame', async () => {
+      insertFrame({
+        frameId: 'empty-frame',
+        createdAt: daysAgo(10),
+        importanceScore: 0.5,
+      });
+
+      const score = adapter.computeImportanceScore('empty-frame');
+      // Base score: 0.3 (no anchors, no events > 3, no digest, no children, not recent)
+      expect(score).toBe(0.3);
+    });
+
+    it('should increase score for frames with DECISION anchors', async () => {
+      insertFrame({
+        frameId: 'decision-frame',
+        createdAt: daysAgo(10),
+      });
+      insertAnchor('decision-frame', 'anc-decision', 'DECISION');
+
+      const score = adapter.computeImportanceScore('decision-frame');
+      // Base 0.3 + 0.15 (DECISION) = 0.45
+      expect(score).toBe(0.45);
+    });
+
+    it('should increase score for frames with digest_text', async () => {
+      insertFrame({
+        frameId: 'digest-frame',
+        createdAt: daysAgo(10),
+        digestText: 'This frame has a digest',
+      });
+
+      const score = adapter.computeImportanceScore('digest-frame');
+      // Base 0.3 + 0.15 (digest) = 0.45
+      expect(score).toBe(0.45);
+    });
+
+    it('should increase score for frames with many events', async () => {
+      insertFrame({
+        frameId: 'eventful-frame',
+        createdAt: daysAgo(10),
+      });
+      for (let i = 0; i < 5; i++) {
+        insertEvent('eventful-frame', `evt-${i}`);
+      }
+
+      const score = adapter.computeImportanceScore('eventful-frame');
+      // Base 0.3 + 0.1 (events > 3) = 0.4
+      expect(score).toBe(0.4);
+    });
+
+    it('should increase score for recent frames', async () => {
+      // Insert a frame less than 1 day old
+      insertFrame({
+        frameId: 'recent-frame',
+        createdAt: nowSec - 3600, // 1 hour ago
+      });
+
+      const score = adapter.computeImportanceScore('recent-frame');
+      // Base 0.3 + 0.1 (recency) = 0.4
+      expect(score).toBe(0.4);
+    });
+
+    it('should cap score at 1.0', async () => {
+      // Create a frame with all scoring factors
+      insertFrame({
+        frameId: 'max-frame',
+        createdAt: nowSec - 3600, // recent
+        digestText: 'Has digest',
+      });
+      insertAnchor('max-frame', 'anc-dec', 'DECISION');
+      for (let i = 0; i < 5; i++) {
+        insertEvent('max-frame', `evt-max-${i}`);
+      }
+      // Insert a child frame
+      const db = adapter.getRawDatabase()!;
+      db.prepare(
+        `INSERT INTO frames (frame_id, run_id, project_id, type, name, state, depth, parent_frame_id, inputs, outputs, digest_json, created_at, retention_policy, importance_score)
+         VALUES ('child-1', 'run-1', 'test-project', 'task', 'child', 'closed', 1, 'max-frame', '{}', '{}', '{}', ?, 'default', 0.5)`
+      ).run(nowSec);
+
+      const score = adapter.computeImportanceScore('max-frame');
+      // 0.3 + 0.15 (DECISION) + 0.1 (events) + 0.15 (digest) + 0.1 (children) + 0.1 (recency) = 0.9
+      expect(score).toBe(0.9);
+      expect(score).toBeLessThanOrEqual(1.0);
+    });
+
+    it('should recompute scores in batches', async () => {
+      // Insert frames with default score of 0.5
+      insertFrame({
+        frameId: 'score-1',
+        createdAt: daysAgo(10),
+        importanceScore: 0.5,
+        digestText: 'Has digest text',
+      });
+      insertFrame({
+        frameId: 'score-2',
+        createdAt: daysAgo(10),
+        importanceScore: 0.5,
+      });
+
+      const updated = adapter.recomputeImportanceScores(100);
+
+      // score-1 should get recomputed (0.3 + 0.15 digest = 0.45, != 0.5 so updated)
+      // score-2 should get recomputed (0.3, != 0.5 so updated)
+      expect(updated).toBe(2);
+
+      const score1 = getImportanceScore('score-1');
+      expect(score1).toBe(0.45);
+
+      const score2 = getImportanceScore('score-2');
+      expect(score2).toBe(0.3);
+    });
+  });
 });

src/core/database/database-adapter.ts

@@ -234,6 +234,7 @@ export abstract class DatabaseAdapter {
     retentionDays?: number;
     batchSize?: number;
     dryRun?: boolean;
+    protectedRunIds?: string[];
   }): Promise<{
     framesDeleted: number;
     eventsDeleted: number;