reflectt-node 0.1.0

package/dist/insights.d.ts

@@ -0,0 +1,222 @@
+import type { Reflection } from './reflections.js';
+declare const COOLDOWN_MS: number;
+declare const PROMOTION_THRESHOLD = 2;
+/** Scoring engine version — increment on any rule change for audit trail */
+export declare const SCORING_ENGINE_VERSION = "1.1.0";
+export declare const HYSTERESIS_BUFFER = 0.3;
+export declare const PRIORITY_THRESHOLDS: {
+    readonly P0: 8;
+    readonly P1: 5;
+    readonly P2: 3;
+};
+export declare const INSIGHT_STATUSES: readonly ["candidate", "promoted", "pending_triage", "task_created", "cooldown", "closed"];
+export type InsightStatus = (typeof INSIGHT_STATUSES)[number];
+export declare const PROMOTION_READINESS: readonly ["not_ready", "ready", "promoted", "override"];
+export type PromotionReadiness = (typeof PROMOTION_READINESS)[number];
+export interface InsightClusterKey {
+    workflow_stage: string;
+    failure_family: string;
+    impacted_unit: string;
+}
+export interface Insight {
+    id: string;
+    cluster_key: string;
+    workflow_stage: string;
+    failure_family: string;
+    impacted_unit: string;
+    title: string;
+    status: InsightStatus;
+    score: number;
+    priority: string;
+    reflection_ids: string[];
+    independent_count: number;
+    evidence_refs: string[];
+    authors: string[];
+    promotion_readiness: PromotionReadiness;
+    recurring_candidate: boolean;
+    cooldown_until: number | null;
+    cooldown_reason: string | null;
+    severity_max: string | null;
+    task_id?: string | null;
+    metadata?: Record<string, unknown>;
+    created_at: number;
+    updated_at: number;
+}
+export interface InsightRow {
+    id: string;
+    cluster_key: string;
+    workflow_stage: string;
+    failure_family: string;
+    impacted_unit: string;
+    title: string;
+    status: string;
+    score: number;
+    priority: string;
+    reflection_ids: string;
+    independent_count: number;
+    evidence_refs: string;
+    authors: string;
+    promotion_readiness: string;
+    recurring_candidate: number;
+    cooldown_until: number | null;
+    cooldown_reason: string | null;
+    severity_max: string | null;
+    task_id: string | null;
+    metadata: string | null;
+    created_at: number;
+    updated_at: number;
+}
+/**
+ * Derive priority from score (no hysteresis — used for initial assignment).
+ */
+export declare function scoreToPriority(score: number): string;
+/**
+ * Priority with hysteresis: prevents flapping near threshold boundaries.
+ *
+ * - To upgrade priority (e.g. P1→P0), score must exceed threshold + buffer
+ * - To downgrade (e.g. P0→P1), score must drop below threshold - buffer
+ * - If score is in the buffer zone, previous priority is retained
+ */
+export declare function scoreToPriorityWithHysteresis(score: number, previousPriority: string | null): string;
+/**
+ * Compute aggregate score from linked reflections.
+ * Base = max confidence, +severity boost, +volume boost.
+ */
+export declare function computeScore(reflections: Reflection[]): number;
+/**
+ * Build cluster key from a reflection.
+ *
+ * NOTE: When a reflection lacks explicit `unit:` / `stage:` tags, we try to
+ * avoid collapsing everything into `unknown::*::unknown` by:
+ *  - deriving unit from the first non-reserved tag (e.g. `chat`, `status-discipline`)
+ *  - as a last resort, deriving a short topic signature from the pain text
+ */
+export declare function extractClusterKey(reflection: Reflection): InsightClusterKey;
+export interface DecisionTrace {
+    version: string;
+    dedupe_cluster_id: string;
+    promotion_band: PromotionReadiness;
+    top_contributors: Array<{
+        factor: string;
+        value: number;
+        description: string;
+    }>;
+    hysteresis_applied: boolean;
+    previous_priority: string | null;
+    raw_score: number;
+}
+export declare function buildDecisionTrace(reflections: Reflection[], clusterKeyStr: string, readiness: PromotionReadiness, previousPriority: string | null, score: number): DecisionTrace;
+export declare function hasMinimumQuality(reflection: Reflection): boolean;
+/**
+ * Can this set of reflections promote an insight?
+ *
+ * Rules:
+ *   0. At least one reflection must pass minimum quality gate
+ *   1. >= 2 independent reflections (different authors)
+ *   2. OR 1 high/critical-severity reflection with evidence (override)
+ */
+export declare function canPromote(reflections: Reflection[]): boolean;
+/**
+ * Find existing active insight matching a cluster key.
+ */
+export declare function findByCluster(clusterKeyStr: string): Insight | null;
+/**
+ * Ingest a reflection into the insight engine.
+ */
+export declare function ingestReflection(reflection: Reflection): Insight;
+/**
+ * Tick cooldowns: move promoted past window → cooldown, expired cooldowns → closed.
+ */
+export declare function tickCooldowns(): {
+    cooled: number;
+    closed: number;
+};
+export declare function getInsight(id: string): Insight | null;
+export interface InsightListOpts {
+    status?: string;
+    priority?: string;
+    workflow_stage?: string;
+    failure_family?: string;
+    impacted_unit?: string;
+    limit?: number;
+    offset?: number;
+}
+export declare function listInsights(opts?: InsightListOpts): {
+    insights: Insight[];
+    total: number;
+};
+export declare function insightStats(): {
+    total: number;
+    by_status: Record<string, number>;
+    by_priority: Record<string, number>;
+    by_failure_family: Record<string, number>;
+};
+export declare function _clearInsightStore(): void;
+/**
+ * Update an insight's status and optionally link a task.
+ * Used by the insight→task bridge when auto-creating or triaging.
+ */
+export declare function updateInsightStatus(insightId: string, status: InsightStatus, taskId?: string): boolean;
+export { COOLDOWN_MS, PROMOTION_THRESHOLD, SCORING_ENGINE_VERSION as _SCORING_ENGINE_VERSION };
+export interface LoopSummaryEntry {
+    insight_id: string;
+    title: string;
+    score: number;
+    priority: string;
+    status: InsightStatus;
+    workflow_stage: string;
+    failure_family: string;
+    impacted_unit: string;
+    independent_count: number;
+    authors: string[];
+    evidence_count: number;
+    evidence_refs: string[];
+    linked_task: {
+        id: string;
+        title: string;
+        status: string;
+        assignee: string | null;
+    } | null;
+    addressed: boolean;
+    created_at: number;
+    updated_at: number;
+}
+export interface LoopSummaryOpts {
+    limit?: number;
+    min_score?: number;
+    exclude_addressed?: boolean;
+}
+/**
+ * Returns top insight signals from the reflection loop, ranked by score.
+ * Each entry includes linked task details and evidence status.
+ *
+ * "Addressed" means the insight has a linked task in done/validating status,
+ * or the insight itself is in cooldown/closed status.
+ */
+export declare function getLoopSummary(opts?: LoopSummaryOpts): {
+    entries: LoopSummaryEntry[];
+    total: number;
+    filters: {
+        limit: number;
+        min_score: number;
+        exclude_addressed: boolean;
+    };
+};
+export declare function getOrphanedInsights(): Insight[];
+export interface ReconcileResult {
+    scanned: number;
+    linked: number;
+    created: number;
+    skipped: number;
+    errors: string[];
+    details: Array<{
+        insight_id: string;
+        action: string;
+        task_id?: string;
+        reason?: string;
+    }>;
+}
+export declare function reconcileInsightTaskLinks(createTaskFn: (insight: Insight) => {
+    taskId: string;
+} | null, dryRun?: boolean): ReconcileResult;
+//# sourceMappingURL=insights.d.ts.map

package/dist/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["../src/insights.ts"],"names":[],"mappings":"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"}