@hiveai/core 0.10.9 → 0.12.0

package/dist/index.js

@@ -46,6 +46,14 @@ var SensorSchema = z.object({
   /** ISO timestamp of the last time this sensor matched a diff. */
   last_fired: z.string().nullable().default(null)
 });
+var ActivationSchema = z.object({
+  /** Case-insensitive substrings matched against the task text. */
+  keywords: z.array(z.string()).default([]),
+  /** Glob-ish path patterns matched against the files being edited. */
+  globs: z.array(z.string()).default([]),
+  /** Always activate (rare — for truly universal playbooks). */
+  always: z.boolean().default(false)
+});
 var IsoDateString = z.union([z.string(), z.date()]).transform((v) => v instanceof Date ? v.toISOString() : v).pipe(z.string().datetime());
 var MemoryFrontmatterSchema = z.object({
   id: z.string().min(1),
@@ -56,6 +64,8 @@ var MemoryFrontmatterSchema = z.object({
   anchor: AnchorSchema.default({ paths: [], symbols: [] }),
   /** Optional executable check derived from this memory (feedback computational layer). */
   sensor: SensorSchema.optional(),
+  /** Optional progressive-disclosure triggers — only meaningful for `type: skill`. */
+  activation: ActivationSchema.optional(),
   tags: z.array(z.string()).default([]),
   domain: z.string().optional(),
   author: z.string().optional(),
@@ -149,6 +159,7 @@ function buildFrontmatter(input) {
     expires_when: null,
     topic: input.topic,
     sensor: input.sensor,
+    activation: input.activation,
     revision_count: 0,
     related_ids: input.relatedIds ?? []
   });
@@ -583,9 +594,14 @@ function emptyUsage() {
     last_read_at: null,
     rejected_count: 0,
     last_rejected_at: null,
-    rejection_reason: null
+    rejection_reason: null,
+    applied_count: 0,
+    last_applied_at: null
   };
 }
+function normalizeUsage(stored) {
+  return { ...emptyUsage(), ...stored ?? {} };
+}
 function emptyUsageIndex() {
   return {
     version: 1,
@@ -615,13 +631,13 @@ async function saveUsageIndex(paths, index) {
   await writeFile(file, JSON.stringify(index, null, 2), "utf8");
 }
 function getUsage(index, id) {
-  return index.by_id[id] ?? emptyUsage();
+  return normalizeUsage(index.by_id[id]);
 }
 function bumpRead(index, ids) {
   if (ids.length === 0) return index;
   const now = (/* @__PURE__ */ new Date()).toISOString();
   for (const id of ids) {
-    const current = index.by_id[id] ?? emptyUsage();
+    const current = normalizeUsage(index.by_id[id]);
     index.by_id[id] = {
       ...current,
       read_count: current.read_count + 1,
@@ -631,7 +647,7 @@ function bumpRead(index, ids) {
   return index;
 }
 function recordRejection(index, id, reason) {
-  const current = index.by_id[id] ?? emptyUsage();
+  const current = normalizeUsage(index.by_id[id]);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   index.by_id[id] = {
     ...current,
@@ -641,6 +657,16 @@ function recordRejection(index, id, reason) {
   };
   return index;
 }
+function recordApplied(index, id) {
+  const current = normalizeUsage(index.by_id[id]);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  index.by_id[id] = {
+    ...current,
+    applied_count: current.applied_count + 1,
+    last_applied_at: now
+  };
+  return index;
+}
 var DECAY_DAYS = 90;
 function isDecaying(usage, createdAt) {
   const threshold = Date.now() - DECAY_DAYS * 24 * 60 * 60 * 1e3;
@@ -657,6 +683,206 @@ async function trackReads(paths, ids) {
   return index;
 }
 
+// src/impact.ts
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+var DEFAULT_DORMANT_DAYS = 120;
+var READ_SATURATION = 32;
+function clamp01(n) {
+  if (Number.isNaN(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+function hasSensorFired(fm) {
+  return Boolean(fm.sensor?.last_fired);
+}
+function isDeadStatus(fm) {
+  return fm.status === "stale" || fm.status === "deprecated" || fm.status === "rejected";
+}
+function computeImpact(fm, usage, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const dormantDays = options.dormantDays ?? DEFAULT_DORMANT_DAYS;
+  const signals = [];
+  let raw = 0;
+  if (usage.read_count > 0) {
+    raw += Math.min(1, Math.log2(usage.read_count + 1) / Math.log2(READ_SATURATION + 1)) * 0.35;
+    signals.push(`read ${usage.read_count}\xD7`);
+  }
+  if (usage.applied_count > 0) {
+    raw += Math.min(1, usage.applied_count / 4) * 0.6;
+    signals.push(`applied ${usage.applied_count}\xD7`);
+  }
+  if (hasSensorFired(fm)) {
+    raw += 0.25;
+    signals.push("sensor fired");
+  }
+  if (usage.rejected_count > 0) {
+    raw -= Math.min(0.6, usage.rejected_count * 0.25);
+    signals.push(`rejected ${usage.rejected_count}\xD7`);
+  }
+  let score = clamp01(raw);
+  if (isDeadStatus(fm)) {
+    score *= 0.2;
+    signals.push(`status=${fm.status}`);
+  }
+  const anchor = usage.last_applied_at ?? usage.last_read_at ?? fm.created_at;
+  const ageDays = (now.getTime() - new Date(anchor).getTime()) / MS_PER_DAY;
+  const dormant = Number.isFinite(ageDays) && ageDays >= dormantDays && usage.applied_count === 0;
+  if (dormant) {
+    score *= 0.5;
+    signals.push(`dormant ${Math.floor(ageDays)}d`);
+  }
+  const tier = deriveTier(score, dormant, usage);
+  const pruneCandidate = isPruneCandidate(fm, usage, tier);
+  return { score: round3(score), tier, signals, pruneCandidate };
+}
+function deriveTier(score, dormant, usage) {
+  if (dormant && usage.read_count <= 1 && usage.applied_count === 0) return "dormant";
+  if (score >= 0.55) return "high";
+  if (score >= 0.2) return "medium";
+  return "low";
+}
+function isPruneCandidate(fm, usage, tier) {
+  if (fm.sensor || usage.applied_count > 0) return false;
+  if (isDeadStatus(fm)) return true;
+  if (usage.rejected_count > 0 && usage.rejected_count >= usage.read_count) return true;
+  if (tier === "dormant" && usage.read_count === 0) return true;
+  return false;
+}
+function round3(n) {
+  return Math.round(n * 1e3) / 1e3;
+}
+function compareImpact(a, b) {
+  if (b.score !== a.score) return b.score - a.score;
+  if (a.pruneCandidate !== b.pruneCandidate) return a.pruneCandidate ? 1 : -1;
+  return 0;
+}
+function summarizeImpact(scores) {
+  const summary = {
+    total: scores.length,
+    high: 0,
+    medium: 0,
+    low: 0,
+    dormant: 0,
+    prune_candidates: 0
+  };
+  for (const s of scores) {
+    summary[s.tier] += 1;
+    if (s.pruneCandidate) summary.prune_candidates += 1;
+  }
+  return summary;
+}
+
+// src/eval.ts
+function round32(n) {
+  return Math.round(n * 1e3) / 1e3;
+}
+function uniq(ids) {
+  return [...new Set(ids)];
+}
+function scoreRetrievalCase(name, expectIds, surfacedRanked) {
+  const expect = uniq(expectIds);
+  const surfaced = uniq(surfacedRanked);
+  const surfacedSet = new Set(surfaced);
+  const hits = expect.filter((id) => surfacedSet.has(id));
+  const misses = expect.filter((id) => !surfacedSet.has(id));
+  let bestRank = null;
+  for (let i = 0; i < surfaced.length; i++) {
+    if (expect.includes(surfaced[i])) {
+      bestRank = i + 1;
+      break;
+    }
+  }
+  return {
+    name,
+    expect_ids: expect,
+    surfaced_ids: surfaced,
+    hits,
+    misses,
+    precision: surfaced.length === 0 ? 0 : round32(hits.length / surfaced.length),
+    recall: expect.length === 0 ? 1 : round32(hits.length / expect.length),
+    best_rank: bestRank
+  };
+}
+function aggregateRetrieval(cases) {
+  const n = cases.length;
+  const mean = (sel) => n === 0 ? 0 : round32(cases.reduce((s, c) => s + sel(c), 0) / n);
+  return {
+    cases,
+    mean_precision: mean((c) => c.precision),
+    mean_recall: mean((c) => c.recall),
+    mrr: mean((c) => c.best_rank ? 1 / c.best_rank : 0)
+  };
+}
+function scoreSensorCase(name, expectFireIds, firedIds) {
+  const expect = uniq(expectFireIds);
+  const fired = uniq(firedIds);
+  const firedSet = new Set(fired);
+  const hits = expect.filter((id) => firedSet.has(id));
+  const misses = expect.filter((id) => !firedSet.has(id));
+  return {
+    name,
+    expect_fire_ids: expect,
+    fired_ids: fired,
+    hits,
+    misses,
+    recall: expect.length === 0 ? 1 : round32(hits.length / expect.length)
+  };
+}
+function aggregateSensors(cases) {
+  const totalExpected = cases.reduce((s, c) => s + c.expect_fire_ids.length, 0);
+  const totalHits = cases.reduce((s, c) => s + c.hits.length, 0);
+  return {
+    cases,
+    catch_rate: totalExpected === 0 ? 1 : round32(totalHits / totalExpected)
+  };
+}
+function overallScore(retrieval, sensors) {
+  if (retrieval && sensors) {
+    return Math.round((0.5 * retrieval.mean_recall + 0.2 * retrieval.mrr + 0.3 * sensors.catch_rate) * 100);
+  }
+  if (retrieval) {
+    return Math.round((0.7 * retrieval.mean_recall + 0.3 * retrieval.mrr) * 100);
+  }
+  if (sensors) {
+    return Math.round(sensors.catch_rate * 100);
+  }
+  return 0;
+}
+function buildReport(retrieval, sensors) {
+  return { retrieval, sensors, score: overallScore(retrieval, sensors) };
+}
+function titleFromBody(body) {
+  const lines = body.split("\n");
+  for (const line of lines) {
+    const heading = /^#+\s*(.+)$/.exec(line.trim());
+    if (heading) return heading[1].trim().slice(0, 120);
+  }
+  for (const line of lines) {
+    const t = line.trim();
+    if (t) return t.replace(/^[-*]\s*/, "").slice(0, 120);
+  }
+  return "";
+}
+function synthesizeSelfEvalCases(memories, options = {}) {
+  const includeFiles = options.includeFiles ?? true;
+  const skip = new Set(options.skipStatuses ?? ["stale", "deprecated", "rejected"]);
+  const cases = [];
+  for (const { memory } of memories) {
+    const fm = memory.frontmatter;
+    if (fm.type === "session_recap") continue;
+    if (skip.has(fm.status)) continue;
+    const paths = fm.anchor.paths;
+    if (paths.length === 0) continue;
+    const task = titleFromBody(memory.body) || fm.id;
+    cases.push({
+      name: fm.id,
+      task,
+      ...includeFiles ? { files: paths } : {},
+      expect_ids: [fm.id]
+    });
+  }
+  return cases;
+}
+
 // src/confidence.ts
 var DEFAULT_CONFIDENCE_THRESHOLDS = {
   trustedReads: 3,
@@ -664,13 +890,13 @@ var DEFAULT_CONFIDENCE_THRESHOLDS = {
   decayDays: 180,
   hardDecayDays: 365
 };
-var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+var MS_PER_DAY2 = 24 * 60 * 60 * 1e3;
 function deriveConfidence(fm, usage, thresholds = DEFAULT_CONFIDENCE_THRESHOLDS, now = /* @__PURE__ */ new Date()) {
   if (fm.status === "stale" || fm.status === "deprecated" || fm.status === "rejected") return "stale";
   const baseLevel = baseConfidence(fm, usage, thresholds);
   if (baseLevel !== "authoritative" && baseLevel !== "trusted") return baseLevel;
   const anchor = usage.last_read_at ?? fm.created_at;
-  const ageDays = (now.getTime() - new Date(anchor).getTime()) / MS_PER_DAY;
+  const ageDays = (now.getTime() - new Date(anchor).getTime()) / MS_PER_DAY2;
   if (Number.isNaN(ageDays) || ageDays <= 0) return baseLevel;
   if (ageDays >= thresholds.hardDecayDays) {
     return "low";
@@ -700,6 +926,122 @@ function isAutoPromoteEligible(fm, usage, rule = DEFAULT_AUTO_PROMOTE_RULE) {
   return usage.read_count >= rule.minReads;
 }
 
+// src/distinctive.ts
+var CODE_STOPWORDS = /* @__PURE__ */ new Set([
+  "import",
+  "export",
+  "function",
+  "return",
+  "const",
+  "let",
+  "var",
+  "class",
+  "public",
+  "private",
+  "protected",
+  "static",
+  "this",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  "void",
+  "async",
+  "await",
+  "from",
+  "type",
+  "interface",
+  "extends",
+  "implements",
+  "number",
+  "string",
+  "boolean",
+  "value",
+  "default",
+  "case",
+  "break",
+  "continue",
+  "throw",
+  "catch",
+  "finally",
+  "else",
+  "while",
+  "for",
+  "new",
+  "super",
+  "yield",
+  "module",
+  "require",
+  "console"
+]);
+var MIN_WORD_LEN = 4;
+function tokenizeWords(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= MIN_WORD_LEN && !CODE_STOPWORDS.has(t));
+}
+function buildDocFrequency(bodies) {
+  const df = /* @__PURE__ */ new Map();
+  for (const body of bodies) {
+    const unique = new Set(tokenizeWords(body));
+    for (const tok of unique) df.set(tok, (df.get(tok) ?? 0) + 1);
+  }
+  return { df, total: bodies.length };
+}
+function distinctiveCap(total) {
+  return Math.max(1, Math.floor(0.1 * total));
+}
+function isDistinctiveToken(token, freq) {
+  const tok = token.toLowerCase();
+  if (tok.length < MIN_WORD_LEN || CODE_STOPWORDS.has(tok)) return false;
+  const df = freq.df.get(tok);
+  if (df === void 0) return true;
+  return df <= distinctiveCap(freq.total);
+}
+function diffHasDistinctiveOverlap(addedDiffText, memoryBody, freq) {
+  const memoryTokens = new Set(tokenizeWords(memoryBody));
+  if (memoryTokens.size === 0) return false;
+  for (const tok of new Set(tokenizeWords(addedDiffText))) {
+    if (memoryTokens.has(tok) && isDistinctiveToken(tok, freq)) return true;
+  }
+  return false;
+}
+
+// src/skill-activation.ts
+function isSkill(fm) {
+  return fm.type === "skill";
+}
+function evaluateSkillActivation(fm, ctx) {
+  if (!isSkill(fm)) return { applicable: false, activated: true, reasons: [] };
+  const act = fm.activation;
+  if (!act) return { applicable: false, activated: true, reasons: ["no-activation"] };
+  const reasons = [];
+  if (act.always) reasons.push("always");
+  const task = (ctx.task ?? "").toLowerCase();
+  if (task) {
+    for (const kw of act.keywords) {
+      if (kw && task.includes(kw.toLowerCase())) {
+        reasons.push(`keyword:${kw}`);
+        break;
+      }
+    }
+  }
+  const files = ctx.files ?? [];
+  if (files.length > 0) {
+    outer: for (const glob of act.globs) {
+      for (const f of files) {
+        if (pathsOverlap(glob, f)) {
+          reasons.push(`glob:${glob}`);
+          break outer;
+        }
+      }
+    }
+  }
+  return { applicable: true, activated: reasons.length > 0, reasons };
+}
+function isSkillSuppressed(fm, ctx) {
+  const result = evaluateSkillActivation(fm, ctx);
+  return result.applicable && !result.activated;
+}
+
 // src/specificity.ts
 var GENERIC_PHRASES = [
   "validate input",
@@ -2631,7 +2973,7 @@ function pickLowercaseValuePattern(text) {
   for (const match of text.matchAll(/\blowercase\s+([A-Za-z][A-Za-z0-9_.:-]{2,79})\s+([a-z][a-z0-9_.:-]{1,40})\b/g)) {
     const key = match[1] ?? "";
     const value = match[2] ?? "";
-    if (!isDistinctiveToken(key, true) || isBoringValue(value)) continue;
+    if (!isDistinctiveToken2(key, true) || isBoringValue(value)) continue;
     candidates.push({
       label: `${key}=${value}`,
       pattern: `${escapeRegExp(key)}\\s*[:=]\\s*["']?${escapeRegExp(value)}["']?`,
@@ -2647,7 +2989,7 @@ function pickAssignmentPattern(text) {
       const key = match[1] ?? "";
       const operator = match[2] ?? "";
       const value = match[3] ?? "";
-      if (!isDistinctiveToken(key, true) || isBoringValue(value)) continue;
+      if (!isDistinctiveToken2(key, true) || isBoringValue(value)) continue;
       const label = `${key}${operator}${value}`;
       candidates.push({
         label,
@@ -2678,7 +3020,7 @@ function pickDistinctiveToken(text) {
     const raw = (match[1] ?? match[2] ?? match[3] ?? "").trim();
     const token = raw.replace(/^[^\w.-]+|[^\w.-]+$/g, "");
     const isCodeLike = Boolean(match[1] ?? match[2]);
-    if (!isDistinctiveToken(token, isCodeLike)) continue;
+    if (!isDistinctiveToken2(token, isCodeLike)) continue;
     const key = token.toLowerCase();
     const codeSpanBonus = match[1] ? 20 : match[2] ? 8 : 0;
     const shapeBonus = /[-_.:]/.test(token) ? 3 : /[A-Z]/.test(token.slice(1)) ? 2 : /\d/.test(token) ? 1 : 0;
@@ -2689,7 +3031,7 @@ function pickDistinctiveToken(text) {
   const best = [...candidates.values()].sort((a, b) => b.score - a.score)[0];
   return best?.raw ?? null;
 }
-function isDistinctiveToken(token, isCodeLike) {
+function isDistinctiveToken2(token, isCodeLike) {
   if (token.length < 4 || token.length > 80) return false;
   if (/^https?:\/\//i.test(token)) return false;
   if (/^\d+$/.test(token)) return false;
@@ -2716,20 +3058,24 @@ function escapeRegExp(value) {
 }
 export {
   AUTOPILOT_DEFAULTS,
+  ActivationSchema,
   AnchorSchema,
   BRIEFING_MARKER_TTL_MS,
   BRIEFING_PRESET_DEFAULTS,
   CHARS_PER_TOKEN,
   CODE_MAP_FILE,
+  CODE_STOPWORDS,
   CONFIG_FILE,
   CrossRepoProvenanceSchema,
   DECAY_DAYS,
   DEFAULT_AUTO_PROMOTE_RULE,
   DEFAULT_CONFIDENCE_THRESHOLDS,
   DEFAULT_CONFIG,
+  DEFAULT_DORMANT_DAYS,
   GUESSABLE_THRESHOLD,
   HAIVE_DIR,
   MEMORIES_DIR,
+  MIN_WORD_LEN,
   MemoryFrontmatterSchema,
   MemoryScopeSchema,
   MemoryStatusSchema,
@@ -2743,6 +3089,8 @@ export {
   USAGE_LOG_DIR,
   USAGE_LOG_FILE,
   addedLinesFromDiff,
+  aggregateRetrieval,
+  aggregateSensors,
   aggregateUsage,
   allocateBudget,
   antiPatternGateParams,
@@ -2751,19 +3099,26 @@ export {
   briefingMarkerPath,
   briefingMarkersDir,
   buildCodeMap,
+  buildDocFrequency,
   buildFrontmatter,
+  buildReport,
   bumpRead,
   codeMapPath,
   collectTimelineEntries,
+  compareImpact,
   compileRegexSensor,
+  computeImpact,
   configPath,
   contractLockPath,
   deriveConfidence,
   diffContract,
+  diffHasDistinctiveOverlap,
+  distinctiveCap,
   emptyUsage,
   emptyUsageIndex,
   enforcementDir,
   estimateTokens,
+  evaluateSkillActivation,
   extractActionsBriefBody,
   extractSnippet,
   findLexicalConflictPairs,
@@ -2776,10 +3131,13 @@ export {
   inferModulesFromPaths,
   isAutoPromoteEligible,
   isDecaying,
+  isDistinctiveToken,
   isFreshIsoDate,
   isGlobPath,
   isLikelyGuessable,
   isRetiredMemory,
+  isSkill,
+  isSkillSuppressed,
   isStackPackSeed,
   listMarkdownFilesRecursive,
   literalMatchesAllTokens,
@@ -2794,6 +3152,7 @@ export {
   memoryMatchesAnchorPaths,
   newMemoryId,
   normalizeSessionId,
+  overallScore,
   parseMemory,
   parseSince,
   pathsOverlap,
@@ -2804,6 +3163,7 @@ export {
   readRecentBriefingMarker,
   readRuntimeJournalTail,
   readUsageEvents,
+  recordApplied,
   recordRejection,
   relPathFrom,
   resolveBriefingBudget,
@@ -2817,6 +3177,8 @@ export {
   saveCodeMap,
   saveConfig,
   saveUsageIndex,
+  scoreRetrievalCase,
+  scoreSensorCase,
   sensorAppliesToPath,
   sensorTargetsFromDiff,
   serializeMemory,
@@ -2825,7 +3187,11 @@ export {
   stripPrivate,
   suggestSensorFromMemory,
   suggestTopicKey,
+  summarizeImpact,
+  synthesizeSelfEvalCases,
+  titleFromBody,
   tokenizeQuery,
+  tokenizeWords,
   trackDependencies,
   trackReads,
   truncateToTokens,