@soleri/core 7.0.0 → 8.1.0

package/src/context/context-engine.ts

@@ -71,11 +71,34 @@ const STOP_PATTERNS = new Set([
   'out-of-the-box',
 ]);
 
-// ─── Confidence Thresholds ──────────────────────────────────────────
+// ─── Scoring Constants (tunable) ────────────────────────────────────
 
+/** Confidence thresholds for discrete levels. */
 const HIGH_CONFIDENCE = 0.75;
 const MEDIUM_CONFIDENCE = 0.45;
 
+/** Weights for knowledge item multi-signal scoring. */
+const KNOWLEDGE_WEIGHTS = {
+  /** Base FTS/vector score weight. */
+  baseScore: 0.4,
+  /** Title keyword overlap weight. */
+  titleMatch: 0.25,
+  /** Tag overlap weight. */
+  tagOverlap: 0.2,
+  /** Intent/domain alignment weight. */
+  intentBoost: 0.15,
+};
+
+/** Weights for confidence computation. */
+const CONFIDENCE_WEIGHTS = {
+  entitySignalPerEntity: 0.08,
+  entitySignalMax: 0.4,
+  actionSignal: 0.2,
+  knowledgeSignalMultiplier: 0.3,
+  sourceDiversityPerExtra: 0.05,
+  sourceDiversityMax: 0.1,
+};
+
 // ─── Class ──────────────────────────────────────────────────────────
 
 export class ContextEngine {
@@ -120,7 +143,13 @@ export class ContextEngine {
         if (seen.has(key)) continue;
         if (type === 'pattern' && STOP_PATTERNS.has(value)) continue;
         seen.add(key);
-        entities.push({ type, value, confidence });
+        entities.push({
+          type,
+          value,
+          confidence,
+          start: match.index,
+          end: match.index + match[0].length,
+        });
       }
     }
 
@@ -147,15 +176,31 @@ export class ContextEngine {
         domain,
         limit: this.config.vaultSearchLimit,
       });
-      // Normalize FTS5 -rank scores to 0-1 range
+      // Normalize FTS5 -rank scores to 0-1 range, then apply multi-signal scoring
       const maxScore = vaultResults.length > 0 ? Math.max(...vaultResults.map((r) => r.score)) : 1;
+      const promptTokens = new Set(
+        prompt
+          .toLowerCase()
+          .split(/\s+/)
+          .filter((t) => t.length >= 3),
+      );
       for (const r of vaultResults) {
+        const baseScore = maxScore > 0 ? r.score / maxScore : 0.5;
+        const enrichedScore = scoreKnowledgeItem(
+          baseScore,
+          r.entry.title,
+          r.entry.tags,
+          promptTokens,
+          domain,
+          r.entry.domain,
+        );
         items.push({
           id: r.entry.id,
           title: r.entry.title,
-          score: maxScore > 0 ? r.score / maxScore : 0.5,
+          score: enrichedScore,
           source: 'vault',
           domain: r.entry.domain,
+          tags: r.entry.tags,
         });
         vaultHits++;
       }
@@ -252,25 +297,29 @@ export class ContextEngine {
   ): number {
     let score = 0;
 
-    // Entity signal (0-0.4): more entities = clearer prompt
+    // Entity signal: more entities = clearer prompt
     const entityCount = entities.entities.length;
-    const entitySignal = Math.min(0.4, entityCount * 0.08);
-    score += entitySignal;
+    score += Math.min(
+      CONFIDENCE_WEIGHTS.entitySignalMax,
+      entityCount * CONFIDENCE_WEIGHTS.entitySignalPerEntity,
+    );
 
-    // Action signal (0-0.2): explicit actions boost confidence
+    // Action signal: explicit actions boost confidence
     const actions = entities.byType.action ?? [];
-    if (actions.length > 0) score += 0.2;
+    if (actions.length > 0) score += CONFIDENCE_WEIGHTS.actionSignal;
 
-    // Knowledge signal (0-0.3): relevant knowledge found
+    // Knowledge signal: relevant knowledge found
     if (knowledge.items.length > 0) {
-      const topScore = knowledge.items[0].score;
-      score += topScore * 0.3;
+      score += knowledge.items[0].score * CONFIDENCE_WEIGHTS.knowledgeSignalMultiplier;
     }
 
-    // Source diversity bonus (0-0.1): multiple sources = more confident
+    // Source diversity bonus: multiple sources = more confident
     const sources = new Set(knowledge.items.map((i) => i.source));
-    if (sources.size >= 2) score += 0.05;
-    if (sources.size >= 3) score += 0.05;
+    const diversityBonus = Math.min(
+      CONFIDENCE_WEIGHTS.sourceDiversityMax,
+      Math.max(0, sources.size - 1) * CONFIDENCE_WEIGHTS.sourceDiversityPerExtra,
+    );
+    score += diversityBonus;
 
     return Math.min(1, score);
   }
