@dzhechkov/harness-core 0.3.103 → 0.3.105

package/src/recall-usage.ts

@@ -0,0 +1,373 @@
+/**
+ * Pure recall-usage accounting for the dz APPLY leg.
+ *
+ * The live hook writes one JSONL event when a learned pattern is actually injected into a prompt.
+ * This module parses that append-only log, folds it into per-pattern usage stats, and compacts it
+ * into aggregate JSONL rows when it crosses a bounded size. It deliberately knows nothing about the
+ * filesystem; callers own reads/writes so the hook and statusline can keep their never-block rules.
+ *
+ * @packageDocumentation
+ */
+
+export const RECALL_USAGE_LOG_RELATIVE = '.dz/recall-usage.jsonl';
+export const RECALL_USAGE_LOG_MAX_BYTES = 1_048_576;
+export const RECALL_USAGE_COMPACT_TARGET_BYTES = Math.floor(RECALL_USAGE_LOG_MAX_BYTES * 0.75);
+
+export interface RecallUsageReadRecord {
+  readonly dzId: string;
+  readonly score: number;
+  readonly ts: string;
+}
+
+export interface RecallUsageAggregateRecord {
+  readonly kind: 'aggregate';
+  readonly dzId: string;
+  readonly reads: number;
+  readonly firstReadAt: string;
+  readonly lastReadAt: string;
+  readonly maxScore: number;
+  readonly totalScore: number;
+  readonly compactedAt: string;
+}
+
+export type RecallUsageRecord = RecallUsageReadRecord | RecallUsageAggregateRecord;
+
+export interface ParsedRecallUsageLog {
+  readonly records: readonly RecallUsageRecord[];
+  readonly validLines: number;
+  readonly invalidLines: number;
+}
+
+export interface RecallUsageStat {
+  readonly dzId: string;
+  readonly reads: number;
+  readonly firstReadAt: string;
+  readonly lastReadAt: string;
+  readonly maxScore: number;
+  readonly avgScore: number;
+}
+
+export interface RecallPatternUsageRef {
+  readonly dzId: string;
+  readonly pattern: string;
+  readonly domain?: string;
+  readonly reward?: number;
+}
+
+export interface RecallUsagePatternRow extends RecallPatternUsageRef {
+  readonly reads: number;
+  readonly firstReadAt?: string;
+  readonly lastReadAt?: string;
+  readonly maxScore?: number;
+  readonly avgScore?: number;
+}
+
+export interface RecallUsageReport {
+  readonly totalPatterns: number;
+  readonly usedPatterns: number;
+  readonly neverReadPatterns: number;
+  readonly totalReads: number;
+  readonly unknownReadPatterns: number;
+  readonly invalidLines: number;
+  readonly top: readonly RecallUsagePatternRow[];
+  readonly neverRead: readonly RecallUsagePatternRow[];
+  readonly unknown: readonly RecallUsageStat[];
+  readonly all: readonly RecallUsagePatternRow[];
+}
+
+interface Acc {
+  dzId: string;
+  reads: number;
+  firstReadAt: string;
+  firstMs: number;
+  lastReadAt: string;
+  lastMs: number;
+  maxScore: number;
+  totalScore: number;
+}
+
+export function formatRecallUsageRecord(input: {
+  readonly dzId?: unknown;
+  readonly score?: unknown;
+  readonly ts?: unknown;
+}): string | undefined {
+  const rec = normalizeReadRecord(input);
+  return rec === undefined ? undefined : `${JSON.stringify(rec)}\n`;
+}
+
+export function parseRecallUsageLog(text: string): ParsedRecallUsageLog {
+  const records: RecallUsageRecord[] = [];
+  let invalidLines = 0;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      const record = normalizeRecord(parsed);
+      if (record === undefined) {
+        invalidLines += 1;
+      } else {
+        records.push(record);
+      }
+    } catch {
+      invalidLines += 1;
+    }
+  }
+  return { records, validLines: records.length, invalidLines };
+}
+
+export function aggregateRecallUsage(records: readonly RecallUsageRecord[]): readonly RecallUsageStat[] {
+  const byId = new Map<string, Acc>();
+  for (const rec of records) {
+    if (isAggregate(rec)) {
+      mergeAggregate(byId, rec);
+    } else {
+      mergeRead(byId, rec);
+    }
+  }
+  return [...byId.values()]
+    .map((a) => ({
+      dzId: a.dzId,
+      reads: a.reads,
+      firstReadAt: a.firstReadAt,
+      lastReadAt: a.lastReadAt,
+      maxScore: a.maxScore,
+      avgScore: a.totalScore / a.reads,
+    }))
+    .sort(compareStats);
+}
+
+export function buildRecallUsageReport(
+  patterns: readonly RecallPatternUsageRef[],
+  parsed: ParsedRecallUsageLog,
+): RecallUsageReport {
+  const stats = aggregateRecallUsage(parsed.records);
+  const statsById = new Map(stats.map((s) => [s.dzId, s]));
+  const patternIds = new Set<string>();
+  const all: RecallUsagePatternRow[] = [];
+
+  for (const p of patterns) {
+    if (p.dzId.trim() === '') continue;
+    if (patternIds.has(p.dzId)) continue;
+    patternIds.add(p.dzId);
+    const stat = statsById.get(p.dzId);
+    const base = patternRef(p);
+    if (stat === undefined) {
+      all.push({ ...base, reads: 0 });
+    } else {
+      all.push({
+        ...base,
+        reads: stat.reads,
+        firstReadAt: stat.firstReadAt,
+        lastReadAt: stat.lastReadAt,
+        maxScore: stat.maxScore,
+        avgScore: stat.avgScore,
+      });
+    }
+  }
+
+  const top = all.filter((r) => r.reads > 0).sort(compareRows);
+  const neverRead = all.filter((r) => r.reads === 0).sort((a, b) => a.dzId.localeCompare(b.dzId));
+  const unknown = stats.filter((s) => !patternIds.has(s.dzId)).sort(compareStats);
+
+  return {
+    totalPatterns: all.length,
+    usedPatterns: top.length,
+    neverReadPatterns: neverRead.length,
+    totalReads: stats.reduce((sum, s) => sum + s.reads, 0),
+    unknownReadPatterns: unknown.length,
+    invalidLines: parsed.invalidLines,
+    top,
+    neverRead,
+    unknown,
+    all: all.sort(compareRows),
+  };
+}
+
+export function shouldCompactRecallUsageLogSize(
+  sizeBytes: number,
+  maxBytes: number = RECALL_USAGE_LOG_MAX_BYTES,
+): boolean {
+  return Number.isFinite(sizeBytes) && sizeBytes > validMax(maxBytes);
+}
+
+export function compactRecallUsageLog(
+  text: string,
+  opts: { readonly maxBytes?: number; readonly targetBytes?: number; readonly compactedAt?: string } = {},
+): string {
+  const maxBytes = validMax(opts.maxBytes ?? RECALL_USAGE_LOG_MAX_BYTES);
+  const targetBytes = validTarget(opts.targetBytes ?? Math.floor(maxBytes * 0.75), maxBytes);
+  const compactedAt = validTs(opts.compactedAt) ? opts.compactedAt : new Date(0).toISOString();
+  const stats = aggregateRecallUsage(parseRecallUsageLog(text).records);
+  const lines = stats.map((s) => aggregateLine(s, compactedAt));
+  let out = joinLines(lines);
+  if (byteLength(out) <= maxBytes) return out;
+
+  const kept: string[] = [];
+  let used = 0;
+  for (const line of lines) {
+    const cost = byteLength(`${line}\n`);
+    if (kept.length > 0 && used + cost > targetBytes) continue;
+    if (cost > maxBytes) continue;
+    if (used + cost <= maxBytes) {
+      kept.push(line);
+      used += cost;
+    }
+  }
+  out = joinLines(kept);
+  return byteLength(out) <= maxBytes ? out : '';
+}
+
+function normalizeRecord(value: unknown): RecallUsageRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value['kind'] === 'aggregate') return normalizeAggregateRecord(value);
+  return normalizeReadRecord(value);
+}
+
+function normalizeReadRecord(value: unknown): RecallUsageReadRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  const dzId = value['dzId'];
+  const score = value['score'];
+  const ts = value['ts'];
+  if (typeof dzId !== 'string' || dzId.trim() === '') return undefined;
+  if (typeof score !== 'number' || !Number.isFinite(score)) return undefined;
+  if (!validTs(ts)) return undefined;
+  return { dzId: dzId.trim(), score, ts };
+}
+
+function normalizeAggregateRecord(value: Record<string, unknown>): RecallUsageAggregateRecord | undefined {
+  const dzId = value['dzId'];
+  const reads = value['reads'];
+  const firstReadAt = value['firstReadAt'];
+  const lastReadAt = value['lastReadAt'];
+  const maxScore = value['maxScore'];
+  const totalScore = value['totalScore'];
+  const compactedAt = value['compactedAt'];
+  if (typeof dzId !== 'string' || dzId.trim() === '') return undefined;
+  if (typeof reads !== 'number' || !Number.isInteger(reads) || reads <= 0) return undefined;
+  if (!validTs(firstReadAt) || !validTs(lastReadAt) || !validTs(compactedAt)) return undefined;
+  if (typeof maxScore !== 'number' || !Number.isFinite(maxScore)) return undefined;
+  if (typeof totalScore !== 'number' || !Number.isFinite(totalScore)) return undefined;
+  return { kind: 'aggregate', dzId: dzId.trim(), reads, firstReadAt, lastReadAt, maxScore, totalScore, compactedAt };
+}
+
+function mergeRead(byId: Map<string, Acc>, rec: RecallUsageReadRecord): void {
+  const ms = Date.parse(rec.ts);
+  const prev = byId.get(rec.dzId);
+  if (prev === undefined) {
+    byId.set(rec.dzId, {
+      dzId: rec.dzId,
+      reads: 1,
+      firstReadAt: rec.ts,
+      firstMs: ms,
+      lastReadAt: rec.ts,
+      lastMs: ms,
+      maxScore: rec.score,
+      totalScore: rec.score,
+    });
+    return;
+  }
+  prev.reads += 1;
+  prev.totalScore += rec.score;
+  prev.maxScore = Math.max(prev.maxScore, rec.score);
+  if (ms < prev.firstMs) {
+    prev.firstMs = ms;
+    prev.firstReadAt = rec.ts;
+  }
+  if (ms >= prev.lastMs) {
+    prev.lastMs = ms;
+    prev.lastReadAt = rec.ts;
+  }
+}
+
+function mergeAggregate(byId: Map<string, Acc>, rec: RecallUsageAggregateRecord): void {
+  const firstMs = Date.parse(rec.firstReadAt);
+  const lastMs = Date.parse(rec.lastReadAt);
+  const prev = byId.get(rec.dzId);
+  if (prev === undefined) {
+    byId.set(rec.dzId, {
+      dzId: rec.dzId,
+      reads: rec.reads,
+      firstReadAt: rec.firstReadAt,
+      firstMs,
+      lastReadAt: rec.lastReadAt,
+      lastMs,
+      maxScore: rec.maxScore,
+      totalScore: rec.totalScore,
+    });
+    return;
+  }
+  prev.reads += rec.reads;
+  prev.totalScore += rec.totalScore;
+  prev.maxScore = Math.max(prev.maxScore, rec.maxScore);
+  if (firstMs < prev.firstMs) {
+    prev.firstMs = firstMs;
+    prev.firstReadAt = rec.firstReadAt;
+  }
+  if (lastMs >= prev.lastMs) {
+    prev.lastMs = lastMs;
+    prev.lastReadAt = rec.lastReadAt;
+  }
+}
+
+function aggregateLine(stat: RecallUsageStat, compactedAt: string): string {
+  const rec: RecallUsageAggregateRecord = {
+    kind: 'aggregate',
+    dzId: stat.dzId,
+    reads: stat.reads,
+    firstReadAt: stat.firstReadAt,
+    lastReadAt: stat.lastReadAt,
+    maxScore: stat.maxScore,
+    totalScore: stat.avgScore * stat.reads,
+    compactedAt,
+  };
+  return JSON.stringify(rec);
+}
+
+function patternRef(p: RecallPatternUsageRef): RecallPatternUsageRef {
+  return {
+    dzId: p.dzId,
+    pattern: p.pattern,
+    ...(p.domain !== undefined ? { domain: p.domain } : {}),
+    ...(p.reward !== undefined ? { reward: p.reward } : {}),
+  };
+}
+
+function compareStats(a: RecallUsageStat, b: RecallUsageStat): number {
+  return b.reads - a.reads || Date.parse(b.lastReadAt) - Date.parse(a.lastReadAt) || a.dzId.localeCompare(b.dzId);
+}
+
+function compareRows(a: RecallUsagePatternRow, b: RecallUsagePatternRow): number {
+  const aLast = a.lastReadAt === undefined ? 0 : Date.parse(a.lastReadAt);
+  const bLast = b.lastReadAt === undefined ? 0 : Date.parse(b.lastReadAt);
+  return b.reads - a.reads || bLast - aLast || a.dzId.localeCompare(b.dzId);
+}
+
+function isAggregate(rec: RecallUsageRecord): rec is RecallUsageAggregateRecord {
+  return 'kind' in rec && rec.kind === 'aggregate';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function validTs(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Date.parse(value));
+}
+
+function validMax(value: number): number {
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : RECALL_USAGE_LOG_MAX_BYTES;
+}
+
+function validTarget(value: number, maxBytes: number): number {
+  if (!Number.isFinite(value) || value <= 0) return Math.floor(maxBytes * 0.75);
+  return Math.min(Math.floor(value), maxBytes);
+}
+
+function joinLines(lines: readonly string[]): string {
+  return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
+}
+
+function byteLength(text: string): number {
+  return text.length;
+}

