claude-memory-layer 1.0.0

package/src/core/task/blocker-resolver.ts

@@ -0,0 +1,325 @@
+/**
+ * Blocker Resolver - Resolve blocker texts to entity references
+ * AXIOMMIND: No stub task creation, fallback to condition
+ */
+
+import { Database } from 'duckdb';
+import { randomUUID } from 'crypto';
+import type { BlockerRef, BlockerKind, Entity } from '../types.js';
+import { makeEntityCanonicalKey, makeArtifactKey } from '../canonical-key.js';
+import { TaskMatcher } from './task-matcher.js';
+
+export interface BlockerResolverConfig {
+  project?: string;
+}
+
+// Patterns for artifact detection
+const URL_PATTERN = /^https?:\/\/.+/;
+const JIRA_PATTERN = /^[A-Z]+-\d+$/;
+const GITHUB_ISSUE_PATTERN = /^[^\/]+\/[^#]+#\d+$/;
+const TASK_ID_PATTERN = /^task:[^:]+:[^:]+$/;
+
+export class BlockerResolver {
+  private taskMatcher: TaskMatcher;
+
+  constructor(
+    private db: Database,
+    private config: BlockerResolverConfig = {}
+  ) {
+    this.taskMatcher = new TaskMatcher(db);
+  }
+
+  /**
+   * Resolve a single blocker text to entity reference
+   * Rules:
+   * 1. Strong ID/URL/key pattern → artifact
+   * 2. Explicit task_id → task
+   * 3. Task title match (strict only) → task
+   * 4. Fallback → condition (no stub task creation)
+   */
+  async resolveBlocker(
+    text: string,
+    sourceEntryId?: string
+  ): Promise<BlockerRef> {
+    const trimmedText = text.trim();
+
+    // Rule 1: Check for artifact patterns
+    const artifactRef = await this.tryResolveAsArtifact(trimmedText);
+    if (artifactRef) {
+      return artifactRef;
+    }
+
+    // Rule 2: Check for explicit task_id pattern
+    if (TASK_ID_PATTERN.test(trimmedText)) {
+      const taskRef = await this.tryResolveAsTaskId(trimmedText);
+      if (taskRef) {
+        return taskRef;
+      }
+      // Task ID not found, fall through to condition
+    }
+
+    // Rule 3: Try task title matching (strict only)
+    const taskMatch = await this.taskMatcher.match(trimmedText, this.config.project);
+
+    if (taskMatch.confidence === 'high' && taskMatch.match) {
+      // Strict match found
+      return {
+        kind: 'task',
+        entityId: taskMatch.match.entityId,
+        rawText: trimmedText,
+        confidence: taskMatch.score
+      };
+    }
+
+    // Rule 4: Fallback to condition (get-or-create)
+    // Also store candidates if any
+    const conditionRef = await this.createConditionBlocker(
+      trimmedText,
+      taskMatch.candidates
+    );
+
+    return conditionRef;
+  }
+
+  /**
+   * Resolve multiple blocker texts
+   */
+  async resolveBlockers(
+    texts: string[],
+    sourceEntryId?: string
+  ): Promise<BlockerRef[]> {
+    const results: BlockerRef[] = [];
+
+    for (const text of texts) {
+      const ref = await this.resolveBlocker(text, sourceEntryId);
+      results.push(ref);
+    }
+
+    return results;
+  }
+
+  /**
+   * Try to resolve as artifact (URL, JIRA, GitHub)
+   */
+  private async tryResolveAsArtifact(text: string): Promise<BlockerRef | null> {
+    // Check patterns
+    if (!URL_PATTERN.test(text) && !JIRA_PATTERN.test(text) && !GITHUB_ISSUE_PATTERN.test(text)) {
+      return null;
+    }
+
+    const canonicalKey = makeArtifactKey(text);
+
+    // Find or create artifact
+    const existing = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT entity_id FROM entities
+       WHERE entity_type = 'artifact' AND canonical_key = ?`,
+      [canonicalKey]
+    );
+
+    let entityId: string;
+
+    if (existing.length > 0) {
+      entityId = existing[0].entity_id as string;
+    } else {
+      // Create artifact entity via event
+      entityId = await this.declareArtifact(text, canonicalKey);
+    }
+
+    return {
+      kind: 'artifact',
+      entityId,
+      rawText: text,
+      confidence: 1.0
+    };
+  }
+
+  /**
+   * Try to resolve as explicit task ID
+   */
+  private async tryResolveAsTaskId(taskId: string): Promise<BlockerRef | null> {
+    // taskId format: task:project:identifier
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT entity_id FROM entities
+       WHERE entity_type = 'task' AND canonical_key = ?
+       AND status = 'active'`,
+      [taskId]
+    );
+
+    if (rows.length === 0) {
+      return null;
+    }
+
+    return {
+      kind: 'task',
+      entityId: rows[0].entity_id as string,
+      rawText: taskId,
+      confidence: 1.0
+    };
+  }
+
+  /**
+   * Create condition blocker (get-or-create)
+   */
+  private async createConditionBlocker(
+    text: string,
+    candidates?: Entity[]
+  ): Promise<BlockerRef> {
+    const canonicalKey = makeEntityCanonicalKey('condition', text, {
+      project: this.config.project
+    });
+
+    // Find existing condition
+    const existing = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT entity_id FROM entities
+       WHERE entity_type = 'condition' AND canonical_key = ?`,
+      [canonicalKey]
+    );
+
+    let entityId: string;
+
+    if (existing.length > 0) {
+      entityId = existing[0].entity_id as string;
+    } else {
+      // Create condition entity via event
+      entityId = await this.declareCondition(text, canonicalKey, candidates);
+    }
+
+    return {
+      kind: 'condition',
+      entityId,
+      rawText: text,
+      confidence: 0.5,
+      candidates: candidates?.map(c => c.entityId)
+    };
+  }
+
+  /**
+   * Declare a new condition entity
+   */
+  private async declareCondition(
+    text: string,
+    canonicalKey: string,
+    candidates?: Entity[]
+  ): Promise<string> {
+    const entityId = randomUUID();
+    const now = new Date().toISOString();
+
+    const currentJson = {
+      text,
+      resolved: false,
+      candidates: candidates?.map(c => ({
+        entityId: c.entityId,
+        title: c.title
+      }))
+    };
+
+    await this.db.run(
+      `INSERT INTO entities (
+        entity_id, entity_type, canonical_key, title, stage, status,
+        current_json, title_norm, search_text, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        entityId,
+        'condition',
+        canonicalKey,
+        text,
+        'raw',
+        'active',
+        JSON.stringify(currentJson),
+        text.toLowerCase().trim(),
+        text,
+        now,
+        now
+      ]
+    );
+
+    // Create alias
+    await this.db.run(
+      `INSERT INTO entity_aliases (entity_type, canonical_key, entity_id, is_primary)
+       VALUES (?, ?, ?, TRUE)
+       ON CONFLICT (entity_type, canonical_key) DO NOTHING`,
+      ['condition', canonicalKey, entityId]
+    );
+
+    return entityId;
+  }
+
+  /**
+   * Declare a new artifact entity
+   */
+  private async declareArtifact(
+    identifier: string,
+    canonicalKey: string
+  ): Promise<string> {
+    const entityId = randomUUID();
+    const now = new Date().toISOString();
+
+    // Determine artifact type
+    let artifactType = 'generic';
+    if (URL_PATTERN.test(identifier)) {
+      artifactType = 'url';
+    } else if (JIRA_PATTERN.test(identifier)) {
+      artifactType = 'jira';
+    } else if (GITHUB_ISSUE_PATTERN.test(identifier)) {
+      artifactType = 'github_issue';
+    }
+
+    const currentJson = {
+      identifier,
+      artifactType
+    };
+
+    await this.db.run(
+      `INSERT INTO entities (
+        entity_id, entity_type, canonical_key, title, stage, status,
+        current_json, title_norm, search_text, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        entityId,
+        'artifact',
+        canonicalKey,
+        identifier,
+        'raw',
+        'active',
+        JSON.stringify(currentJson),
+        identifier.toLowerCase(),
+        identifier,
+        now,
+        now
+      ]
+    );
+
+    // Create alias
+    await this.db.run(
+      `INSERT INTO entity_aliases (entity_type, canonical_key, entity_id, is_primary)
+       VALUES (?, ?, ?, TRUE)
+       ON CONFLICT (entity_type, canonical_key) DO NOTHING`,
+      ['artifact', canonicalKey, entityId]
+    );
+
+    return entityId;
+  }
+
+  /**
+   * Create unknown placeholder condition
+   * Used when task is blocked but no blocker text provided
+   */
+  async createUnknownPlaceholder(taskTitle: string): Promise<BlockerRef> {
+    const text = `Unknown blocker for: ${taskTitle}`;
+
+    const ref = await this.createConditionBlocker(text);
+
+    // Mark as auto placeholder
+    await this.db.run(
+      `UPDATE entities
+       SET current_json = json_set(current_json, '$.auto_placeholder', true)
+       WHERE entity_id = ?`,
+      [ref.entityId]
+    );
+
+    return {
+      ...ref,
+      confidence: 0.0
+    };
+  }
+}

package/src/core/task/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Task Entity System - AXIOMMIND Principle 5
+ * Task is Entity, state via event fold
+ */
+
+export * from './task-matcher.js';
+export * from './blocker-resolver.js';
+export * from './task-resolver.js';
+export * from './task-projector.js';

package/src/core/task/task-matcher.ts

@@ -0,0 +1,238 @@
+/**
+ * Task Matcher - Find existing tasks by title similarity
+ * AXIOMMIND: strict matching (≥0.92, gap≥0.03)
+ */
+
+import { Database } from 'duckdb';
+import type { Entity, MatchConfidence } from '../types.js';
+import { makeEntityCanonicalKey } from '../canonical-key.js';
+import { MATCH_THRESHOLDS } from '../types.js';
+
+export interface TaskMatchResult {
+  match: Entity | null;
+  confidence: MatchConfidence;
+  score: number;
+  gap?: number;
+  candidates?: Entity[];
+}
+
+export interface TaskMatcherConfig {
+  minCombinedScore: number;
+  minGap: number;
+  suggestionThreshold: number;
+  maxCandidates: number;
+}
+
+const DEFAULT_CONFIG: TaskMatcherConfig = {
+  minCombinedScore: MATCH_THRESHOLDS.minCombinedScore,
+  minGap: MATCH_THRESHOLDS.minGap,
+  suggestionThreshold: MATCH_THRESHOLDS.suggestionThreshold,
+  maxCandidates: 5
+};
+
+export class TaskMatcher {
+  private readonly config: TaskMatcherConfig;
+
+  constructor(
+    private db: Database,
+    config?: Partial<TaskMatcherConfig>
+  ) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Find task by exact canonical key match
+   */
+  async findExact(title: string, project?: string): Promise<Entity | null> {
+    const canonicalKey = makeEntityCanonicalKey('task', title, { project });
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM entities
+       WHERE entity_type = 'task' AND canonical_key = ?
+       AND status = 'active'`,
+      [canonicalKey]
+    );
+
+    if (rows.length === 0) return null;
+    return this.rowToEntity(rows[0]);
+  }
+
+  /**
+   * Find task by alias
+   */
+  async findByAlias(title: string, project?: string): Promise<Entity | null> {
+    const canonicalKey = makeEntityCanonicalKey('task', title, { project });
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT e.* FROM entities e
+       JOIN entity_aliases a ON e.entity_id = a.entity_id
+       WHERE a.entity_type = 'task' AND a.canonical_key = ?
+       AND e.status = 'active'`,
+      [canonicalKey]
+    );
+
+    if (rows.length === 0) return null;
+    return this.rowToEntity(rows[0]);
+  }
+
+  /**
+   * Search tasks by text (FTS-like)
+   */
+  async searchByText(query: string, project?: string): Promise<Array<{ entity: Entity; score: number }>> {
+    const searchPattern = `%${query.toLowerCase()}%`;
+
+    let sql = `
+      SELECT *,
+        CASE
+          WHEN title_norm = ? THEN 1.0
+          WHEN title_norm LIKE ? THEN 0.9
+          ELSE 0.7
+        END as match_score
+      FROM entities
+      WHERE entity_type = 'task'
+        AND status = 'active'
+        AND (title_norm LIKE ? OR search_text LIKE ?)
+    `;
+
+    const normalizedQuery = query.toLowerCase().trim();
+    const params: unknown[] = [normalizedQuery, `%${normalizedQuery}%`, searchPattern, searchPattern];
+
+    if (project) {
+      sql += ` AND json_extract(current_json, '$.project') = ?`;
+      params.push(project);
+    }
+
+    sql += ` ORDER BY match_score DESC, updated_at DESC LIMIT ?`;
+    params.push(this.config.maxCandidates);
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(sql, params);
+
+    return rows.map(row => ({
+      entity: this.rowToEntity(row),
+      score: row.match_score as number
+    }));
+  }
+
+  /**
+   * Match task with confidence classification
+   * Returns high confidence only if score ≥ 0.92 AND gap ≥ 0.03
+   */
+  async match(title: string, project?: string): Promise<TaskMatchResult> {
+    // Step 1: Try exact match
+    const exactMatch = await this.findExact(title, project);
+    if (exactMatch) {
+      return {
+        match: exactMatch,
+        confidence: 'high',
+        score: 1.0
+      };
+    }
+
+    // Step 2: Try alias match
+    const aliasMatch = await this.findByAlias(title, project);
+    if (aliasMatch) {
+      return {
+        match: aliasMatch,
+        confidence: 'high',
+        score: 0.98
+      };
+    }
+
+    // Step 3: Try text search
+    const searchResults = await this.searchByText(title, project);
+    if (searchResults.length === 0) {
+      return {
+        match: null,
+        confidence: 'none',
+        score: 0
+      };
+    }
+
+    const topResult = searchResults[0];
+    const secondScore = searchResults.length > 1 ? searchResults[1].score : null;
+
+    // Calculate gap
+    const gap = secondScore !== null ? topResult.score - secondScore : Infinity;
+
+    // Classify confidence
+    const confidence = this.classifyConfidence(topResult.score, gap);
+
+    // For strict matching, only return high confidence if criteria met
+    if (confidence === 'high') {
+      return {
+        match: topResult.entity,
+        confidence: 'high',
+        score: topResult.score,
+        gap
+      };
+    }
+
+    // For suggested, return candidates
+    if (confidence === 'suggested') {
+      return {
+        match: null,
+        confidence: 'suggested',
+        score: topResult.score,
+        gap,
+        candidates: searchResults.slice(0, this.config.maxCandidates).map(r => r.entity)
+      };
+    }
+
+    return {
+      match: null,
+      confidence: 'none',
+      score: topResult.score
+    };
+  }
+
+  /**
+   * Classify confidence based on AXIOMMIND thresholds
+   */
+  private classifyConfidence(score: number, gap: number): MatchConfidence {
+    const { minCombinedScore, minGap, suggestionThreshold } = this.config;
+
+    // High confidence: score ≥ 0.92 AND gap ≥ 0.03
+    if (score >= minCombinedScore && gap >= minGap) {
+      return 'high';
+    }
+
+    // Suggested: score ≥ 0.75
+    if (score >= suggestionThreshold) {
+      return 'suggested';
+    }
+
+    return 'none';
+  }
+
+  /**
+   * Get suggestion candidates (for condition fallback)
+   */
+  async getSuggestionCandidates(title: string, project?: string): Promise<Entity[]> {
+    const searchResults = await this.searchByText(title, project);
+    return searchResults
+      .filter(r => r.score >= this.config.suggestionThreshold)
+      .slice(0, this.config.maxCandidates)
+      .map(r => r.entity);
+  }
+
+  /**
+   * Convert database row to Entity
+   */
+  private rowToEntity(row: Record<string, unknown>): Entity {
+    return {
+      entityId: row.entity_id as string,
+      entityType: row.entity_type as 'task' | 'condition' | 'artifact',
+      canonicalKey: row.canonical_key as string,
+      title: row.title as string,
+      stage: row.stage as 'raw' | 'working' | 'candidate' | 'verified' | 'certified',
+      status: row.status as 'active' | 'contested' | 'deprecated' | 'superseded',
+      currentJson: typeof row.current_json === 'string'
+        ? JSON.parse(row.current_json)
+        : row.current_json as Record<string, unknown>,
+      titleNorm: row.title_norm as string | undefined,
+      searchText: row.search_text as string | undefined,
+      createdAt: new Date(row.created_at as string),
+      updatedAt: new Date(row.updated_at as string)
+    };
+  }
+}