@@ -300,3 +349,53 @@ export class ContextEngine {
     return [...domains];
   }
 }
+
+// ─── Multi-Signal Knowledge Scoring ─────────────────────────────────
+
+/**
+ * Score a knowledge item using multiple signals:
+ * - baseScore: FTS5 rank or vector similarity (0-1)
+ * - titleMatch: keyword overlap between prompt and entry title
+ * - tagOverlap: how many prompt tokens appear in entry tags
+ * - intentBoost: domain alignment between query domain and entry domain
+ */
+function scoreKnowledgeItem(
+  baseScore: number,
+  title: string,
+  tags: string[],
+  promptTokens: Set<string>,
+  queryDomain: string | undefined,
+  entryDomain: string | undefined,
+): number {
+  // Title match: fraction of prompt tokens found in title
+  const titleTokens = new Set(
+    title
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length >= 3),
+  );
+  let titleOverlap = 0;
+  for (const t of promptTokens) {
+    if (titleTokens.has(t)) titleOverlap++;
+  }
+  const titleMatch = promptTokens.size > 0 ? titleOverlap / promptTokens.size : 0;
+
+  // Tag overlap: fraction of tags that match prompt tokens
+  const lowerTags = tags.map((t) => t.toLowerCase());
+  let tagHits = 0;
+  for (const tag of lowerTags) {
+    if (promptTokens.has(tag)) tagHits++;
+  }
+  const tagOverlap = lowerTags.length > 0 ? tagHits / lowerTags.length : 0;
+
+  // Intent boost: 1.0 if domains match, 0.0 otherwise
+  const intentBoost = queryDomain && entryDomain && queryDomain === entryDomain ? 1.0 : 0.0;
+
+  return Math.min(
+    1.0,
+    baseScore * KNOWLEDGE_WEIGHTS.baseScore +
+      titleMatch * KNOWLEDGE_WEIGHTS.titleMatch +
+      tagOverlap * KNOWLEDGE_WEIGHTS.tagOverlap +
+      intentBoost * KNOWLEDGE_WEIGHTS.intentBoost,
+  );
+}

package/src/context/types.ts

