@hiveai/core 0.13.7 → 0.13.9

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>;
@@ -549,6 +566,49 @@ interface ImpactSummary {
 /** Roll up a set of impact scores into tier counts. */
 declare function summarizeImpact(scores: ImpactScore[]): ImpactSummary;
 
+type PreventionSource = "sensor" | "anti-pattern";
+interface PreventionEvent {
+    /** ISO timestamp of the catch. */
+    at: string;
+    /** Memory id whose lesson fired. */
+    id: string;
+    /** Which gate path recorded it. */
+    source: PreventionSource;
+}
+declare function preventionLogPath(paths: HaivePaths): string;
+/** Append one catch to the log. Best-effort, creates the dir on demand. */
+declare function appendPreventionEvent(paths: HaivePaths, event: PreventionEvent): Promise<void>;
+/** Read all catch events (skips malformed lines). */
+declare function loadPreventionEvents(paths: HaivePaths): Promise<PreventionEvent[]>;
+interface PreventionTrend {
+    /** Catches in the last 7 days. */
+    last_7d: number;
+    /** Catches in the last 30 days. */
+    last_30d: number;
+    /** Catch counts per ISO week, oldest → newest, for the last N weeks (default 6). */
+    weekly: number[];
+}
+declare function computePreventionTrend(events: PreventionEvent[], now?: Date, weeks?: number): PreventionTrend;
+interface RecurrenceRow {
+    id: string;
+    /** Total catches for this memory. */
+    catches: number;
+    /** Number of distinct UTC days the lesson fired — the recurrence signal. */
+    distinct_days: number;
+    last_at: string;
+}
+interface RecurrenceReport {
+    /**
+     * Memories whose lesson was caught on >= 2 distinct days — i.e. the mistake was RE-INTRODUCED
+     * after it had already been captured and caught once. A high count means a recurring problem the
+     * team keeps reintroducing (the guardrail is earning its keep, and the root cause may need a
+     * stronger fix than a memory).
+     */
+    recurring_count: number;
+    top: RecurrenceRow[];
+}
+declare function computeRecurrence(events: PreventionEvent[]): RecurrenceReport;
+
 /**
  * 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
@@ -1580,6 +1640,8 @@ interface DashboardOptions {
     /** Dormancy window for impact scoring. Defaults to impact's own default. */
     dormantDays?: number;
     now?: Date;
+    /** Prevention event log (from `loadPreventionEvents`) — powers the trend + recurrence rollups. */
+    preventionEvents?: PreventionEvent[];
 }
 interface ImpactRow {
     id: string;
@@ -1598,6 +1660,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 +1703,17 @@ interface DashboardReport {
         decaying: number;
         top_dormant: DormantRow[];
     };
+    /** OUTCOME measurement: prevention events = times a memory's sensor/anti-pattern 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[];
+        /** Catch volume over time (from the prevention event log). */
+        trend: PreventionTrend;
+        /** Lessons re-introduced after capture (caught on >= 2 distinct days). */
+        recurrence: RecurrenceReport;
+    };
     corpus: {
         /** Number of memory files (policy corpus, excludes session_recap). */
         memory_files: number;
@@ -1646,4 +1725,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 PreventionEvent, type PreventionRow, type PreventionSource, type PreventionTrend, RUNTIME_JOURNAL_FILENAME, type RecurrenceReport, type RecurrenceRow, 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, appendPreventionEvent, appendRuntimeJournalEntry, appendUsageEvent, briefingMarkerPath, briefingMarkersDir, buildCodeMap, buildDashboard, buildDocFrequency, buildFrontmatter, buildReport, bumpRead, codeMapPath, collectTimelineEntries, compareEvalReports, compareImpact, compileRegexSensor, computeImpact, computePreventionTrend, computeRecurrence, 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, loadPreventionEvents, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseFindings, parseMemory, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, preventionLogPath, 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 };