@lythos/cold-pool 0.9.26 → 0.9.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.26",
+  "version": "0.9.28",
   "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",
@@ -33,6 +33,9 @@
     "url": "https://github.com/lythos-labs/lythoskill/issues"
   },
   "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-cold-pool#readme",
+  "dependencies": {
+    "simple-git": "^3.36.0"
+  },
   "engines": {
     "bun": ">=1.0.0"
   }

package/src/cold-pool.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool'
@@ -99,3 +99,22 @@ describe('ColdPool — fs-backed read accessors', () => {
     expect(empty.list()).toEqual([])
   })
 })
+
+describe('ColdPool.metadata — MetadataDB integration', () => {
+  const root = mkdtempSync(join(tmpdir(), 'cold-pool-meta-test-'))
+  const pool = new ColdPool(root)
+
+  test('metadata is auto-created on first access (lazy-open)', () => {
+    expect(pool.metadata).toBeDefined()
+    // Lazy-open: DB file is NOT created until first method call.
+    expect(existsSync(join(root, '.cold-pool-meta.db'))).toBe(false)
+    // Trigger open with a no-op read.
+    pool.metadata.getRepoRef('github.com', 'nonexistent', 'repo')
+    expect(existsSync(join(root, '.cold-pool-meta.db'))).toBe(true)
+  })
+
+  test('metadata records survive round-trip', () => {
+    pool.metadata.recordRepoRef('github.com', 'lythos-labs', 'lythoskill', '9645fdb')
+    expect(pool.metadata.getRepoRef('github.com', 'lythos-labs', 'lythoskill')).toBe('9645fdb')
+  })
+})

package/src/cold-pool.ts

