@lythos/cold-pool 0.14.2 → 0.14.4

package/README.md

@@ -31,7 +31,7 @@ Three layers, sharing the project's `intent → plan → execute` pattern
 Per `ADR-20260502012643244`, locators are FQ-only:
 
 - `host.tld/owner/repo[/skill]` — remote skill (monorepo, flat, or arbitrary subdir)
-- `localhost/<name>` — local-only skill, no remote origin
+- `localhost/me/<skill>` — local-only skill, no remote origin (host/owner/repo aligned)
 
 Bare names and `owner/repo` shorthand are rejected — `parseLocator` returns null.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Cold pool service layer — dedicated resource holder for skill repositories with intent/plan/execute primitives. Single owner of git side-effects; consumed by deck/curator/arena.",
   "keywords": [
     "ai-agent",
@@ -42,7 +42,7 @@
   },
   "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-cold-pool#readme",
   "dependencies": {
-    "@lythos/infra": "^0.14.2",
+    "@lythos/infra": "^0.14.4",
     "simple-git": "^3.36.0"
   },
   "engines": {

package/src/cli.ts

@@ -185,9 +185,19 @@ async function main(): Promise<void> {
         }
       }
 
+      // Metadata integrity check
+      const integrity = pool.metadata.validateIntegrity()
+
       pool.metadata.close()
 
       // Report
+      if (!integrity.ok) {
+        if (integrity.stored === null) {
+          console.log(`ℹ️  Metadata fingerprint not yet stored — first reconcile will create it.`)
+        } else {
+          console.log(`⚠️  Metadata integrity: ${integrity.message}`)
+        }
+      }
       console.log(`\n📊 Validate Report`)
       console.log(`   Cold pool: ${coldPoolPath}`)
       console.log(`   Skills declared: ${lock.skills.length}`)

package/src/cold-pool.ts

