@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/cases/membership-explain.d.ts

@@ -0,0 +1,56 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { CaseMembershipSourceType } from './types.js';
+export interface CaseMembershipScoreBreakdown {
+    entity_overlap: number | null;
+    embedding_similarity: number | null;
+    temporal_proximity: number | null;
+    explicit_from_wiki: number | null;
+}
+export interface CaseMembershipExplanation {
+    case_id: string;
+    terminal_case_id: string;
+    resolved_via_case_id: string | null;
+    chain: string[];
+    source_type: CaseMembershipSourceType;
+    source_id: string;
+    membership: {
+        status: string;
+        role: string | null;
+        confidence: number | null;
+        reason: string | null;
+        user_locked: boolean;
+        assignment_strategy: string | null;
+        assigned_at: string | null;
+    };
+    score_breakdown: CaseMembershipScoreBreakdown | null;
+    score_breakdown_reason?: 'breakdown_not_recorded' | 'breakdown_malformed';
+    source_locator: string | null;
+    explanation_updated_at: string | null;
+    warnings: string[];
+}
+export interface PopulateScoreBreakdownInput {
+    case_id: string;
+    source_type: CaseMembershipSourceType;
+    source_id: string;
+    assignment_strategy?: string | null;
+    source_locator?: string | null;
+    now?: string;
+}
+export type ExplainCaseMembershipResult = CaseMembershipExplanation | {
+    kind: 'not_found';
+    code: 'case.membership_not_found';
+    message: string;
+    terminal_case_id: string;
+    resolved_via_case_id: string | null;
+    chain: string[];
+};
+export declare function explainCaseMembership(adapter: DatabaseAdapter, input: {
+    case_id: string;
+    source_type: CaseMembershipSourceType;
+    source_id: string;
+}): ExplainCaseMembershipResult;
+export declare function populateScoreBreakdown(adapter: DatabaseAdapter, membershipRow: PopulateScoreBreakdownInput, breakdown: CaseMembershipScoreBreakdown): {
+    kind: 'populated';
+    changes: number;
+};
+//# sourceMappingURL=membership-explain.d.ts.map

