@holoscript/framework 6.0.3

package/src/__tests__/distributed-claimer.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { DistributedClaimer } from '../distributed-claimer';
+import { MeshDiscovery, GossipProtocol } from '../mesh';
+import type { GossipPacket } from '../mesh';
+
+describe('DistributedClaimer', () => {
+  let mesh: MeshDiscovery;
+  let gossip: GossipProtocol;
+  let claimer: DistributedClaimer;
+
+  beforeEach(() => {
+    mesh = new MeshDiscovery('node-1');
+    gossip = new GossipProtocol();
+    claimer = new DistributedClaimer(mesh, gossip, { claimTtlMs: 5000 });
+  });
+
+  it('claims an unclaimed task', () => {
+    const result = claimer.claim('task-1', 'agent-a');
+    expect(result.success).toBe(true);
+    expect(result.claimedBy).toBe('agent-a');
+    expect(result.taskId).toBe('task-1');
+  });
+
+  it('allows the same agent to re-claim (refresh)', () => {
+    claimer.claim('task-1', 'agent-a');
+    const result = claimer.claim('task-1', 'agent-a');
+    expect(result.success).toBe(true);
+    expect(result.claimedBy).toBe('agent-a');
+  });
+
+  it('rejects lower-priority agent on conflict', () => {
+    claimer.claim('task-1', 'agent-a', 3);
+    const result = claimer.claim('task-1', 'agent-b', 5); // higher number = lower priority
+    expect(result.success).toBe(false);
+    expect(result.claimedBy).toBe('agent-a');
+  });
+
+  it('higher-priority agent wins conflict', () => {
+    claimer.claim('task-1', 'agent-a', 5);
+    const result = claimer.claim('task-1', 'agent-b', 2); // lower number = higher priority
+    expect(result.success).toBe(true);
+    expect(result.claimedBy).toBe('agent-b');
+    expect(result.contested).toEqual(['agent-a']);
+  });
+
+  it('releases a claim', () => {
+    claimer.claim('task-1', 'agent-a');
+    const released = claimer.release('task-1', 'agent-a');
+    expect(released).toBe(true);
+    expect(claimer.getClaimHolder('task-1')).toBeUndefined();
+  });
+
+  it('cannot release another agent claim', () => {
+    claimer.claim('task-1', 'agent-a');
+    const released = claimer.release('task-1', 'agent-b');
+    expect(released).toBe(false);
+    expect(claimer.getClaimHolder('task-1')?.agentId).toBe('agent-a');
+  });
+
+  it('confirms a claim (extends TTL)', () => {
+    claimer.claim('task-1', 'agent-a');
+    const confirmed = claimer.confirm('task-1', 'agent-a');
+    expect(confirmed).toBe(true);
+    const record = claimer.getClaimHolder('task-1');
+    expect(record).toBeDefined();
+    // Confirmed claims have extended TTL (10x)
+    expect(record!.expiresAt).toBeGreaterThan(Date.now() + 40_000);
+  });
+
+  it('tracks multiple active claims', () => {
+    claimer.claim('task-1', 'agent-a');
+    claimer.claim('task-2', 'agent-b');
+    claimer.claim('task-3', 'agent-a');
+    const active = claimer.getActiveClaims();
+    expect(active).toHaveLength(3);
+  });
+
+  it('broadcasts claims via gossip', () => {
+    claimer.claim('task-1', 'agent-a');
+    expect(gossip.getPoolSize()).toBeGreaterThan(0);
+  });
+
+  it('ingests gossip claim packets', () => {
+    // Simulate a remote claim arriving via gossip
+    const packet: GossipPacket = {
+      id: 'pkt-remote-1',
+      source: 'claimer:node-2',
+      version: 1,
+      payload: {
+        type: 'claim',
+        record: {
+          taskId: 'task-remote',
+          agentId: 'remote-agent',
+          timestamp: Date.now() * 1000,
+          priority: 3,
+          expiresAt: Date.now() + 30_000,
+        },
+      },
+      timestamp: Date.now(),
+    };
+
+    claimer.ingestGossip(packet);
+    const holder = claimer.getClaimHolder('task-remote');
+    expect(holder).toBeDefined();
+    expect(holder!.agentId).toBe('remote-agent');
+  });
+
+  it('ingests gossip release packets', () => {
+    claimer.claim('task-1', 'agent-a');
+
+    const record = claimer.getClaimHolder('task-1')!;
+    const packet: GossipPacket = {
+      id: 'pkt-release',
+      source: 'claimer:node-2',
+      version: 1,
+      payload: { type: 'release', record },
+      timestamp: Date.now(),
+    };
+
+    claimer.ingestGossip(packet);
+    expect(claimer.getClaimHolder('task-1')).toBeUndefined();
+  });
+
+  it('resolves gossip conflicts by priority', () => {
+    claimer.claim('task-1', 'agent-a', 5);
+
+    const packet: GossipPacket = {
+      id: 'pkt-conflict',
+      source: 'claimer:node-2',
+      version: 1,
+      payload: {
+        type: 'claim',
+        record: {
+          taskId: 'task-1',
+          agentId: 'agent-remote',
+          timestamp: Date.now() * 1000,
+          priority: 2, // Higher priority (lower number)
+          expiresAt: Date.now() + 30_000,
+        },
+      },
+      timestamp: Date.now(),
+    };
+
+    claimer.ingestGossip(packet);
+    expect(claimer.getClaimHolder('task-1')?.agentId).toBe('agent-remote');
+  });
+});