package/src/statusline.ts

@@ -19,6 +19,7 @@ import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { listBrain } from './brain.js';
+import { RECALL_USAGE_LOG_RELATIVE, aggregateRecallUsage, parseRecallUsageLog } from './recall-usage.js';
 
 /**
  * Live learning state for one in-flight `/feature-adr` run — the per-run visibility panel
@@ -49,6 +50,8 @@ export interface FeatureAdrState {
 export interface StatuslineData {
   /** Count of learned patterns in the project's unified memory store. */
   readonly patterns: number;
+  /** Count of learned patterns that the live recall hook has actually injected at least once. */
+  readonly usedPatterns?: number;
   /** Number of sources registered in the durable cross-project knowledge brain. */
   readonly brainSources: number;
   /** Hours since the last `dz consolidate` run, if a watermark is present. */
@@ -138,6 +141,18 @@ function countLearnedPatterns(projectRoot: string): number {
   return countJsonlPatternsReadonly(projectRoot);
 }
 
+function countUsedPatternsReadonly(projectRoot: string): number | undefined {
+  const path = join(projectRoot, RECALL_USAGE_LOG_RELATIVE);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = parseRecallUsageLog(readFileSync(path, 'utf-8'));
+    if (parsed.records.length === 0) return undefined;
+    return aggregateRecallUsage(parsed.records).length;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Hours since the last consolidation, or `undefined` when never consolidated / unreadable. */
 function consolidatedAgeHours(projectRoot: string, now: number): number | undefined {
   const path = consolidateWatermarkPath(projectRoot);
@@ -268,6 +283,13 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
     brainSources = 0;
   }
 
+  let usedPatterns: number | undefined;
+  try {
+    usedPatterns = countUsedPatternsReadonly(root);
+  } catch {
+    usedPatterns = undefined;
+  }
+
   const ageH = consolidatedAgeHours(root, now);
 
   // Live /feature-adr panel — attached ONLY when a fresh run is in flight (readonly, never throws).
@@ -280,6 +302,7 @@ export function statuslineData(projectRoot: string, now: number = Date.now()): S
 
   return {
     patterns,
+    ...(usedPatterns !== undefined ? { usedPatterns } : {}),
     brainSources,
     ...(ageH !== undefined ? { consolidatedAgeH: ageH } : {}),
     ...(featureAdr !== undefined ? { featureAdr } : {}),