package/dist/cases/membership-explain.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainCaseMembership = explainCaseMembership;
+exports.populateScoreBreakdown = populateScoreBreakdown;
+const canonicalize_js_1 = require("../canonicalize.js");
+const store_js_1 = require("./store.js");
+function normalizeNow(value) {
+    return value ?? new Date().toISOString();
+}
+function placeholders(values) {
+    if (values.length === 0) {
+        throw new Error('Cannot build SQL IN clause for an empty value list.');
+    }
+    return values.map(() => '?').join(', ');
+}
+function loadMembership(adapter, chain, sourceType, sourceId) {
+    const row = adapter
+        .prepare(`
+        SELECT case_id, source_type, source_id, status, role, confidence, reason,
+               user_locked, assignment_strategy, added_at AS assigned_at,
+               score_breakdown_json, source_locator, explanation_updated_at, updated_at
+        FROM case_memberships
+        WHERE case_id IN (${placeholders(chain)})
+          AND source_type = ?
+          AND source_id = ?
+        ORDER BY
+          CASE status
+            WHEN 'active' THEN 0
+            WHEN 'candidate' THEN 1
+            WHEN 'excluded' THEN 2
+            WHEN 'removed' THEN 3
+            ELSE 4
+          END ASC,
+          user_locked DESC,
+          updated_at DESC,
+          case_id ASC
+        LIMIT 1
+      `)
+        .get(...chain, sourceType, sourceId);
+    return row ?? null;
+}
+function nullableNumber(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+function parseScoreBreakdown(value) {
+    if (value === null || value.trim().length === 0) {
+        return {
+            breakdown: null,
+            reason: 'breakdown_not_recorded',
+            warnings: ['breakdown_not_recorded'],
+        };
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                breakdown: null,
+                reason: 'breakdown_malformed',
+                warnings: ['breakdown_malformed'],
+            };
+        }
+        const record = parsed;
+        return {
+            breakdown: {
+                entity_overlap: nullableNumber(record.entity_overlap),
+                embedding_similarity: nullableNumber(record.embedding_similarity),
+                temporal_proximity: nullableNumber(record.temporal_proximity),
+                explicit_from_wiki: nullableNumber(record.explicit_from_wiki),
+            },
+            warnings: [],
+        };
+    }
+    catch {
+        return {
+            breakdown: null,
+            reason: 'breakdown_malformed',
+            warnings: ['breakdown_malformed'],
+        };
+    }
+}
+function explainCaseMembership(adapter, input) {
+    const explainAdapter = adapter;
+    const resolution = (0, store_js_1.resolveCanonicalCaseChain)(explainAdapter, input.case_id);
+    const chain = (0, store_js_1.expandCaseChainForAssembly)(explainAdapter, resolution.terminal_case_id, resolution.chain);
+    const row = loadMembership(explainAdapter, chain, input.source_type, input.source_id);
+    if (!row) {
+        return {
+            kind: 'not_found',
+            code: 'case.membership_not_found',
+            message: 'Membership row was not found in the canonical case chain.',
+            terminal_case_id: resolution.terminal_case_id,
+            resolved_via_case_id: resolution.resolved_via_case_id,
+            chain,
+        };
+    }
+    const parsedBreakdown = parseScoreBreakdown(row.score_breakdown_json);
+    return {
+        case_id: row.case_id,
+        terminal_case_id: resolution.terminal_case_id,
+        resolved_via_case_id: resolution.resolved_via_case_id,
+        chain,
+        source_type: row.source_type,
+        source_id: row.source_id,
+        membership: {
+            status: row.status,
+            role: row.role,
+            confidence: row.confidence,
+            reason: row.reason,
+            user_locked: Number(row.user_locked) === 1,
+            assignment_strategy: row.assignment_strategy,
+            assigned_at: row.assigned_at,
+        },
+        score_breakdown: parsedBreakdown.breakdown,
+        ...(parsedBreakdown.reason ? { score_breakdown_reason: parsedBreakdown.reason } : {}),
+        source_locator: row.source_locator,
+        explanation_updated_at: row.explanation_updated_at,
+        warnings: parsedBreakdown.warnings,
+    };
+}
+function populateScoreBreakdown(adapter, membershipRow, breakdown) {
+    const now = normalizeNow(membershipRow.now);
+    const result = adapter
+        .prepare(`
+        UPDATE case_memberships
+        SET score_breakdown_json = ?,
+            source_locator = COALESCE(?, source_locator),
+            assignment_strategy = COALESCE(?, assignment_strategy),
+            explanation_updated_at = ?
+        WHERE case_id = ?
+          AND source_type = ?
+          AND source_id = ?
+      `)
+        .run((0, canonicalize_js_1.canonicalizeJSON)(breakdown), membershipRow.source_locator ?? null, membershipRow.assignment_strategy ?? null, now, membershipRow.case_id, membershipRow.source_type, membershipRow.source_id);
+    return { kind: 'populated', changes: result.changes };
+}
+//# sourceMappingURL=membership-explain.js.map

package/dist/cases/membership-matcher.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+export interface CaseMembershipMatchInput {
+    event_id: string;
+    event_text: string;
+    event_entities: string[];
+    observed_at: string;
+    explicit_case_id?: string | null;
+    query_embedding?: Float32Array | null;
+    now?: string;
+}
+export interface CaseMembershipMatch {
+    case_id: string;
+    score: number;
+    status: 'active' | 'candidate';
+    reason: string;
+}
+export type CaseMembershipMatchResult = CaseMembershipMatch[] | {
+    kind: 'precompile_gap';
+    code: 'case.precompile_gap';
+    case_id: string;
+};
+export declare function matchEventToExistingCases(adapter: DatabaseAdapter, input: CaseMembershipMatchInput): CaseMembershipMatchResult;
+//# sourceMappingURL=membership-matcher.d.ts.map