@@ -40,6 +40,7 @@ export interface ListPlan {
  * directory. Terminal-depth heuristics alone miss real-world layouts
  * like monorepos with subdirs, multi-skill repos, and mixed-depth clones.
  */
+/** Pure plan builder — IO (readdirSync) done by caller, results injected as allEntries. */
 export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPlan {
   const plan: ListPlanEntry[] = []
   const dirSet = new Set(allEntries.filter(e => e.isDirectory).map(e => e.relPath))

package/src/fetch-plan.ts

@@ -16,6 +16,7 @@ import type { Locator, FetchPlan, FetchResult, FetchIO } from './types.js'
 import { gitClone } from './git-io.js'
 import { getMirror, rewriteUrl } from './mirror.js'
 
+/** Plan builder — IO via ColdPool parameter (pool.has, pool.resolveDir). Execute: executeFetchPlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildFetchPlan(
   pool: ColdPool,
   locator: Locator,

package/src/metadata-db.test.ts

@@ -155,4 +155,60 @@ describe('MetadataDB', () => {
       db2.close()
     })
   })
+
+  describe('integrity fingerprint', () => {
+    it('creates fingerprint after reconcileDeckReferences', () => {
+      db.reconcileDeckReferences('/tmp/test-deck', [
+        { locator: 'github.com/a/b/skill-x', alias: 'x' },
+      ])
+      const result = db.validateIntegrity()
+      expect(result.ok).toBe(true)
+      expect(result.stored).not.toBeNull()
+      expect(result.computed).toBe(result.stored!)
+    })
+
+    it('detects data tampering (corrupted active locators)', () => {
+      db.reconcileDeckReferences('/tmp/test-deck', [
+        { locator: 'github.com/a/b/skill-x', alias: 'x' },
+      ])
+      expect(db.validateIntegrity().ok).toBe(true)
+
+      // Tamper: remove a locator directly via SQL
+      db['db'].exec(`DELETE FROM deck_refs`)
+      const result = db.validateIntegrity()
+      expect(result.ok).toBe(false)
+      expect(result.message).toContain('mismatch')
+    })
+
+    it('detects swapped DB (different schema version)', () => {
+      db.reconcileDeckReferences('/tmp/test-deck', [
+        { locator: 'github.com/a/b/skill-x', alias: 'x' },
+      ])
+      expect(db.validateIntegrity().ok).toBe(true)
+
+      // Tamper: bump schema version in fingerprint record without migration
+      db['db'].exec(`UPDATE _meta_fingerprint SET schema_version = 99`)
+      const result = db.validateIntegrity()
+      expect(result.ok).toBe(false)
+      expect(result.message).toContain('Schema version')
+    })
+
+    it('returns ok when fingerprint is consistent', () => {
+      db.reconcileDeckReferences('/tmp/deck-1', [
+        { locator: 'github.com/x/y/skill-a', alias: 'a' },
+        { locator: 'github.com/x/y/skill-b', alias: 'b' },
+      ])
+      const r1 = db.validateIntegrity()
+      expect(r1.ok).toBe(true)
+
+      // Second reconcile with same data — fingerprint recomputed, still ok
+      db.reconcileDeckReferences('/tmp/deck-1', [
+        { locator: 'github.com/x/y/skill-a', alias: 'a' },
+        { locator: 'github.com/x/y/skill-b', alias: 'b' },
+      ])
+      const r2 = db.validateIntegrity()
+      expect(r2.ok).toBe(true)
+      expect(r2.stored).toBe(r1.computed) // stored should now be latest
+    })
+  })
 })

package/src/metadata-db.ts

@@ -21,6 +21,7 @@
  */
 
 import { SqliteDb } from '@lythos/infra'
+import { createHash } from 'node:crypto'
 
 export type DeckRefState = 'added' | 'linked' | 'removed'
 
@@ -52,7 +53,7 @@ export interface DeckReference {
   removedAt: string | null
 }
 
-const CURRENT_SCHEMA = 6
+const CURRENT_SCHEMA = 7
 
 export class MetadataDB extends SqliteDb {
   constructor(dbPath: string) {
@@ -103,6 +104,16 @@ export class MetadataDB extends SqliteDb {
     this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_state ON deck_refs(state)`)
     this.exec(`CREATE INDEX IF NOT EXISTS idx_skills_repo ON skills(host, owner, repo)`)
 
+    this.exec(`
+      CREATE TABLE IF NOT EXISTS _meta_fingerprint (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        fingerprint TEXT NOT NULL,
+        computed_at TEXT NOT NULL,
+        schema_version INTEGER NOT NULL,
+        active_locator_count INTEGER NOT NULL
+      )
+    `)
+
     // Schema migrations
     this.migrateSchema(CURRENT_SCHEMA, [
       { version: 1, sql: `CREATE TABLE IF NOT EXISTS _schema_version (version INTEGER NOT NULL)` },
@@ -126,6 +137,18 @@ export class MetadataDB extends SqliteDb {
         version: 6,
         sql: `ALTER TABLE deck_refs ADD COLUMN mode TEXT DEFAULT 'symlink'`,
       },
+      {
+        version: 7,
+        sql: `
+          CREATE TABLE IF NOT EXISTS _meta_fingerprint (
+            id INTEGER PRIMARY KEY CHECK (id = 1),
+            fingerprint TEXT NOT NULL,
+            computed_at TEXT NOT NULL,
+            schema_version INTEGER NOT NULL,
+            active_locator_count INTEGER NOT NULL
+          )
+        `,
+      },
     ])
   }
 
@@ -360,5 +383,71 @@ export class MetadataDB extends SqliteDb {
       }
       insert.finalize()
     })()
+
+    this.computeAndStoreFingerprint()
+  }
+
+  // ── Integrity fingerprint ─────────────────────────────────────
+
+  private computeAndStoreFingerprint(): void {
+    const activeLocators = this.getAllActiveLocators().sort().join('\n')
+    const repoCount = (this.db.query('SELECT COUNT(*) as cnt FROM repos').get() as { cnt: number } | null)?.cnt ?? 0
+    const skillCount = (this.db.query('SELECT COUNT(*) as cnt FROM skills').get() as { cnt: number } | null)?.cnt ?? 0
+    const refCount = (this.db.query('SELECT COUNT(*) as cnt FROM deck_refs').get() as { cnt: number } | null)?.cnt ?? 0
+    const alc = activeLocators ? activeLocators.split('\n').length : 0
+    const payload = `${activeLocators}\n${CURRENT_SCHEMA}\n${repoCount}\n${skillCount}\n${refCount}`
+    const fingerprint = createHash('sha256').update(payload).digest('hex')
+
+    this.exec(
+      `INSERT OR REPLACE INTO _meta_fingerprint (id, fingerprint, computed_at, schema_version, active_locator_count)
+       VALUES (1, $fp, $now, $sv, $alc)`,
+      { $fp: fingerprint, $now: this.now(), $sv: CURRENT_SCHEMA, $alc: alc },
+    )
+  }
+
+  /**
+   * Recompute the fingerprint and compare with stored value.
+   * Returns { ok: true } if match, { ok: false, message } with repair hint if mismatch.
+   */
+  validateIntegrity(): { ok: boolean; stored: string | null; computed: string; message: string } {
+    const row = this.db
+      .query(`SELECT fingerprint, computed_at, schema_version FROM _meta_fingerprint WHERE id = 1`)
+      .get() as { fingerprint: string; computed_at: string; schema_version: number } | null
+
+    const activeLocators = this.getAllActiveLocators().sort().join('\n')
+    const repoCount = (this.db.query('SELECT COUNT(*) as cnt FROM repos').get() as { cnt: number } | null)?.cnt ?? 0
+    const skillCount = (this.db.query('SELECT COUNT(*) as cnt FROM skills').get() as { cnt: number } | null)?.cnt ?? 0
+    const refCount = (this.db.query('SELECT COUNT(*) as cnt FROM deck_refs').get() as { cnt: number } | null)?.cnt ?? 0
+    const payload = `${activeLocators}\n${CURRENT_SCHEMA}\n${repoCount}\n${skillCount}\n${refCount}`
+    const computed = createHash('sha256').update(payload).digest('hex')
+
+    if (!row) {
+      return {
+        ok: false,
+        stored: null,
+        computed,
+        message: 'No fingerprint stored. DB may be uninitialized — run deck link to rebuild.',
+      }
+    }
+
+    if (row.schema_version !== CURRENT_SCHEMA) {
+      return {
+        ok: false,
+        stored: row.fingerprint,
+        computed,
+        message: `Schema version mismatch: stored ${row.schema_version}, current ${CURRENT_SCHEMA}. Run deck link to rebuild metadata.`,
+      }
+    }
+
+    if (row.fingerprint !== computed) {
+      return {
+        ok: false,
+        stored: row.fingerprint,
+        computed,
+        message: 'Fingerprint mismatch — metadata DB may have been swapped, corrupted, or desynchronized from cold pool. Run deck link to rebuild.',
+      }
+    }
+
+    return { ok: true, stored: row.fingerprint, computed, message: 'Integrity OK' }
   }
 }

package/src/parse-locator.test.ts

@@ -110,7 +110,7 @@ describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)',
     expect(parseLocator('localhost')).toBeNull()
   })
 
-  test('localhost/<name> (single name, missing repo) is rejected — that was the post-compaction agent invention', () => {
+  test('localhost/<name> (2 segments) is rejected — use localhost/me/<skill> for quick local form', () => {
     expect(parseLocator('localhost/my-skill')).toBeNull()
   })
 })

package/src/parse-locator.ts

@@ -1,19 +1,18 @@
 /**
  * FQ-only locator parser, per ADR-20260502012643244.
  *
- * Three accepted forms (everything else returns null):
+ * Accepted forms (everything else returns null):
  *   - `host.tld/owner/repo[/skill]`        — remote skill
  *   - `host.tld/owner/repo[/skill]#ref`    — remote skill at branch/tag/commit
  *   - `host.tld/owner/repo`                — remote standalone (skill = null)
- *   - `localhost/owner/repo[/skill]`       — local skill, same shape as remote
+ *   - `localhost/me/<skill>`               — local skill, full form (host/owner/repo aligned)
  *
  * The locator is a path. Appending it to the cold-pool base dir gives an
- * existing directory; SKILL.md inside is the skill content. No special-case
- * for localhost — only difference is `host === 'localhost'` signals "no
- * remote, no clone, no refresh".
+ * existing directory; SKILL.md inside is the skill content. For localhost,
+ * `host === 'localhost'` signals "no remote, no clone, no refresh".
  *
- * Single-name `localhost/<name>` is rejected — that's a post-compaction
- * agent invention, not the canonical form.
+ * localhost follows the same host/owner/repo shape as remote locators —
+ * `me` is the conventional owner for personal skills.
  *
  * `#ref` suffix (branch/tag/commit) is compatible with skills.sh's
  * `parseFragmentRef`. The ref is passed to gitClone for checkout.
@@ -41,7 +40,8 @@ export function parseLocator(input: string): Locator | null {
   const parts = pathPart.split('/')
   // Reject empty segments (double slashes) and path traversal
   if (parts.some(p => p === '' || p === '..' || p === '.')) return null
-  // Need at least host/owner/repo (3 segments) for any FQ form
+  // Need at least host/owner/repo (3 segments) for any FQ form.
+  // For localhost quick form, use: localhost/me/<skill-name>
   if (parts.length < 3) return null
 
   // host segment: must be `localhost` (literal) or contain a `.` (host.tld)

package/src/prune-plan.test.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { buildPrunePlan, executePrunePlan } from './prune-plan'
+import { ColdPool } from './cold-pool'
+
+function seedPool(): { root: string; pool: ColdPool } {
+  const root = mkdtempSync(join(tmpdir(), 'prune-test-'))
+  const pool = new ColdPool(root)
+
+  // Repo A: referenced → should NOT be pruned
+  const repoA = join(root, 'github.com', 'org', 'repo-a')
+  mkdirSync(repoA, { recursive: true })
+  writeFileSync(join(repoA, 'SKILL.md'), '# Skill A')
+
+  // Repo B: NOT referenced → SHOULD be pruned
+  const repoB = join(root, 'github.com', 'org', 'repo-b')
+  mkdirSync(repoB, { recursive: true })
+  writeFileSync(join(repoB, 'SKILL.md'), '# Skill B')
+
+  // Repo C: referenced → should NOT be pruned
+  const repoC = join(root, 'github.com', 'org', 'repo-c')
+  mkdirSync(repoC, { recursive: true })
+  writeFileSync(join(repoC, 'SKILL.md'), '# Skill C')
+
+  // Seed metadata: A and C are active, B is not
+  pool.metadata.reconcileDeckReferences('/tmp/test-deck', [
+    { locator: 'github.com/org/repo-a', alias: 'a' },
+    { locator: 'github.com/org/repo-c', alias: 'c' },
+  ])
+
+  return { root, pool }
+}
+
+describe('buildPrunePlan — plan-mode (IO via ColdPool + test filesystem)', () => {
+  let root: string
+  let pool: ColdPool
+
+  beforeEach(() => {
+    const p = seedPool()
+    root = p.root
+    pool = p.pool
+  })
+
+  afterEach(() => {
+    try { pool.metadata.close() } catch {}
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  test('identifies unreferenced repos as prune candidates', () => {
+    const plan = buildPrunePlan(root)
+    expect(plan.candidates.length).toBe(1)
+    expect(plan.candidates[0].repoRel).toBe('github.com/org/repo-b')
+  })
+
+  test('does NOT flag actively referenced repos', () => {
+    const plan = buildPrunePlan(root)
+    const rels = plan.candidates.map(c => c.repoRel)
+    expect(rels).not.toContain('github.com/org/repo-a')
+    expect(rels).not.toContain('github.com/org/repo-c')
+  })
+
+  test('empty cold pool → empty plan', () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), 'prune-empty-'))
+    const plan = buildPrunePlan(emptyDir)
+    expect(plan.candidates).toEqual([])
+    expect(plan.totalSize).toBe(0)
+    rmSync(emptyDir, { recursive: true, force: true })
+  })
+
+  test('plan includes coldPoolPath and totalSize', () => {
+    const plan = buildPrunePlan(root)
+    expect(plan.coldPoolPath).toBe(root)
+    expect(plan.totalSize).toBeGreaterThan(0)
+  })
+})
+
+describe('executePrunePlan — plan-mode (IO injected)', () => {
+  test('calls delete for each candidate', () => {
+    const deleted: string[] = []
+    const plan = {
+      coldPoolPath: '/pool',
+      candidates: [
+        { repoPath: '/pool/gh/org/a', repoRel: 'gh/org/a', size: 1024 },
+        { repoPath: '/pool/gh/org/b', repoRel: 'gh/org/b', size: 2048 },
+      ],
+      totalSize: 3072,
+    }
+    const results = executePrunePlan(plan, {
+      delete: (path) => { deleted.push(path) },
+      log: () => {},
+    })
+    expect(deleted).toEqual(['/pool/gh/org/a', '/pool/gh/org/b'])
+    expect(results).toHaveLength(2)
+    expect(results[0].deleted).toBe(true)
+    expect(results[1].deleted).toBe(true)
+  })
+
+  test('logs count and total size', () => {
+    const logs: string[] = []
+    executePrunePlan({
+      coldPoolPath: '/pool',
+      candidates: [{ repoPath: '/pool/x', repoRel: 'x', size: 500 }],
+      totalSize: 500,
+    }, {
+      delete: () => {},
+      log: (msg) => logs.push(msg),
+    })
+    const joined = logs.join(' ')
+    expect(joined).toContain('1 repo')
+    expect(joined).toContain('500')
+  })
+
+  test('skips delete when candidates array empty', () => {
+    let called = false
+    const results = executePrunePlan(
+      { coldPoolPath: '/pool', candidates: [], totalSize: 0 },
+      { delete: () => { called = true }, log: () => {} },
+    )
+    expect(called).toBe(false)
+    expect(results).toEqual([])
+  })
+})

package/src/prune-plan.ts

@@ -82,6 +82,7 @@ function defaultFormatSize(bytes: number): string {
  * 2. Queries metadata DB for all active locators (state = added/linked/NULL).
  * 3. A repo is prunable if no active locator references it.
  */
+/** Plan builder — IO via ColdPool (findSkillDirectories, metadata queries). Execute: executePrunePlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildPrunePlan(coldPoolPath: string): PrunePlan {
   const pool = new ColdPool(coldPoolPath)
   const allRepos = pool.findSkillDirectories()

package/src/reconcile-plan.ts

@@ -66,6 +66,7 @@ function extractRepo(source: string): RepoKey | null {
 
 // ── Plan builder ───────────────────────────────────────────────────────────
 
+/** Plan builder — IO via ColdPool parameter (list, has, metadata). Execute: executeReconcilePlan(plan, io?) in same file. Mock ColdPool for plan-mode tests. */
 export function buildReconcilePlan(
   coldPool: ColdPool,
   desired: ReconcileDesiredState,

package/src/types.ts

@@ -11,9 +11,10 @@
  *   - `host.tld/owner/repo` (remote standalone — repo root has SKILL.md, skill = null)
  *   - `localhost/owner/repo[/skill]` (no remote — same shape, host literal `localhost`)
  *
- * Bare names, shorthand `owner/repo`, and `localhost/<name>` (no owner/repo)
- * are rejected by `parseLocator`. The locator is a path: appending to coldPool
- * yields `<coldPool>/<host>/<owner>/<repo>[/skill]/SKILL.md`. The only thing
+ * Bare names and shorthand `owner/repo` are rejected by `parseLocator`.
+ * localhost follows host/owner/repo shape: `localhost/me/<skill>`.
+ * The locator is a path: appending to coldPool yields
+ * `<coldPool>/<host>/<owner>/<repo>[/skill]/SKILL.md`. The only thing
  * `isLocalhost` controls is "no remote operations" (no clone, no pull, no fetch).
  */
 export interface Locator {

package/src/validate-plan.ts

@@ -32,6 +32,7 @@ export interface ValidationIO {
 
 const DEFAULT_CHECKS: ValidationCheck[] = ['syntax', 'remote', 'path']
 
+/** Pure plan builder. Execute: executeValidationPlan(plan, io?) in same file — IO injected via ValidationIO. */
 export function buildValidationPlan(
   rawInput: string,
   opts?: { checks?: ReadonlyArray<ValidationCheck>; ref?: string },
@@ -55,7 +56,7 @@ export async function executeValidationPlan(
     fixes.push({
       action: 'update-locator',
       confidence: 0.5,
-      message: 'Locator must be FQ: host.tld/owner/repo[/skill] or localhost/<name>. Bare names are rejected per ADR-20260502012643244.',
+      message: 'Locator must be FQ: host.tld/owner/repo[/skill] or localhost/me/<skill>. Bare names are rejected per ADR-20260502012643244.',
     })
     return {
       status: 'invalid',