@@ -10,15 +10,18 @@ import { existsSync, readdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Locator } from './types.js'
+import { MetadataDB } from './metadata-db.js'
 
 export const DEFAULT_COLD_POOL_PATH = process.env.LYTHOS_COLD_POOL
   ?? join(homedir(), '.agents/skill-repos')
 
 export class ColdPool {
   readonly path: string
+  readonly metadata: MetadataDB
 
   constructor(coldPoolPath?: string) {
     this.path = coldPoolPath ?? DEFAULT_COLD_POOL_PATH
+    this.metadata = new MetadataDB(join(this.path, '.cold-pool-meta.db'))
   }
 
   /**

package/src/git-hash.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { simpleGit } from 'simple-git'
+import { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'
+
+let repoDir: string
+
+beforeAll(async () => {
+  repoDir = mkdtempSync(join(tmpdir(), 'lythos-git-hash-test-'))
+  const git = simpleGit(repoDir)
+  await git.init(['--initial-branch=main'])
+  writeFileSync(join(repoDir, 'SKILL.md'), '# Test Skill\n')
+  mkdirSync(join(repoDir, 'skills', 'pdf'), { recursive: true })
+  writeFileSync(join(repoDir, 'skills', 'pdf', 'SKILL.md'), '# PDF Skill\n> renders PDF\n')
+  await git.add('.')
+  await git.commit('initial')
+})
+
+afterAll(() => {
+  rmSync(repoDir, { recursive: true, force: true })
+})
+
+describe('hashSkillMd (SHA-256)', () => {
+  it('computes SHA-256 of SKILL.md', () => {
+    const result = hashSkillMd(join(repoDir, 'SKILL.md'))
+    expect(result).toBeString()
+    expect(result.length).toBe(64)
+  })
+
+  it('produces deterministic output', () => {
+    const a = hashSkillMd(join(repoDir, 'SKILL.md'))
+    const b = hashSkillMd(join(repoDir, 'SKILL.md'))
+    expect(a).toBe(b)
+  })
+
+  it('produces different hash for different content', () => {
+    const root = hashSkillMd(join(repoDir, 'SKILL.md'))
+    const nested = hashSkillMd(join(repoDir, 'skills', 'pdf', 'SKILL.md'))
+    expect(root).not.toBe(nested)
+  })
+})
+
+describe('getRepoHeadRef', () => {
+  it('returns HEAD commit hash', async () => {
+    const head = await getRepoHeadRef(repoDir)
+    expect(head).toBeString()
+    expect(head.length).toBe(40)
+  })
+
+  it('matches simple-git log output', async () => {
+    const head = await getRepoHeadRef(repoDir)
+    const log = await simpleGit(repoDir).log()
+    expect(head).toBe(log.latest!.hash)
+  })
+})
+
+describe('getSkillBlobHash', () => {
+  it('hashes SKILL.md in repo root', async () => {
+    const hash = await getSkillBlobHash(repoDir, '')
+    expect(hash).toBeString()
+    expect(hash.length).toBe(40)
+  })
+
+  it('hashes SKILL.md in nested subpath', async () => {
+    const hash = await getSkillBlobHash(repoDir, 'skills/pdf')
+    expect(hash).toBeString()
+    expect(hash.length).toBe(40)
+  })
+
+  it('produces different blob hashes for different files', async () => {
+    const root = await getSkillBlobHash(repoDir, '')
+    const nested = await getSkillBlobHash(repoDir, 'skills/pdf')
+    expect(root).not.toBe(nested)
+  })
+})
+
+describe('getSkillTreeHash', () => {
+  it('returns tree hash for subdirectory', async () => {
+    const hash = await getSkillTreeHash(repoDir, 'skills/pdf')
+    expect(hash).toBeString()
+    expect(hash.length).toBe(40)
+  })
+
+  it('throws on bad path', async () => {
+    await expect(getSkillTreeHash(repoDir, 'nonexistent')).rejects.toThrow()
+  })
+})

package/src/git-hash.ts

@@ -0,0 +1,27 @@
+import { simpleGit, type SimpleGit } from 'simple-git'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+function git(repoDir: string): SimpleGit {
+  return simpleGit(repoDir)
+}
+
+export async function getRepoHeadRef(repoDir: string): Promise<string> {
+  return (await git(repoDir).revparse(['HEAD'])).trim()
+}
+
+export async function getSkillBlobHash(repoDir: string, skillSubpath: string): Promise<string> {
+  const path = skillSubpath ? `${skillSubpath}/SKILL.md` : 'SKILL.md'
+  return (await git(repoDir).raw(['hash-object', path])).trim()
+}
+
+export function hashSkillMd(skillMdPath: string): string {
+  return createHash('sha256').update(readFileSync(skillMdPath, 'utf-8')).digest('hex')
+}
+
+export async function getSkillTreeHash(repoDir: string, skillSubpath: string): Promise<string> {
+  const output = (await git(repoDir).raw(['ls-tree', 'HEAD', skillSubpath || '.'])).trim()
+  const hash = output.split(/\s+/)[2]
+  if (!hash) throw new Error(`Could not parse tree hash from: ${output}`)
+  return hash
+}

package/src/index.ts

@@ -18,6 +18,9 @@ export type {
 export { parseLocator, formatLocator } from './parse-locator.js'
 export { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool.js'
 
+export type { RepoRef, SkillHash, DeckReference } from './metadata-db.js'
+export { MetadataDB } from './metadata-db.js'
+
 export type { TreeEntry, TreeResponse, FetchFn } from './github-tree.js'
 export { fetchRepoTree } from './github-tree.js'
 
@@ -31,3 +34,5 @@ export type { GitCloneOptions, GitPullResult, GitRootResult } from './git-io.js'
 export { gitClone, gitPull, detectGitRoot } from './git-io.js'
 
 export { buildFetchPlan, executeFetchPlan } from './fetch-plan.js'
+
+export { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'

package/src/metadata-db.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { MetadataDB } from './metadata-db.js'
+
+function tempDbPath(): string {
+  return join(tmpdir(), `cold-pool-meta-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`)
+}
+
+describe('MetadataDB', () => {
+  let db: MetadataDB
+  let dbPath: string
+
+  beforeEach(() => {
+    dbPath = tempDbPath()
+    db = new MetadataDB(dbPath)
+  })
+
+  afterEach(() => {
+    db.close()
+    try { Bun.file(dbPath).delete() } catch {}
+  })
+
+  describe('repos', () => {
+    it('records and retrieves a repo HEAD ref', () => {
+      db.recordRepoRef('github.com', 'lythos-labs', 'lythoskill', '9645fdb')
+      expect(db.getRepoRef('github.com', 'lythos-labs', 'lythoskill')).toBe('9645fdb')
+    })
+
+    it('returns null for unknown repo', () => {
+      expect(db.getRepoRef('github.com', 'unknown', 'repo')).toBeNull()
+    })
+
+    it('overwrites on duplicate key', () => {
+      db.recordRepoRef('github.com', 'lythos-labs', 'lythoskill', '9645fdb')
+      db.recordRepoRef('github.com', 'lythos-labs', 'lythoskill', 'a1b2c3d')
+      expect(db.getRepoRef('github.com', 'lythos-labs', 'lythoskill')).toBe('a1b2c3d')
+    })
+
+    it('handles localhost host', () => {
+      db.recordRepoRef('localhost', 'me', 'my-skill', 'abc1234')
+      expect(db.getRepoRef('localhost', 'me', 'my-skill')).toBe('abc1234')
+    })
+  })
+
+  describe('skills', () => {
+    it('records and retrieves a skill hash', () => {
+      db.recordSkillHash('github.com', 'lythos-labs', 'lythoskill', 'skills/lythoskill-deck', 'sha256-e3b0c44', 'git-blob-e3b0c44', '9645fdb')
+      expect(db.getSkillHash('github.com', 'lythos-labs', 'lythoskill', 'skills/lythoskill-deck')).toBe('sha256-e3b0c44')
+    })
+
+    it('handles standalone skill (empty subpath)', () => {
+      db.recordSkillHash('github.com', 'garrytan', 'gstack', '', 'sha256-abc', 'git-blob-abc', 'deadbeef')
+      expect(db.getSkillHash('github.com', 'garrytan', 'gstack', '')).toBe('sha256-abc')
+    })
+
+    it('returns null for unknown skill', () => {
+      expect(db.getSkillHash('github.com', 'unknown', 'repo', 'skill')).toBeNull()
+    })
+
+    it('overwrites on duplicate key', () => {
+      db.recordSkillHash('github.com', 'lythos-labs', 'lythoskill', 'skills/lythoskill-deck', 'oldhash', 'git-old', '9645fdb')
+      db.recordSkillHash('github.com', 'lythos-labs', 'lythoskill', 'skills/lythoskill-deck', 'newhash', 'git-new', 'a1b2c3d')
+      expect(db.getSkillHash('github.com', 'lythos-labs', 'lythoskill', 'skills/lythoskill-deck')).toBe('newhash')
+    })
+  })
+
+  describe('deck_refs', () => {
+    it('adds and retrieves a reference', () => {
+      db.addReference('github.com/lythos-labs/lythoskill/skills/lythoskill-deck', '/project-a/skill-deck.toml', 'lythoskill-deck')
+      const refs = db.getReferencingDecks('github.com/lythos-labs/lythoskill/skills/lythoskill-deck')
+      expect(refs).toHaveLength(1)
+      expect(refs[0].deckPath).toBe('/project-a/skill-deck.toml')
+      expect(refs[0].alias).toBe('lythoskill-deck')
+    })
+
+    it('returns empty array for unreferenced skill', () => {
+      expect(db.getReferencingDecks('github.com/unknown/repo/skill')).toEqual([])
+    })
+
+    it('supports multiple decks referencing same skill', () => {
+      db.addReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml', 'skill-a')
+      db.addReference('github.com/owner/repo/skill', '/project-b/skill-deck.toml', 'skill-b')
+      const refs = db.getReferencingDecks('github.com/owner/repo/skill')
+      expect(refs).toHaveLength(2)
+      const paths = refs.map((r) => r.deckPath).sort()
+      expect(paths).toEqual(['/project-a/skill-deck.toml', '/project-b/skill-deck.toml'])
+    })
+
+    it('removes a specific reference', () => {
+      db.addReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml', 'skill-a')
+      db.addReference('github.com/owner/repo/skill', '/project-b/skill-deck.toml', 'skill-b')
+      db.removeReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml')
+      const refs = db.getReferencingDecks('github.com/owner/repo/skill')
+      expect(refs).toHaveLength(1)
+      expect(refs[0].deckPath).toBe('/project-b/skill-deck.toml')
+    })
+
+    it('removes all references for a deck', () => {
+      db.addReference('github.com/owner/repo/skill-a', '/project-a/skill-deck.toml', 'skill-a')
+      db.addReference('github.com/owner/repo/skill-b', '/project-a/skill-deck.toml', 'skill-b')
+      db.removeAllReferencesForDeck('/project-a/skill-deck.toml')
+      expect(db.getReferencingDecks('github.com/owner/repo/skill-a')).toEqual([])
+      expect(db.getReferencingDecks('github.com/owner/repo/skill-b')).toEqual([])
+    })
+
+    it('allows null alias', () => {
+      db.addReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml', null)
+      const refs = db.getReferencingDecks('github.com/owner/repo/skill')
+      expect(refs[0].alias).toBeNull()
+    })
+  })
+
+  describe('reconcileDeckReferences', () => {
+    it('replaces all references for a deck atomically', () => {
+      // Pre-existing refs
+      db.addReference('github.com/old/repo/skill', '/project-a/skill-deck.toml', 'old-skill')
+      db.addReference('github.com/owner/repo/skill-a', '/project-a/skill-deck.toml', 'skill-a')
+
+      // Reconcile with new declared set
+      db.reconcileDeckReferences('/project-a/skill-deck.toml', [
+        { locator: 'github.com/owner/repo/skill-a', alias: 'skill-a' },
+        { locator: 'github.com/owner/repo/skill-b', alias: 'skill-b' },
+      ])
+
+      // old-skill removed, skill-a kept, skill-b added
+      expect(db.getReferencingDecks('github.com/old/repo/skill')).toEqual([])
+      expect(db.getReferencingDecks('github.com/owner/repo/skill-a')).toHaveLength(1)
+      expect(db.getReferencingDecks('github.com/owner/repo/skill-b')).toHaveLength(1)
+    })
+
+    it('handles empty declared set (deck unlinked)', () => {
+      db.addReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml', 'skill')
+      db.reconcileDeckReferences('/project-a/skill-deck.toml', [])
+      expect(db.getReferencingDecks('github.com/owner/repo/skill')).toEqual([])
+    })
+
+    it('does not affect other decks during reconcile', () => {
+      db.addReference('github.com/owner/repo/skill', '/project-a/skill-deck.toml', 'skill-a')
+      db.addReference('github.com/owner/repo/skill', '/project-b/skill-deck.toml', 'skill-b')
+
+      db.reconcileDeckReferences('/project-a/skill-deck.toml', [])
+
+      expect(db.getReferencingDecks('github.com/owner/repo/skill')).toHaveLength(1)
+      expect(db.getReferencingDecks('github.com/owner/repo/skill')[0].deckPath).toBe('/project-b/skill-deck.toml')
+    })
+  })
+
+  describe('schema idempotency', () => {
+    it('can be re-instantiated on same file without error', () => {
+      db.close()
+      const db2 = new MetadataDB(dbPath)
+      db2.recordRepoRef('github.com', 'test', 'repo', 'abc123')
+      expect(db2.getRepoRef('github.com', 'test', 'repo')).toBe('abc123')
+      db2.close()
+    })
+  })
+})

package/src/metadata-db.ts

@@ -0,0 +1,236 @@
+/**
+ * Cold-pool metadata layer — SQLite-backed.
+ *
+ * Per ADR-20260507143241493: git-native hash, local-only trust, SQLite storage.
+ *
+ * Three tables:
+ *   repos        — per-repo HEAD ref tracking
+ *   skills       — per-skill content hash (git blob hash of SKILL.md)
+ *   deck_refs    — cross-deck reference index
+ */
+
+import { Database } from 'bun:sqlite'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export interface RepoRef {
+  host: string
+  owner: string
+  repo: string
+  headRef: string
+  lastPulledAt: string
+}
+
+export interface SkillHash {
+  host: string
+  owner: string
+  repo: string
+  skillSubpath: string
+  contentGitHash: string
+  headRefAtRecord: string
+  lastSeenAt: string
+}
+
+export interface DeckReference {
+  skillLocator: string
+  deckPath: string
+  declaredAlias: string | null
+}
+
+export class MetadataDB {
+  private dbPath: string
+  private _db: Database | null = null
+
+  constructor(dbPath: string) {
+    this.dbPath = dbPath
+  }
+
+  /** Lazy-open: first DB access triggers creation. Allows ColdPool
+   *  to be instantiated with read-only / non-existent paths (e.g. test
+   *  fixtures) without failing on construction. */
+  private get db(): Database {
+    if (this._db == null) {
+      try {
+        mkdirSync(dirname(this.dbPath), { recursive: true })
+      } catch {
+        // Parent dir may be read-only (e.g. test paths like /cold).
+        // SQLite { create: true } will fail below with a clearer error.
+      }
+      this._db = new Database(this.dbPath, { create: true })
+      this.initSchema()
+    }
+    return this._db
+  }
+
+  private initSchema(): void {
+    this.exec(`
+      CREATE TABLE IF NOT EXISTS repos (
+        host TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        head_ref TEXT,
+        last_pulled_at TEXT,
+        PRIMARY KEY (host, owner, repo)
+      )
+    `)
+
+    this.exec(`
+      CREATE TABLE IF NOT EXISTS skills (
+        host TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        repo TEXT NOT NULL,
+        skill_subpath TEXT NOT NULL DEFAULT '',
+        content_sha256 TEXT,
+        git_blob_hash TEXT,
+        head_ref_at_record TEXT,
+        last_seen_at TEXT,
+        PRIMARY KEY (host, owner, repo, skill_subpath)
+      )
+    `)
+
+    this.exec(`
+      CREATE TABLE IF NOT EXISTS deck_refs (
+        skill_locator TEXT NOT NULL,
+        deck_path TEXT NOT NULL,
+        declared_alias TEXT,
+        PRIMARY KEY (skill_locator, deck_path)
+      )
+    `)
+
+    this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_deck ON deck_refs(deck_path)`)
+    this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_locator ON deck_refs(skill_locator)`)
+    this.exec(`CREATE INDEX IF NOT EXISTS idx_skills_repo ON skills(host, owner, repo)`)
+  }
+
+  // ── Small db util wrappers (no ORM, just DRY) ────────────────
+
+  /** Execute a statement that returns no rows. Auto-finalize. */
+  private exec(sql: string, params?: Record<string, unknown>): void {
+    const stmt = this.db.query(sql)
+    stmt.run(params ?? {})
+    stmt.finalize()
+  }
+
+  /** Query zero or one row. */
+  private queryOne<T>(sql: string, params?: Record<string, unknown>): T | null {
+    return this.db.query(sql).get(params ?? {}) as T | null
+  }
+
+  /** Query many rows. */
+  private queryAll<T>(sql: string, params?: Record<string, unknown>): T[] {
+    return this.db.query(sql).all(params ?? {}) as T[]
+  }
+
+  private now(): string {
+    return new Date().toISOString()
+  }
+
+  // ── Repo ─────────────────────────────────────────────────────
+
+  recordRepoRef(host: string, owner: string, repo: string, headRef: string): void {
+    this.exec(
+      `INSERT OR REPLACE INTO repos (host, owner, repo, head_ref, last_pulled_at)
+       VALUES ($host, $owner, $repo, $headRef, $now)`,
+      { $host: host, $owner: owner, $repo: repo, $headRef: headRef, $now: this.now() },
+    )
+  }
+
+  getRepoRef(host: string, owner: string, repo: string): string | null {
+    const row = this.queryOne<{ head_ref: string }>(
+      `SELECT head_ref FROM repos WHERE host = $host AND owner = $owner AND repo = $repo`,
+      { $host: host, $owner: owner, $repo: repo },
+    )
+    return row?.head_ref ?? null
+  }
+
+  // ── Skill ────────────────────────────────────────────────────
+
+  recordSkillHash(
+    host: string,
+    owner: string,
+    repo: string,
+    skillSubpath: string,
+    contentSha256: string,
+    gitBlobHash: string | null,
+    headRefAtRecord: string,
+  ): void {
+    this.exec(
+      `INSERT OR REPLACE INTO skills
+         (host, owner, repo, skill_subpath, content_sha256, git_blob_hash, head_ref_at_record, last_seen_at)
+       VALUES ($host, $owner, $repo, $subpath, $sha256, $blob, $headRef, $now)`,
+      {
+        $host: host,
+        $owner: owner,
+        $repo: repo,
+        $subpath: skillSubpath,
+        $sha256: contentSha256,
+        $blob: gitBlobHash,
+        $headRef: headRefAtRecord,
+        $now: this.now(),
+      },
+    )
+  }
+
+  getSkillHash(host: string, owner: string, repo: string, skillSubpath: string): string | null {
+    const row = this.queryOne<{ content_sha256: string }>(
+      `SELECT content_sha256 FROM skills
+       WHERE host = $host AND owner = $owner AND repo = $repo AND skill_subpath = $subpath`,
+      { $host: host, $owner: owner, $repo: repo, $subpath: skillSubpath },
+    )
+    return row?.content_sha256 ?? null
+  }
+
+  // ── Deck References ──────────────────────────────────────────
+
+  addReference(skillLocator: string, deckPath: string, declaredAlias: string | null): void {
+    this.exec(
+      `INSERT OR REPLACE INTO deck_refs (skill_locator, deck_path, declared_alias)
+       VALUES ($locator, $deck, $alias)`,
+      { $locator: skillLocator, $deck: deckPath, $alias: declaredAlias },
+    )
+  }
+
+  removeReference(skillLocator: string, deckPath: string): void {
+    this.exec(
+      `DELETE FROM deck_refs WHERE skill_locator = $locator AND deck_path = $deck`,
+      { $locator: skillLocator, $deck: deckPath },
+    )
+  }
+
+  removeAllReferencesForDeck(deckPath: string): void {
+    this.exec(`DELETE FROM deck_refs WHERE deck_path = $deck`, { $deck: deckPath })
+  }
+
+  getReferencingDecks(skillLocator: string): Array<{ deckPath: string; alias: string | null }> {
+    const rows = this.queryAll<{ deck_path: string; declared_alias: string | null }>(
+      `SELECT deck_path, declared_alias FROM deck_refs WHERE skill_locator = $locator`,
+      { $locator: skillLocator },
+    )
+    return rows.map((r) => ({ deckPath: r.deck_path, alias: r.declared_alias }))
+  }
+
+  // ── Reconcile ────────────────────────────────────────────────
+
+  reconcileDeckReferences(
+    deckPath: string,
+    declaredSkills: Array<{ locator: string; alias: string | null }>,
+  ): void {
+    this.db.transaction(() => {
+      this.exec(`DELETE FROM deck_refs WHERE deck_path = $deck`, { $deck: deckPath })
+
+      const insert = this.db.query(`
+        INSERT INTO deck_refs (skill_locator, deck_path, declared_alias)
+        VALUES ($locator, $deck, $alias)
+      `)
+      for (const skill of declaredSkills) {
+        insert.run({ $locator: skill.locator, $deck: deckPath, $alias: skill.alias })
+      }
+      insert.finalize()
+    })()
+  }
+
+  close(): void {
+    this._db?.close()
+    this._db = null
+  }
+}