package/dist/cases/membership-matcher.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchEventToExistingCases = matchEventToExistingCases;
+const wiki_page_index_js_1 = require("./wiki-page-index.js");
+const ACTIVE_CASE_STATUSES = new Set(['active', 'blocked']);
+const ACTIVE_THRESHOLD = 0.7;
+const CANDIDATE_THRESHOLD = 0.52;
+const RECENCY_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+function normalizeEntity(value) {
+    return value.trim().toLowerCase();
+}
+function parsePrimaryActors(value) {
+    if (!value || value.trim().length === 0) {
+        return [];
+    }
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const actorIds = [];
+    for (const item of parsed) {
+        if (typeof item === 'string') {
+            actorIds.push(item);
+            continue;
+        }
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+            const entityId = item.entity_id;
+            if (typeof entityId === 'string' && entityId.trim().length > 0) {
+                actorIds.push(entityId);
+            }
+        }
+    }
+    return actorIds;
+}
+function overlapCount(left, right) {
+    const rightSet = new Set(right.map(normalizeEntity).filter(Boolean));
+    const seen = new Set();
+    let count = 0;
+    for (const value of left) {
+        const normalized = normalizeEntity(value);
+        if (normalized.length === 0 || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        if (rightSet.has(normalized)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+function timestampMs(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function hasRecentActivity(row, observedAt) {
+    const observedMs = timestampMs(observedAt);
+    if (observedMs === null) {
+        return false;
+    }
+    const caseMs = timestampMs(row.last_activity_at) ?? timestampMs(row.compiled_at);
+    if (caseMs === null) {
+        return false;
+    }
+    return Math.abs(observedMs - caseMs) <= RECENCY_WINDOW_MS;
+}
+function wikiSimilarityByCase(adapter, queryEmbedding) {
+    const scores = new Map();
+    if (!queryEmbedding) {
+        return scores;
+    }
+    try {
+        const hits = (0, wiki_page_index_js_1.vectorSearchWikiPages)(adapter, queryEmbedding, 20);
+        for (const hit of hits) {
+            if (hit.record.page_type !== 'case' || !hit.record.case_id) {
+                continue;
+            }
+            const existing = scores.get(hit.record.case_id) ?? -Infinity;
+            if (hit.raw_score > existing) {
+                scores.set(hit.record.case_id, hit.raw_score);
+            }
+        }
+    }
+    catch {
+        return scores;
+    }
+    return scores;
+}
+function scoreCandidate(input) {
+    let score = 0;
+    const signals = [];
+    const actorOverlap = overlapCount(input.eventEntities, parsePrimaryActors(input.row.primary_actors));
+    if (actorOverlap > 0) {
+        const actorScore = Math.min(0.45 * actorOverlap, 0.9);
+        score += actorScore;
+        signals.push(`primary_actors_overlap:${actorOverlap}`);
+    }
+    if (input.wikiScore >= 0.82) {
+        score += 0.3;
+        signals.push(`wiki_embedding:${input.wikiScore.toFixed(3)}`);
+    }
+    else if (input.wikiScore >= 0.74) {
+        score += 0.18;
+        signals.push(`wiki_embedding:${input.wikiScore.toFixed(3)}`);
+    }
+    if (hasRecentActivity(input.row, input.observedAt)) {
+        score += 0.15;
+        signals.push('recent_activity');
+    }
+    return { score, signals };
+}
+function toMatch(case_id, score, signals) {
+    if (score >= ACTIVE_THRESHOLD) {
+        return {
+            case_id,
+            score: Number(score.toFixed(4)),
+            status: 'active',
+            reason: signals.join(','),
+        };
+    }
+    if (score >= CANDIDATE_THRESHOLD) {
+        return {
+            case_id,
+            score: Number(score.toFixed(4)),
+            status: 'candidate',
+            reason: signals.join(','),
+        };
+    }
+    return null;
+}
+function matchEventToExistingCases(adapter, input) {
+    const matcherAdapter = adapter;
+    if (input.explicit_case_id) {
+        const row = matcherAdapter
+            .prepare(`
+          SELECT case_id, status
+          FROM case_truth
+          WHERE case_id = ?
+        `)
+            .get(input.explicit_case_id);
+        if (!row) {
+            return {
+                kind: 'precompile_gap',
+                code: 'case.precompile_gap',
+                case_id: input.explicit_case_id,
+            };
+        }
+        if (!ACTIVE_CASE_STATUSES.has(row.status)) {
+            return [];
+        }
+        return [
+            {
+                case_id: row.case_id,
+                score: 1,
+                status: 'active',
+                reason: 'explicit_case_id',
+            },
+        ];
+    }
+    const rows = matcherAdapter
+        .prepare(`
+        SELECT case_id, title, primary_actors, current_wiki_path, last_activity_at,
+               compiled_at, status, confidence
+        FROM case_truth
+        WHERE status IN ('active','blocked')
+        ORDER BY COALESCE(last_activity_at, compiled_at, created_at) DESC
+        LIMIT 200
+      `)
+        .all();
+    const wikiScores = wikiSimilarityByCase(matcherAdapter, input.query_embedding);
+    const matches = [];
+    for (const row of rows) {
+        const { score, signals } = scoreCandidate({
+            row,
+            eventEntities: input.event_entities,
+            observedAt: input.observed_at,
+            wikiScore: wikiScores.get(row.case_id) ?? 0,
+        });
+        const match = toMatch(row.case_id, score, signals);
+        if (match) {
+            matches.push(match);
+        }
+    }
+    return matches.sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.case_id.localeCompare(right.case_id);
+    });
+}
+//# sourceMappingURL=membership-matcher.js.map

package/dist/cases/merge-split.d.ts

@@ -0,0 +1,61 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+export type MergeCaseErrorCode = 'case.confirmation_required' | 'case.merge_self' | 'case.merge_chain_cycle' | 'case.terminal_status';
+export interface MergeCasesInput {
+    loser_case_id: string;
+    survivor_case_id: string;
+    reason: string;
+    confirmed: true;
+    confirmed_by: string;
+    confirmation_summary: string;
+    now?: string;
+}
+export type MergeCasesResult = {
+    kind: 'merged';
+    loser_case_id: string;
+    survivor_case_id: string;
+    audit_event_id: string;
+} | {
+    kind: 'precompile_gap';
+    code: 'case.precompile_gap';
+    case_id: string;
+} | {
+    kind: 'rejected';
+    code: MergeCaseErrorCode;
+    message: string;
+};
+export interface SplitCaseChildPlan {
+    title: string;
+    current_wiki_path?: string | null;
+    membership_sources: Array<{
+        source_type: 'decision' | 'event' | 'observation' | 'artifact';
+        source_id: string;
+        remove_from_parent?: boolean;
+    }>;
+}
+export interface SplitCaseInput {
+    parent_case_id: string;
+    children: SplitCaseChildPlan[];
+    trusted_child_case_ids: string[];
+    reason: string;
+    confirmed: true;
+    confirmed_by: string;
+    confirmation_summary: string;
+    now?: string;
+}
+export type SplitCaseResult = {
+    kind: 'split';
+    parent_case_id: string;
+    child_case_ids: string[];
+    audit_event_id: string;
+} | {
+    kind: 'precompile_gap';
+    code: 'case.precompile_gap';
+    case_id: string;
+} | {
+    kind: 'rejected';
+    code: 'case.confirmation_required' | 'case.terminal_status' | 'case.split_requires_two_children' | 'case.child_id_not_trusted' | 'case.child_id_count_mismatch';
+    message: string;
+};
+export declare function mergeCases(adapter: DatabaseAdapter, input: MergeCasesInput): MergeCasesResult;
+export declare function splitCase(adapter: DatabaseAdapter, input: SplitCaseInput): SplitCaseResult;
+//# sourceMappingURL=merge-split.d.ts.map