@lythos/cold-pool 0.9.31 → 0.9.32

package/README.md

@@ -2,7 +2,7 @@
 
 Cold pool service layer for the lythoskill ecosystem.
 
-> Status: scaffold (0.9.x). Public API will stabilize at 0.10.0.
+> Status: 0.9.32 — public API. Reconciliation (reconcile plan) is functional; execute convergence WIP.
 
 ## What this is
 
@@ -16,12 +16,14 @@ deck / curator / arena consume it instead of running `git clone` themselves.
 Three layers, sharing the project's `intent → plan → execute` pattern
 (`cortex/wiki/01-patterns/2026-05-04-intent-plan-execute-fractal-architecture-pattern.md`):
 
-- **Resource layer** — `ColdPool` class holds path, metadata index, reconcile
-  entry. Read-only accessors.
+- **Resource layer** — `ColdPool` class holds path, metadata index (MetadataDB),
+  reconcile entry. Read-only accessors: `resolveDir()`, `has()`, `list()`.
 - **Plan layer** — `buildFetchPlan(coldPool, locator) → FetchPlan`,
-  `buildValidationPlan(coldPool, locator) → ValidationReport`. Pure data,
+  `buildValidationPlan(coldPool, locator) → ValidationReport`,
+  `buildReconcilePlan(coldPool, desired) → ReconcilePlan`. Pure data,
   no side effects, dry-run printable.
-- **Execute layer** — `executeFetchPlan(plan, io: FetchIO)`. IO is
+- **Execute layer** — `executeFetchPlan(plan, io: FetchIO)`,
+  `executeReconcilePlan(plan, io: ReconcileIO)`. IO is
   injectable; defaults to real git operations. Tests swap mocks.
 
 ## Locator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.31",
+  "version": "0.9.32",
   "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",

package/src/index.ts

