@hiveai/core 0.13.5 → 0.13.8

package/dist/index.d.ts

@@ -469,6 +469,14 @@ interface MemoryUsage {
      */
     applied_count: number;
     last_applied_at: string | null;
+    /**
+     * Number of *prevention* events — times this memory's sensor actually fired on a scanned diff,
+     * intercepting a known mistake before it landed. This is an OUTCOME signal (defect prevented),
+     * the closest proxy hAIve has to "did the knowledge stop a real problem?", distinct from
+     * retrieval (read) and self-reported usefulness (applied). Recorded by `haive sensors check`.
+     */
+    prevented_count: number;
+    last_prevented_at: string | null;
 }
 interface UsageIndex {
     version: 1;
@@ -490,6 +498,15 @@ declare function recordRejection(index: UsageIndex, id: string, reason: string |
  * a memory that merely got surfaced from one that demonstrably steered work.
  */
 declare function recordApplied(index: UsageIndex, id: string): UsageIndex;
+/** Debounce window so re-scanning the same diff within a few minutes doesn't inflate prevention
+ *  counts (a pre-commit hook can run the check several times for one commit). */
+declare const PREVENTION_DEBOUNCE_MS: number;
+/**
+ * Record a *prevention* event: a memory's sensor fired on a scanned diff, intercepting a known
+ * mistake before it landed. Outcome signal (defect prevented), stronger than a read. Debounced by
+ * {@link PREVENTION_DEBOUNCE_MS}. Returns true if a NEW event was recorded (false if debounced).
+ */
+declare function recordPrevention(index: UsageIndex, id: string, now?: number): boolean;
 declare const DECAY_DAYS = 90;
 declare function isDecaying(usage: MemoryUsage, createdAt: string): boolean;
 declare function trackReads(paths: HaivePaths, ids: string[]): Promise<UsageIndex>;
@@ -553,7 +570,7 @@ declare function summarizeImpact(scores: ImpactScore[]): ImpactSummary;
  * A rigorous, model-free, repeatable evaluation of hAIve's core promise: surfacing
  * the right knowledge and guardrails at the right moment. Unlike the agent benchmark
  * (which parses human-written reports), this is deterministic and CI-runnable — it
- * produces a chiffré quality score from labeled cases, so a regression in ranking or
+ * produces a numeric quality score from labeled cases, so a regression in ranking or
  * sensor coverage fails the build instead of silently degrading every agent session.
  *
  * Two case families:
@@ -1598,6 +1615,12 @@ interface DormantRow {
     last_read_at: string | null;
     age_days: number;
 }
+interface PreventionRow {
+    id: string;
+    type: string;
+    prevented_count: number;
+    last_prevented_at: string | null;
+}
 interface DashboardReport {
     generated_at: string;
     inventory: {
@@ -1635,6 +1658,13 @@ interface DashboardReport {
         decaying: number;
         top_dormant: DormantRow[];
     };
+    /** OUTCOME measurement: prevention events = times a memory's sensor fired on a real diff,
+     *  intercepting a known mistake. Distinct from retrieval (reads) — demonstrated value. */
+    prevention: {
+        total_events: number;
+        memories_with_catches: number;
+        top: PreventionRow[];
+    };
     corpus: {
         /** Number of memory files (policy corpus, excludes session_recap). */
         memory_files: number;
@@ -1646,4 +1676,4 @@ interface DashboardReport {
 /** Build the full observability rollup from the loaded corpus + usage index. Pure. */
 declare function buildDashboard(memories: LoadedMemory[], usage: UsageIndex, options?: DashboardOptions): DashboardReport;
 
-export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type Anchor, AnchorSchema, type AntiPatternGate, type AutoPromoteRule, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BreakingChange, type BriefingBudgetNumbers, type BriefingBudgetPreset, type BriefingMarker, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CODE_STOPWORDS, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type CollectTimelineOpts, type ConfidenceLevel, type ConfidenceThresholds, type ConflictCandidatePair, type ConflictCandidatesOpts, type ContractDiffResult, type ContractFile, type ContractSnapshot, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, DEFAULT_DORMANT_DAYS, type DashboardOptions, type DashboardReport, type DepChange, type DepTrackResult, type DependencySnapshot, type DocFrequency, type DormantRow, type DraftOptions, type DraftsOptions, type EvalDelta, type EvalReport, type EvalSpec, type Finding, type FindingSeverity, GUESSABLE_THRESHOLD, HAIVE_DIR, type HaiveConfig, type HaivePaths, type ImpactOptions, type ImpactRow, type ImpactScore, type ImpactSummary, type ImpactTier, type LexicalRankResult, type LoadedMemory, MEMORIES_DIR, MIN_WORD_LEN, type Memory, type MemoryDraft, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, type MetricDelta, PROJECT_CONTEXT_FILE, RUNTIME_JOURNAL_FILENAME, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type RuntimeJournalEntry, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type SelfEvalOptions, type Sensor, type SensorAggregate, type SensorCase, type SensorCaseResult, type SensorHit, type SensorRow, SensorSchema, type SensorSuggestionOptions, type SensorTarget, type SkillActivation, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, antiPatternGateParams, appendRuntimeJournalEntry, appendUsageEvent, briefingMarkerPath, briefingMarkersDir, buildCodeMap, buildDashboard, buildDocFrequency, buildFrontmatter, buildReport, bumpRead, codeMapPath, collectTimelineEntries, compareEvalReports, compareImpact, compileRegexSensor, computeImpact, configPath, contractLockPath, deriveConfidence, diffContract, diffHasDistinctiveOverlap, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evaluateSkillActivation, extractActionsBriefBody, extractSnippet, filterNewDrafts, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findingBody, findingToDraft, firstMemoryOneLine, getUsage, globToRegExp, hasRecentBriefingMarker, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, isDistinctiveToken, isFreshIsoDate, isGlobPath, isLikelyGuessable, isRetiredMemory, isSkill, isSkillSuppressed, isStackPackSeed, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseFindings, parseMemory, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, pullCrossRepoSources, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readUsageEvents, recordApplied, recordRejection, relPathFrom, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scoreRetrievalCase, scoreSensorCase, sensorAppliesToPath, sensorTargetsFromDiff, serializeMemory, snapshotContract, specificityScore, stripPrivate, suggestSensorFromMemory, suggestTopicKey, summarizeImpact, synthesizeSelfEvalCases, titleFromBody, tokenizeQuery, tokenizeWords, trackDependencies, trackReads, truncateToTokens, usageLogPath, usageLogSize, usagePath, verifyAnchor, watchContracts, writeBriefingMarker };
+export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type Anchor, AnchorSchema, type AntiPatternGate, type AutoPromoteRule, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BreakingChange, type BriefingBudgetNumbers, type BriefingBudgetPreset, type BriefingMarker, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CODE_STOPWORDS, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type CollectTimelineOpts, type ConfidenceLevel, type ConfidenceThresholds, type ConflictCandidatePair, type ConflictCandidatesOpts, type ContractDiffResult, type ContractFile, type ContractSnapshot, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, DEFAULT_DORMANT_DAYS, type DashboardOptions, type DashboardReport, type DepChange, type DepTrackResult, type DependencySnapshot, type DocFrequency, type DormantRow, type DraftOptions, type DraftsOptions, type EvalDelta, type EvalReport, type EvalSpec, type Finding, type FindingSeverity, GUESSABLE_THRESHOLD, HAIVE_DIR, type HaiveConfig, type HaivePaths, type ImpactOptions, type ImpactRow, type ImpactScore, type ImpactSummary, type ImpactTier, type LexicalRankResult, type LoadedMemory, MEMORIES_DIR, MIN_WORD_LEN, type Memory, type MemoryDraft, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, type MetricDelta, PREVENTION_DEBOUNCE_MS, PROJECT_CONTEXT_FILE, type PreventionRow, RUNTIME_JOURNAL_FILENAME, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type RuntimeJournalEntry, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type SelfEvalOptions, type Sensor, type SensorAggregate, type SensorCase, type SensorCaseResult, type SensorHit, type SensorRow, SensorSchema, type SensorSuggestionOptions, type SensorTarget, type SkillActivation, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, antiPatternGateParams, appendRuntimeJournalEntry, appendUsageEvent, briefingMarkerPath, briefingMarkersDir, buildCodeMap, buildDashboard, buildDocFrequency, buildFrontmatter, buildReport, bumpRead, codeMapPath, collectTimelineEntries, compareEvalReports, compareImpact, compileRegexSensor, computeImpact, configPath, contractLockPath, deriveConfidence, diffContract, diffHasDistinctiveOverlap, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evaluateSkillActivation, extractActionsBriefBody, extractSnippet, filterNewDrafts, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findingBody, findingToDraft, firstMemoryOneLine, getUsage, globToRegExp, hasRecentBriefingMarker, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, isDistinctiveToken, isFreshIsoDate, isGlobPath, isLikelyGuessable, isRetiredMemory, isSkill, isSkillSuppressed, isStackPackSeed, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseFindings, parseMemory, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, pullCrossRepoSources, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readUsageEvents, recordApplied, recordPrevention, recordRejection, relPathFrom, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scoreRetrievalCase, scoreSensorCase, sensorAppliesToPath, sensorTargetsFromDiff, serializeMemory, snapshotContract, specificityScore, stripPrivate, suggestSensorFromMemory, suggestTopicKey, summarizeImpact, synthesizeSelfEvalCases, titleFromBody, tokenizeQuery, tokenizeWords, trackDependencies, trackReads, truncateToTokens, usageLogPath, usageLogSize, usagePath, verifyAnchor, watchContracts, writeBriefingMarker };

package/dist/index.js

@@ -596,7 +596,9 @@ function emptyUsage() {
     last_rejected_at: null,
     rejection_reason: null,
     applied_count: 0,
-    last_applied_at: null
+    last_applied_at: null,
+    prevented_count: 0,
+    last_prevented_at: null
   };
 }
 function normalizeUsage(stored) {
@@ -667,6 +669,21 @@ function recordApplied(index, id) {
   };
   return index;
 }
+var PREVENTION_DEBOUNCE_MS = 5 * 60 * 1e3;
+function recordPrevention(index, id, now = Date.now()) {
+  const current = normalizeUsage(index.by_id[id]);
+  const last = current.last_prevented_at ? Date.parse(current.last_prevented_at) : 0;
+  if (Number.isFinite(last) && last > 0 && now - last < PREVENTION_DEBOUNCE_MS) {
+    index.by_id[id] = current;
+    return false;
+  }
+  index.by_id[id] = {
+    ...current,
+    prevented_count: current.prevented_count + 1,
+    last_prevented_at: new Date(now).toISOString()
+  };
+  return true;
+}
 var DECAY_DAYS = 90;
 function isDecaying(usage, createdAt) {
   const threshold = Date.now() - DECAY_DAYS * 24 * 60 * 60 * 1e3;
@@ -710,7 +727,10 @@ function computeImpact(fm, usage, options = {}) {
     raw += Math.min(1, usage.applied_count / 4) * 0.6;
     signals.push(`applied ${usage.applied_count}\xD7`);
   }
-  if (hasSensorFired(fm)) {
+  if (usage.prevented_count > 0) {
+    raw += Math.min(1, usage.prevented_count / 3) * 0.6;
+    signals.push(`prevented ${usage.prevented_count}\xD7`);
+  } else if (hasSensorFired(fm)) {
     raw += 0.25;
     signals.push("sensor fired");
   }
@@ -3294,6 +3314,8 @@ function buildDashboard(memories, usage, options = {}) {
   let decaying = 0;
   let bodyChars = 0;
   const dormantRows = [];
+  let preventionEvents = 0;
+  const preventionRows = [];
   for (const { memory } of memories) {
     const fm = memory.frontmatter;
     if (fm.type === "session_recap") {
@@ -3338,6 +3360,15 @@ function buildDashboard(memories, usage, options = {}) {
       signals: impact.signals,
       prune_candidate: impact.pruneCandidate
     });
+    if (memUsage.prevented_count > 0) {
+      preventionEvents += memUsage.prevented_count;
+      preventionRows.push({
+        id: fm.id,
+        type: fm.type,
+        prevented_count: memUsage.prevented_count,
+        last_prevented_at: memUsage.last_prevented_at
+      });
+    }
     if (isDecaying(memUsage, fm.created_at)) decaying += 1;
     if (impact.tier === "dormant") {
       const anchor = memUsage.last_read_at ?? fm.created_at;
@@ -3377,6 +3408,11 @@ function buildDashboard(memories, usage, options = {}) {
       decaying,
       top_dormant: dormantRows.slice(0, top)
     },
+    prevention: {
+      total_events: preventionEvents,
+      memories_with_catches: preventionRows.length,
+      top: preventionRows.sort((a, b) => b.prevented_count - a.prevented_count).slice(0, top)
+    },
     corpus: {
       memory_files: inventory.total,
       body_chars: bodyChars,
@@ -3408,6 +3444,7 @@ export {
   MemoryScopeSchema,
   MemoryStatusSchema,
   MemoryTypeSchema,
+  PREVENTION_DEBOUNCE_MS,
   PROJECT_CONTEXT_FILE,
   RUNTIME_JOURNAL_FILENAME,
   SESSION_RECAP_TTL_MS,
@@ -3502,6 +3539,7 @@ export {
   readRuntimeJournalTail,
   readUsageEvents,
   recordApplied,
+  recordPrevention,
   recordRejection,
   relPathFrom,
   resolveBriefingBudget,