package/src/__tests__/done-log-audit.test.ts

@@ -0,0 +1,342 @@
+/**
+ * DoneLogAuditor tests (FW-0.3)
+ *
+ * Tests the done-log audit logic: violations, stats, and Team.audit() integration.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import {
+  DoneLogAuditor,
+  auditDoneLog,
+  isLikelyReportEntry,
+  isCommitProof,
+} from '../board/audit';
+import type { DoneLogEntry } from '../board/board-types';
+import { Team } from '../team';
+
+// ── Helpers ──
+
+function makeEntry(overrides: Partial<DoneLogEntry> = {}): DoneLogEntry {
+  return {
+    taskId: `task_${Math.random().toString(36).slice(2, 6)}`,
+    title: 'Fix the widget',
+    completedBy: 'agent-a',
+    commitHash: 'abc1234',
+    timestamp: '2026-04-05T10:00:00Z',
+    summary: 'Fixed the widget by refactoring X',
+    ...overrides,
+  };
+}
+
+// ── isLikelyReportEntry ──
+
+describe('isLikelyReportEntry', () => {
+  it('detects [report] prefix in title', () => {
+    expect(isLikelyReportEntry({ title: '[report] Session summary' })).toBe(true);
+  });
+
+  it('detects "session end" prefix in summary', () => {
+    expect(isLikelyReportEntry({ summary: 'session end — 5 tasks done' })).toBe(true);
+  });
+
+  it('returns false for normal entries', () => {
+    expect(isLikelyReportEntry({ title: 'Fix bug', summary: 'Refactored code' })).toBe(false);
+  });
+});
+
+// ── isCommitProof ──
+
+describe('isCommitProof', () => {
+  it('accepts valid short hash', () => {
+    expect(isCommitProof('abc1234')).toBe(true);
+  });
+
+  it('accepts valid full hash', () => {
+    expect(isCommitProof('abc1234567890abc1234567890abc1234567890a')).toBe(true);
+  });
+
+  it('rejects undefined', () => {
+    expect(isCommitProof(undefined)).toBe(false);
+  });
+
+  it('rejects empty string', () => {
+    expect(isCommitProof('')).toBe(false);
+  });
+
+  it('rejects "none"', () => {
+    expect(isCommitProof('none')).toBe(false);
+  });
+
+  it('rejects "local-uncommitted"', () => {
+    expect(isCommitProof('local-uncommitted')).toBe(false);
+  });
+
+  it('rejects non-hex strings', () => {
+    expect(isCommitProof('not-a-hash!')).toBe(false);
+  });
+});
+
+// ── auditDoneLog (backward compat) ──
+
+describe('auditDoneLog', () => {
+  it('returns 100% verification for empty log', () => {
+    const result = auditDoneLog([]);
+    expect(result.total).toBe(0);
+    expect(result.health.verificationRate).toBe(100);
+  });
+
+  it('counts verified and unverified', () => {
+    const entries = [
+      makeEntry({ commitHash: 'abc1234' }),
+      makeEntry({ commitHash: undefined }),
+    ];
+    const result = auditDoneLog(entries);
+    expect(result.verified).toBe(1);
+    expect(result.unverified).toBe(1);
+    expect(result.health.verificationRate).toBe(50);
+  });
+
+  it('detects duplicate titles', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', title: 'Same title' }),
+      makeEntry({ taskId: 't2', title: 'Same title' }),
+    ];
+    const result = auditDoneLog(entries);
+    expect(result.duplicates).toBe(1);
+    expect(result.duplicateTasks[0].title).toBe('Same title');
+    expect(result.duplicateTasks[0].count).toBe(2);
+  });
+
+  it('excludes report entries from proof requirement', () => {
+    const entries = [
+      makeEntry({ title: '[report] Session end', commitHash: undefined }),
+      makeEntry({ commitHash: 'abc1234' }),
+    ];
+    const result = auditDoneLog(entries);
+    expect(result.nonProofEntries).toBe(1);
+    expect(result.proofRequiredTotal).toBe(1);
+    expect(result.health.verificationRate).toBe(100);
+  });
+});
+
+// ── DoneLogAuditor.audit() ──
+
+describe('DoneLogAuditor.audit()', () => {
+  it('returns no violations for well-formed entries', () => {
+    const entries = [
+      makeEntry({ timestamp: '2026-04-05T10:00:00Z' }),
+      makeEntry({ timestamp: '2026-04-05T11:00:00Z' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations).toHaveLength(0);
+  });
+
+  it('detects missing completedBy', () => {
+    const entries = [makeEntry({ completedBy: '' })];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations.some(v => v.rule === 'missing-completedBy')).toBe(true);
+  });
+
+  it('detects missing summary', () => {
+    const entries = [makeEntry({ summary: '' })];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations.some(v => v.rule === 'missing-summary')).toBe(true);
+  });
+
+  it('detects missing commit proof', () => {
+    const entries = [makeEntry({ commitHash: undefined })];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations.some(v => v.rule === 'missing-commit')).toBe(true);
+  });
+
+  it('detects duplicate taskId entries', () => {
+    const entries = [
+      makeEntry({ taskId: 'dup-1', timestamp: '2026-04-05T10:00:00Z' }),
+      makeEntry({ taskId: 'dup-1', timestamp: '2026-04-05T11:00:00Z' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations.some(v => v.rule === 'duplicate-entry')).toBe(true);
+  });
+
+  it('detects non-monotonic timestamps', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', timestamp: '2026-04-05T12:00:00Z' }),
+      makeEntry({ taskId: 't2', timestamp: '2026-04-05T10:00:00Z' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    expect(violations.some(v => v.rule === 'non-monotonic-timestamp')).toBe(true);
+  });
+
+  it('skips report entries from field checks', () => {
+    const entries = [
+      makeEntry({ title: '[report] Session summary', commitHash: undefined, summary: '' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const violations = auditor.audit();
+    // Report entries should not trigger missing-commit or missing-summary
+    expect(violations).toHaveLength(0);
+  });
+});
+
+// ── DoneLogAuditor.stats() ──
+
+describe('DoneLogAuditor.stats()', () => {
+  it('returns zero stats for empty log', () => {
+    const auditor = new DoneLogAuditor([]);
+    const stats = auditor.stats();
+    expect(stats.total).toBe(0);
+    expect(stats.byAgent).toHaveLength(0);
+    expect(stats.bySource).toHaveLength(0);
+    expect(stats.completionOverTime).toHaveLength(0);
+  });
+
+  it('groups by agent', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', completedBy: 'alice' }),
+      makeEntry({ taskId: 't2', completedBy: 'alice' }),
+      makeEntry({ taskId: 't3', completedBy: 'bob' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const stats = auditor.stats();
+    expect(stats.byAgent).toHaveLength(2);
+    const alice = stats.byAgent.find(a => a.agent === 'alice');
+    expect(alice?.completed).toBe(2);
+    const bob = stats.byAgent.find(a => a.agent === 'bob');
+    expect(bob?.completed).toBe(1);
+  });
+
+  it('tracks verified vs unverified per agent', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', completedBy: 'alice', commitHash: 'abc1234' }),
+      makeEntry({ taskId: 't2', completedBy: 'alice', commitHash: undefined }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const stats = auditor.stats();
+    const alice = stats.byAgent.find(a => a.agent === 'alice');
+    expect(alice?.verified).toBe(1);
+    expect(alice?.unverified).toBe(1);
+  });
+
+  it('detects synthesizer source from taskId', () => {
+    const entries = [
+      makeEntry({ taskId: 'task_synth_001' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const stats = auditor.stats();
+    expect(stats.bySource.some(s => s.source === 'synthesizer')).toBe(true);
+  });
+
+  it('groups completion over time by date', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', timestamp: '2026-04-05T10:00:00Z' }),
+      makeEntry({ taskId: 't2', timestamp: '2026-04-05T14:00:00Z' }),
+      makeEntry({ taskId: 't3', timestamp: '2026-04-06T10:00:00Z' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const stats = auditor.stats();
+    expect(stats.completionOverTime).toHaveLength(2);
+    expect(stats.completionOverTime[0]).toEqual({ date: '2026-04-05', completed: 2 });
+    expect(stats.completionOverTime[1]).toEqual({ date: '2026-04-06', completed: 1 });
+  });
+
+  it('sorts agents by completed count descending', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', completedBy: 'low' }),
+      makeEntry({ taskId: 't2', completedBy: 'high' }),
+      makeEntry({ taskId: 't3', completedBy: 'high' }),
+      makeEntry({ taskId: 't4', completedBy: 'high' }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const stats = auditor.stats();
+    expect(stats.byAgent[0].agent).toBe('high');
+    expect(stats.byAgent[1].agent).toBe('low');
+  });
+});
+
+// ── DoneLogAuditor.fullAudit() ──
+
+describe('DoneLogAuditor.fullAudit()', () => {
+  it('returns combined audit, violations, and stats', () => {
+    const entries = [
+      makeEntry({ taskId: 't1', timestamp: '2026-04-05T10:00:00Z' }),
+      makeEntry({ taskId: 't2', timestamp: '2026-04-05T11:00:00Z', commitHash: undefined }),
+    ];
+    const auditor = new DoneLogAuditor(entries);
+    const result = auditor.fullAudit();
+
+    // audit (backward compat)
+    expect(result.audit.total).toBe(2);
+    expect(result.audit.verified).toBe(1);
+    expect(result.audit.unverified).toBe(1);
+
+    // violations
+    expect(result.violations.some(v => v.rule === 'missing-commit')).toBe(true);
+
+    // stats
+    expect(result.stats.total).toBe(2);
+  });
+});
+
+// ── Team.audit() integration ──
+
+describe('Team.audit()', () => {
+  it('audits local done log (empty)', async () => {
+    const team = new Team({
+      name: 'test-team',
+      agents: [],
+    });
+    const result = await team.audit();
+    expect(result.audit.total).toBe(0);
+    expect(result.violations).toHaveLength(0);
+    expect(result.stats.total).toBe(0);
+  });
+
+  it('audits remote done log via listBoard', async () => {
+    const team = new Team({
+      name: 'remote-team',
+      agents: [],
+      boardUrl: 'https://example.com',
+      boardApiKey: 'test-key',
+    });
+
+    // Mock fetch for the remote board call
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify({
+        board: {
+          open: [],
+          claimed: [],
+          done_log: [
+            {
+              taskId: 't1',
+              title: 'Remote task',
+              completedBy: 'remote-agent',
+              commitHash: 'abcdef1',
+              timestamp: '2026-04-05T10:00:00Z',
+              summary: 'Done remotely',
+            },
+            {
+              taskId: 't2',
+              title: 'Another remote task',
+              completedBy: 'remote-agent',
+              timestamp: '2026-04-05T11:00:00Z',
+              summary: 'Also done',
+            },
+          ],
+        },
+      })),
+    );
+
+    const result = await team.audit();
+    expect(result.audit.total).toBe(2);
+    expect(result.audit.verified).toBe(1);
+    expect(result.stats.byAgent).toHaveLength(1);
+    expect(result.stats.byAgent[0].agent).toBe('remote-agent');
+
+    fetchSpy.mockRestore();
+  });
+});