@@ -38,3 +38,13 @@ export { gitClone, gitPull, detectGitRoot } from './git-io.js'
 export { buildFetchPlan, executeFetchPlan } from './fetch-plan.js'
 
 export { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'
+
+export type {
+  DesiredSkill,
+  ReconcileDesiredState,
+  ReconcileEntry,
+  ReconcilePlan,
+  ReconcileResult,
+  ReconcileIO,
+} from './reconcile-plan.js'
+export { buildReconcilePlan, executeReconcilePlan } from './reconcile-plan.js'

package/src/reconcile-plan.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test'
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ColdPool } from './cold-pool'
+import { buildReconcilePlan, executeReconcilePlan, type ReconcileDesiredState } from './reconcile-plan'
+
+function makePool(): { root: string; pool: ColdPool } {
+  const root = mkdtempSync(join(tmpdir(), 'reconcile-test-'))
+  const pool = new ColdPool(root)
+  return { root, pool }
+}
+
+function seedRepo(root: string, host: string, owner: string, repo: string) {
+  const dir = join(root, host, owner, repo)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'SKILL.md'), '# Test Skill')
+  // Seed metadata with a fake HEAD ref
+  return dir
+}
+
+describe('buildReconcilePlan — pure classification', () => {
+  let root: string
+  let pool: ColdPool
+
+  beforeEach(() => {
+    const p = makePool()
+    root = p.root
+    pool = p.pool
+  })
+
+  afterEach(() => {
+    pool.metadata.close()
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  test('empty desired + empty cold pool → all empty', () => {
+    const desired: ReconcileDesiredState = { deckPath: '/project/skill-deck.toml', skills: [] }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing).toEqual([])
+    expect(plan.behind).toEqual([])
+    expect(plan.extra).toEqual([])
+  })
+
+  test('desired skill missing from cold pool → reported as missing', () => {
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'github.com/lythos-labs/tdd', alias: 'tdd' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing.length).toBe(1)
+    expect(plan.missing[0].host).toBe('github.com')
+    expect(plan.missing[0].owner).toBe('lythos-labs')
+    expect(plan.missing[0].repo).toBe('tdd')
+    expect(plan.missing[0].aliases).toEqual(['tdd'])
+    expect(plan.behind).toEqual([])
+    expect(plan.extra).toEqual([])
+  })
+
+  test('desired skill exists in cold pool with metadata → reported as behind', () => {
+    seedRepo(root, 'github.com', 'owner', 'repo-a')
+    pool.metadata.recordRepoRef('github.com', 'owner', 'repo-a', 'abc123def')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'github.com/owner/repo-a', alias: 'skill-a' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing).toEqual([])
+    expect(plan.behind.length).toBe(1)
+    expect(plan.behind[0].repo).toBe('repo-a')
+    expect(plan.behind[0].reason).toContain('abc123d')
+    expect(plan.extra).toEqual([])
+  })
+
+  test('desired skill exists but no metadata → not flagged (manual clone)', () => {
+    seedRepo(root, 'github.com', 'owner', 'repo-b')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'github.com/owner/repo-b', alias: 'skill-b' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing).toEqual([])
+    expect(plan.behind).toEqual([])
+    expect(plan.extra).toEqual([])
+  })
+
+  test('monorepo skill path → extracts correct repo root', () => {
+    seedRepo(root, 'github.com', 'owner', 'monorepo')
+    pool.metadata.recordRepoRef('github.com', 'owner', 'monorepo', 'def456')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'github.com/owner/monorepo/skills/foo', alias: 'foo' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing).toEqual([])
+    expect(plan.behind.length).toBe(1)
+    expect(plan.behind[0].repo).toBe('monorepo')
+  })
+
+  test('extra repo in cold pool not in desired → reported as extra', () => {
+    seedRepo(root, 'github.com', 'someone', 'orphan-repo')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'github.com/owner/repo-a', alias: 'a' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing.length).toBe(1) // repo-a is missing
+    expect(plan.extra.length).toBe(1)
+    expect(plan.extra[0].repo).toBe('orphan-repo')
+  })
+
+  test('multiple skills in same repo → single repo entry', () => {
+    seedRepo(root, 'github.com', 'owner', 'shared-repo')
+    pool.metadata.recordRepoRef('github.com', 'owner', 'shared-repo', 'ghi789')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [
+        { locator: 'github.com/owner/shared-repo/skills/a', alias: 'alpha' },
+        { locator: 'github.com/owner/shared-repo/skills/b', alias: 'beta' },
+      ],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing).toEqual([])
+    expect(plan.behind.length).toBe(1)
+    expect(plan.behind[0].aliases).toEqual(['alpha', 'beta'])
+  })
+
+  test('localhost skill in desired, exists in pool', () => {
+    seedRepo(root, 'localhost', 'me', 'local-skill')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'localhost/me/local-skill', alias: 'local' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    // localhost: metadata not auto-recorded (user-managed), so no behind
+    expect(plan.missing).toEqual([])
+    expect(plan.behind).toEqual([])
+    expect(plan.extra).toEqual([])
+  })
+
+  test('unrecognized locator format → reported as missing', () => {
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [{ locator: 'bare-name', alias: 'bare' }],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+    expect(plan.missing.length).toBe(1)
+    expect(plan.missing[0].reason).toContain('Unrecognized')
+  })
+
+  test('mixed: missing + behind + extra all populated', () => {
+    // Seed two repos that exist
+    seedRepo(root, 'github.com', 'owner', 'exists-behind')
+    pool.metadata.recordRepoRef('github.com', 'owner', 'exists-behind', 'abc')
+    seedRepo(root, 'github.com', 'owner', 'exists-clean')
+
+    // Seed an orphan
+    seedRepo(root, 'github.com', 'someone', 'orphan')
+
+    const desired: ReconcileDesiredState = {
+      deckPath: '/project/skill-deck.toml',
+      skills: [
+        { locator: 'github.com/owner/exists-behind', alias: 'behind' },
+        { locator: 'github.com/owner/exists-clean', alias: 'clean' },
+        { locator: 'github.com/owner/missing-repo', alias: 'missing' },
+      ],
+    }
+    const plan = buildReconcilePlan(pool, desired)
+
+    expect(plan.missing.length).toBe(1)
+    expect(plan.missing[0].repo).toBe('missing-repo')
+
+    expect(plan.behind.length).toBe(1)
+    expect(plan.behind[0].repo).toBe('exists-behind')
+
+    expect(plan.extra.length).toBe(1)
+    expect(plan.extra[0].repo).toBe('orphan')
+  })
+})
+
+describe('executeReconcilePlan — plan-first reporting', () => {
+  test('empty plan → all zero count', () => {
+    const results = executeReconcilePlan({ missing: [], behind: [], extra: [] })
+    expect(results).toEqual([])
+  })
+
+  test('missing entry → failed status', () => {
+    const plan = {
+      missing: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/pool/github.com/o/r', reason: 'Not found', aliases: ['r'] }],
+      behind: [],
+      extra: [],
+    }
+    const results = executeReconcilePlan(plan)
+    expect(results.length).toBe(1)
+    expect(results[0].status).toBe('failed')
+  })
+
+  test('behind entry → skipped status', () => {
+    const plan = {
+      missing: [],
+      behind: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/pool/github.com/o/r', reason: 'HEAD mismatch', aliases: ['r'] }],
+      extra: [],
+    }
+    const results = executeReconcilePlan(plan)
+    expect(results[0].status).toBe('skipped')
+  })
+
+  test('extra entry → extra-reported status', () => {
+    const plan = {
+      missing: [],
+      behind: [],
+      extra: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/pool/github.com/o/r', reason: 'Orphan', aliases: [] }],
+    }
+    const results = executeReconcilePlan(plan)
+    expect(results[0].status).toBe('extra-reported')
+  })
+
+  test('io.log captures output', () => {
+    const lines: string[] = []
+    const plan = {
+      missing: [{ host: 'github.com', owner: 'o', repo: 'r', repoPath: '/p/github.com/o/r', reason: 'X', aliases: ['r'] }],
+      behind: [],
+      extra: [],
+    }
+    executeReconcilePlan(plan, { log: (m) => lines.push(m) })
+    const report = lines.join('\n')
+    expect(report).toContain('Missing: 1')
+    expect(report).toContain('❌ Missing')
+  })
+})