@@ -10,6 +10,10 @@ export interface ExtractedEntity {
   type: EntityType;
   value: string;
   confidence: number;
+  /** Start offset in the original prompt. */
+  start?: number;
+  /** End offset in the original prompt. */
+  end?: number;
 }
 
 export interface EntityExtractionResult {
@@ -25,6 +29,7 @@ export interface KnowledgeItem {
   score: number;
   source: 'vault' | 'cognee' | 'brain';
   domain?: string;
+  tags?: string[];
 }
 
 export interface KnowledgeRetrievalResult {

package/src/control/intent-router.ts

@@ -16,6 +16,7 @@ import type {
   IntentClassification,
   ModeConfig,
   MorphResult,
+  RoutingAccuracyReport,
 } from './types.js';
 
 // ─── Token Stemming ─────────────────────────────────────────────────
@@ -168,6 +169,16 @@ export class IntentRouter {
         matched_keywords TEXT NOT NULL DEFAULT '[]',
         created_at TEXT NOT NULL DEFAULT (datetime('now'))
       );
+
+      CREATE TABLE IF NOT EXISTS routing_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        routing_log_id INTEGER,
+        initial_intent TEXT NOT NULL,
+        actual_intent TEXT NOT NULL,
+        correction INTEGER NOT NULL DEFAULT 0,
+        confidence REAL NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
     `);
   }
 
@@ -314,6 +325,102 @@ export class IntentRouter {
     }
   }
 
+  // ─── Routing Feedback ─────────────────────────────────────────────
+
+  recordRoutingFeedback(input: {
+    routingLogId?: number;
+    initialIntent: string;
+    actualIntent: string;
+    confidence: number;
+    correction: boolean;
+  }): { recorded: boolean; id: number } {
+    const result = this.provider.run(
+      `INSERT INTO routing_feedback (routing_log_id, initial_intent, actual_intent, correction, confidence)
+       VALUES (?, ?, ?, ?, ?)`,
+      [
+        input.routingLogId ?? null,
+        input.initialIntent,
+        input.actualIntent,
+        input.correction ? 1 : 0,
+        input.confidence,
+      ],
+    );
+    return { recorded: true, id: Number(result.lastInsertRowid) };
+  }
+
+  getRoutingAccuracy(periodDays: number = 30): RoutingAccuracyReport {
+    const cutoff = new Date(Date.now() - periodDays * 86400000).toISOString();
+
+    const total = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    const correct = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE initial_intent = actual_intent AND created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    const corrections = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE correction = 1 AND created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    // Common misroutes
+    const misrouteRows = this.provider.all<{
+      from_intent: string;
+      to_intent: string;
+      count: number;
+    }>(
+      `SELECT initial_intent as from_intent, actual_intent as to_intent, COUNT(*) as count
+       FROM routing_feedback
+       WHERE initial_intent != actual_intent AND created_at >= ?
+       GROUP BY initial_intent, actual_intent
+       ORDER BY count DESC
+       LIMIT 10`,
+      [cutoff],
+    );
+
+    // Confidence calibration: group by confidence bucket and check accuracy per bucket
+    const calibrationRows = this.provider.all<{ bucket: string; total: number; correct: number }>(
+      `SELECT
+         CASE
+           WHEN confidence >= 0.8 THEN 'high'
+           WHEN confidence >= 0.4 THEN 'medium'
+           ELSE 'low'
+         END as bucket,
+         COUNT(*) as total,
+         SUM(CASE WHEN initial_intent = actual_intent THEN 1 ELSE 0 END) as correct
+       FROM routing_feedback
+       WHERE created_at >= ?
+       GROUP BY bucket`,
+      [cutoff],
+    );
+
+    const calibration: Record<string, { total: number; correct: number; accuracy: number }> = {};
+    for (const row of calibrationRows) {
+      calibration[row.bucket] = {
+        total: row.total,
+        correct: row.correct,
+        accuracy: row.total > 0 ? Math.round((row.correct / row.total) * 100) : 0,
+      };
+    }
+
+    return {
+      periodDays,
+      total,
+      correct,
+      accuracy: total > 0 ? Math.round((correct / total) * 100) : 100,
+      corrections,
+      commonMisroutes: misrouteRows.map((r) => ({
+        from: r.from_intent,
+        to: r.to_intent,
+        count: r.count,
+      })),
+      confidenceCalibration: calibration,
+    };
+  }
+
   // ─── Analytics ──────────────────────────────────────────────────────
 
   getRoutingStats(): {

package/src/control/types.ts

@@ -100,3 +100,13 @@ export interface MorphResult {
   currentMode: OperationalMode;
   behaviorRules: string[];
 }
+
+export interface RoutingAccuracyReport {
+  periodDays: number;
+  total: number;
+  correct: number;
+  accuracy: number;
+  corrections: number;
+  commonMisroutes: Array<{ from: string; to: string; count: number }>;
+  confidenceCalibration: Record<string, { total: number; correct: number; accuracy: number }>;
+}

package/src/curator/classifier.ts

@@ -0,0 +1,86 @@
+/**
+ * Classifier — LLM-based auto-categorization for vault entries.
+ *
+ * Suggests category, severity, and additional tags based on entry content.
+ * Graceful degradation: returns empty suggestions when LLM is unavailable.
+ */
+
+import type { LLMClient } from '../llm/llm-client.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface ClassificationResult {
+  classified: boolean;
+  suggestedDomain: string | null;
+  suggestedSeverity: string | null;
+  suggestedTags: string[];
+  confidence: number;
+  error?: string;
+}
+
+// ─── Classify ────────────────────────────────────────────────────────
+
+const CLASSIFY_PROMPT = `Classify this knowledge entry. Suggest the best domain, severity, and 3-5 tags.
+
+**Title:** {title}
+**Type:** {type}
+**Current tags:** {tags}
+**Description:** {description}
+
+Respond with ONLY this JSON (no markdown fences):
+{"domain":"string","severity":"critical|warning|suggestion","tags":["tag1","tag2","tag3"],"confidence":0.0-1.0}
+
+Rules:
+- domain: a single word (e.g., architecture, testing, security, design, performance, accessibility)
+- severity: critical = must-know, warning = important, suggestion = nice-to-know
+- tags: lowercase, hyphenated, specific and useful for search
+- confidence: how sure you are about this classification (0.0-1.0)`;
+
+export async function classifyEntry(
+  entry: IntelligenceEntry,
+  llm: LLMClient | null,
+): Promise<ClassificationResult> {
+  const fallback: ClassificationResult = {
+    classified: false,
+    suggestedDomain: null,
+    suggestedSeverity: null,
+    suggestedTags: [],
+    confidence: 0,
+  };
+
+  if (!llm) return fallback;
+
+  const prompt = CLASSIFY_PROMPT.replace('{title}', entry.title)
+    .replace('{type}', entry.type)
+    .replace('{tags}', entry.tags.join(', ') || 'none')
+    .replace('{description}', entry.description);
+
+  try {
+    const result = await llm.complete({
+      systemPrompt: 'You are a knowledge classifier. Respond only with JSON.',
+      userPrompt: prompt,
+      temperature: 0.1,
+      maxTokens: 300,
+      caller: 'classifier',
+      task: 'classify',
+    });
+
+    const parsed = JSON.parse(result.text) as {
+      domain: string;
+      severity: string;
+      tags: string[];
+      confidence: number;
+    };
+
+    return {
+      classified: true,
+      suggestedDomain: parsed.domain ?? null,
+      suggestedSeverity: parsed.severity ?? null,
+      suggestedTags: parsed.tags ?? [],
+      confidence: parsed.confidence ?? 0.5,
+    };
+  } catch (err) {
+    return { ...fallback, error: (err as Error).message };
+  }
+}

package/src/curator/quality-gate.ts

@@ -0,0 +1,127 @@
+/**
+ * Quality Gate — LLM-based entry quality evaluation.
+ *
+ * Evaluates vault entries on 5 criteria (novelty, actionability, specificity,
+ * relevance, informationDensity). Entries scoring below threshold are rejected.
+ *
+ * Graceful degradation: returns ACCEPT when LLM is unavailable.
+ */
+
+import type { LLMClient } from '../llm/llm-client.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type QualityVerdict = 'ACCEPT' | 'REJECT';
+
+export interface QualityScores {
+  novelty: number;
+  actionability: number;
+  specificity: number;
+  relevance: number;
+  informationDensity: number;
+}
+
+export interface QualityResult {
+  evaluated: boolean;
+  verdict: QualityVerdict;
+  overallScore: number;
+  scores: QualityScores;
+  reasoning: string;
+  rejectReasons?: string[];
+  error?: string;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+const REJECT_THRESHOLD = 50;
+const CRITICAL_LOW = 15;
+
+const QUALITY_PROMPT = `You are a strict knowledge base curator deciding whether an entry deserves to be in a high-quality vault.
+
+Your job is to REJECT junk and keep the vault clean. Be ruthless but fair.
+
+## Entry Under Review
+- **Type:** {type}
+- **Title:** {title}
+- **Tags:** {tags}
+- **Description:** {description}
+{why}{example}{context}
+
+## Scoring Criteria (each 0-100)
+
+1. **novelty** — Is this genuinely new knowledge or a truism? ("Write clean code" = 5, "Use driver adapter pattern to avoid Prisma lock-in" = 90)
+2. **actionability** — Can someone act on this? Vague advice = low, specific do/don't = high
+3. **specificity** — Is this specific to a real context or generic fluff?
+4. **relevance** — Does this belong in a technical knowledge vault?
+5. **informationDensity** — Is there real substance or mostly filler?
+
+## Verdict Rules
+- Overall score = average of all 5 criteria
+- **REJECT** if overall < ${REJECT_THRESHOLD}, or if ANY criterion scores <= ${CRITICAL_LOW}
+- **ACCEPT** otherwise
+- When in doubt, REJECT.
+
+Respond with ONLY this JSON (no markdown fences):
+{"verdict":"ACCEPT or REJECT","overallScore":0-100,"scores":{"novelty":N,"actionability":N,"specificity":N,"relevance":N,"informationDensity":N},"reasoning":"2-3 sentences","rejectReasons":["reason1"]}`;
+
+// ─── Evaluate ────────────────────────────────────────────────────────
+
+export async function evaluateQuality(
+  entry: IntelligenceEntry,
+  llm: LLMClient | null,
+): Promise<QualityResult> {
+  const fallback: QualityResult = {
+    evaluated: false,
+    verdict: 'ACCEPT',
+    overallScore: 50,
+    scores: {
+      novelty: 50,
+      actionability: 50,
+      specificity: 50,
+      relevance: 50,
+      informationDensity: 50,
+    },
+    reasoning: 'LLM unavailable — defaulting to accept',
+  };
+
+  if (!llm) return fallback;
+
+  const prompt = QUALITY_PROMPT.replace('{type}', entry.type)
+    .replace('{title}', entry.title)
+    .replace('{tags}', entry.tags.join(', ') || 'none')
+    .replace('{description}', entry.description)
+    .replace('{why}', entry.why ? `- **Why:** ${entry.why}\n` : '')
+    .replace('{example}', entry.example ? `- **Example:** ${entry.example}\n` : '')
+    .replace('{context}', entry.context ? `- **Context:** ${entry.context}\n` : '');
+
+  try {
+    const result = await llm.complete({
+      systemPrompt: 'You are a knowledge quality evaluator. Respond only with JSON.',
+      userPrompt: prompt,
+      temperature: 0.1,
+      maxTokens: 500,
+      caller: 'quality-gate',
+      task: 'evaluate',
+    });
+
+    const parsed = JSON.parse(result.text) as {
+      verdict: string;
+      overallScore: number;
+      scores: QualityScores;
+      reasoning: string;
+      rejectReasons?: string[];
+    };
+
+    return {
+      evaluated: true,
+      verdict: (parsed.verdict === 'REJECT' ? 'REJECT' : 'ACCEPT') as QualityVerdict,
+      overallScore: parsed.overallScore ?? 50,
+      scores: parsed.scores ?? fallback.scores,
+      reasoning: parsed.reasoning ?? '',
+      rejectReasons: parsed.rejectReasons,
+    };
+  } catch (err) {
+    return { ...fallback, error: (err as Error).message };
+  }
+}

package/src/domain-packs/index.ts

@@ -11,12 +11,6 @@ export {
 
 export { loadDomainPack, loadDomainPacksFromConfig, resolveDependencies } from './loader.js';
 
-export { installKnowledge, type KnowledgeInstallResult } from './knowledge-installer.js';
-
-export { installSkills, type SkillsInstallResult } from './skills-installer.js';
-
-export { injectDomainRules, removeDomainRules } from './inject-rules.js';
-
 export {
   type PackRuntime,
   type PackProjectContext,

package/src/domain-packs/loader.ts

@@ -18,7 +18,8 @@ export async function loadDomainPack(packageName: string): Promise<DomainPackMan
     mod = await import(packageName);
   } catch (err) {
     throw new Error(
-      `Failed to import domain pack "${packageName}": ${err instanceof Error ? err.message : String(err)}`, { cause: err },
+      `Failed to import domain pack "${packageName}": ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
     );
   }
 
@@ -33,10 +34,29 @@ export async function loadDomainPack(packageName: string): Promise<DomainPackMan
     throw new Error(`Domain pack "${packageName}" failed validation: ${result.errors.message}`);
   }
 
-  return {
-    ...result.data,
-    packageName,
-  };
+  const manifest: DomainPackManifest = { ...result.data, packageName };
+
+  // Warn if pack's engine requirement is mismatched
+  try {
+    const pkgJson = await import(`${packageName}/package.json`, { with: { type: 'json' } })
+      .then((m) => m.default)
+      .catch(() => null);
+    const peerCore = pkgJson?.peerDependencies?.['@soleri/core'];
+    if (peerCore) {
+      const requiredMajor = parseInt(peerCore.replace(/[^0-9]/g, ''), 10);
+      const { ENGINE_MAJOR_VERSION } = await import('../engine/module-manifest.js');
+      if (requiredMajor && ENGINE_MAJOR_VERSION && requiredMajor > ENGINE_MAJOR_VERSION) {
+        console.error(
+          `[warn] Domain pack "${packageName}" requires @soleri/core ${peerCore} ` +
+            `but engine is v${ENGINE_MAJOR_VERSION}. Upgrade @soleri/core.`,
+        );
+      }
+    }
+  } catch {
+    // Version check is best-effort — don't block loading
+  }
+
+  return manifest;
 }
 
 /**

package/src/domain-packs/pack-runtime.ts

@@ -14,7 +14,7 @@ import type { Vault } from '../vault/vault.js';
  */
 export interface PackProjectContext {
   id: string;
-  name: string;
+  name?: string;
   path: string;
   colors?: {
     [scale: string]: {
@@ -49,7 +49,7 @@ export interface PackRuntime {
   getProject(projectId: string): PackProjectContext | undefined;
 
   /** List all registered projects */
-  listProjects(): Array<{ id: string; name: string; path: string }>;
+  listProjects(): Array<{ id: string; name?: string; path: string }>;
 
   /** Create a session check (for tool chaining) */
   createCheck(type: string, data: Record<string, unknown>): string;
@@ -70,8 +70,8 @@ export interface PackRuntime {
 export function createPackRuntime(runtime: {
   vault: Vault;
   projectRegistry: {
-    getProject(id: string): PackProjectContext | undefined;
-    listProjects(): Array<{ id: string; name: string; path: string }>;
+    get(id: string): PackProjectContext | null;
+    list(): Array<{ id: string; name?: string; path: string }>;
   };
   sessionStore?: {
     createCheck(type: string, data: Record<string, unknown>): string;
@@ -81,8 +81,8 @@ export function createPackRuntime(runtime: {
 }): PackRuntime {
   return {
     vault: runtime.vault,
-    getProject: (id) => runtime.projectRegistry.getProject(id),
-    listProjects: () => runtime.projectRegistry.listProjects(),
+    getProject: (id) => runtime.projectRegistry.get(id) ?? undefined,
+    listProjects: () => runtime.projectRegistry.list(),
     createCheck: (type, data) => {
       if (!runtime.sessionStore) throw new Error('Session store not available');
       return runtime.sessionStore.createCheck(type, data);

package/src/domain-packs/types.ts

@@ -93,8 +93,14 @@ export interface DomainPack {
   requires?: string[];
   /** Called after pack is installed (one-time setup). */
   onInstall?: (runtime: AgentRuntime) => Promise<void>;
-  /** Called each time the agent starts (runtime initialization). */
-  onActivate?: (runtime: AgentRuntime) => Promise<void>;
+  /**
+   * Called each time the agent starts (runtime initialization).
+   *
+   * Receives `PackRuntime` (narrowed interface with vault, projects, session checks).
+   * The full `AgentRuntime` is passed as second argument for backwards compatibility
+   * but is deprecated — packs should only use `PackRuntime`.
+   */
+  onActivate?: (packRuntime: PackRuntime, runtime?: AgentRuntime) => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------