package/src/reconcile-plan.ts

@@ -0,0 +1,217 @@
+/**
+ * Reconcile plan: k8s-style desired vs actual convergence.
+ *
+ * Per ADR-20260507021957847 and EPIC-20260507191713917.
+ * Plan builders are pure (read-only, no mutation). Executors inject IO.
+ */
+
+import { existsSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import type { ColdPool } from './cold-pool.js'
+import { parseLocator } from './parse-locator.js'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface DesiredSkill {
+  locator: string
+  alias: string
+}
+
+export interface ReconcileDesiredState {
+  deckPath: string
+  skills: DesiredSkill[]
+}
+
+export interface ReconcileEntry {
+  host: string
+  owner: string
+  repo: string
+  repoPath: string
+  reason: string
+  /** The affected skill aliases, if any. */
+  aliases: string[]
+}
+
+export interface ReconcilePlan {
+  /** Skills whose repo dir doesn't exist in the cold pool. */
+  missing: ReconcileEntry[]
+  /** Skills whose repo exists but git HEAD doesn't match the metadata record. */
+  behind: ReconcileEntry[]
+  /** Repos in the cold pool not referenced by any skill in the desired state. */
+  extra: ReconcileEntry[]
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+interface RepoKey {
+  host: string
+  owner: string
+  repo: string
+}
+
+function repoKey(host: string, owner: string, repo: string): string {
+  return `${host}/${owner}/${repo}`
+}
+
+/**
+ * Extract (host, owner, repo) from a source path relative to cold-pool root.
+ * Uses parseLocator — the source path is an FQ locator whose first 3 segments
+ * give the canonical repo directory.
+ */
+function extractRepo(source: string): RepoKey | null {
+  const loc = parseLocator(source)
+  if (!loc) return null
+  return { host: loc.host, owner: loc.owner, repo: loc.repo }
+}
+
+// ── Plan builder ───────────────────────────────────────────────────────────
+
+export function buildReconcilePlan(
+  coldPool: ColdPool,
+  desired: ReconcileDesiredState,
+): ReconcilePlan {
+  // 1. Index desired skills by repo
+  const desiredRepos = new Map<string, { key: RepoKey; aliases: string[] }>()
+  const unrecognized: ReconcileEntry[] = []
+
+  for (const skill of desired.skills) {
+    const repo = extractRepo(skill.locator)
+    if (!repo) {
+      unrecognized.push({
+        host: '', owner: '', repo: skill.locator, repoPath: '',
+        reason: `Unrecognized locator format: "${skill.locator}"`,
+        aliases: [skill.alias],
+      })
+      continue
+    }
+    const k = repoKey(repo.host, repo.owner, repo.repo)
+    const existing = desiredRepos.get(k)
+    if (existing) {
+      existing.aliases.push(skill.alias)
+    } else {
+      desiredRepos.set(k, { key: repo, aliases: [skill.alias] })
+    }
+  }
+
+  // 2. Enumerate cold pool actual state
+  const coldPoolDirs = coldPool.list() // absolute paths
+  const coldPoolRepos = new Map<string, string>() // repoKey → absolute path
+  for (const dir of coldPoolDirs) {
+    const rel = relative(coldPool.path, dir)
+    const parts = rel.split('/')
+    if (parts.length >= 3) {
+      const k = repoKey(parts[0], parts[1], parts[2])
+      coldPoolRepos.set(k, dir)
+    }
+  }
+
+  // 3. Compare: missing + behind
+  const missing: ReconcileEntry[] = [...unrecognized]
+  const behind: ReconcileEntry[] = []
+
+  for (const [k, { key, aliases }] of desiredRepos) {
+    const dir = coldPoolRepos.get(k)
+    if (!dir || !existsSync(dir)) {
+      missing.push({
+        host: key.host, owner: key.owner, repo: key.repo,
+        repoPath: coldPool.resolveDir({ raw: '', host: key.host, owner: key.owner, repo: key.repo, skill: null, isLocalhost: key.host === 'localhost' }),
+        reason: 'Repo directory not found in cold pool',
+        aliases,
+      })
+      continue
+    }
+
+    // Check metadata DB for recorded HEAD ref
+    const recordedRef = coldPool.metadata.getRepoRef(key.host, key.owner, key.repo)
+    if (recordedRef) {
+      // Metadata has a record — repo was previously fetched via deck add.
+      // We can't check current HEAD here because that requires async git ops.
+      // Mark as "needs verification" — the async executor will check.
+      behind.push({
+        host: key.host, owner: key.owner, repo: key.repo,
+        repoPath: dir,
+        reason: `Recorded HEAD: ${recordedRef.slice(0, 8)} — verify against current`,
+        aliases,
+      })
+    }
+    // If no metadata record, the repo exists but wasn't recorded via deck add.
+    // This is fine (e.g. manually cloned). Don't flag.
+  }
+
+  // 4. Compare: extra (in cold pool but not referenced by desired state)
+  const extra: ReconcileEntry[] = []
+  for (const [k, dir] of coldPoolRepos) {
+    if (!desiredRepos.has(k)) {
+      const parts = k.split('/')
+      extra.push({
+        host: parts[0], owner: parts[1], repo: parts[2],
+        repoPath: dir,
+        reason: 'Not referenced by any skill in the desired state',
+        aliases: [],
+      })
+    }
+  }
+
+  return { missing, behind, extra }
+}
+
+// ── Execution (IO layer, injectable for testing) ───────────────────────────
+
+export interface ReconcileResult {
+  host: string
+  owner: string
+  repo: string
+  status: 'restored' | 'updated' | 'skipped' | 'failed' | 'extra-reported'
+  message: string
+}
+
+export interface ReconcileIO {
+  gitClone?: (url: string, dir: string, opts?: { depth?: number }) => void
+  log?: (msg: string) => void
+}
+
+export function executeReconcilePlan(
+  plan: ReconcilePlan,
+  _io?: ReconcileIO,
+): ReconcileResult[] {
+  const log = _io?.log ?? (() => {})
+  const results: ReconcileResult[] = []
+
+  // Report phase — plan-first: show what would happen
+  log('\n🔍 Reconcile Plan')
+  log(`   Missing: ${plan.missing.length} | Behind: ${plan.behind.length} | Extra: ${plan.extra.length}`)
+
+  for (const entry of plan.missing) {
+    const repo = `${entry.host}/${entry.owner}/${entry.repo}`
+    log(`   ❌ Missing: ${repo} — ${entry.reason}`)
+    log(`      Affected: ${entry.aliases.join(', ')}`)
+    results.push({
+      host: entry.host, owner: entry.owner, repo: entry.repo,
+      status: 'failed',
+      message: `Missing: ${entry.reason}`,
+    })
+  }
+
+  for (const entry of plan.behind) {
+    const repo = `${entry.host}/${entry.owner}/${entry.repo}`
+    log(`   ⚠️  Behind: ${repo}`)
+    log(`      ${entry.reason}`)
+    results.push({
+      host: entry.host, owner: entry.owner, repo: entry.repo,
+      status: 'skipped',
+      message: entry.reason,
+    })
+  }
+
+  for (const entry of plan.extra) {
+    const repo = `${entry.host}/${entry.owner}/${entry.repo}`
+    log(`   📦 Extra: ${repo} — ${entry.reason}`)
+    results.push({
+      host: entry.host, owner: entry.owner, repo: entry.repo,
+      status: 'extra-reported',
+      message: entry.reason,
+    })
+  }
+
+  return results
+}