@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/entities/read-identity.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveReadIdentity = resolveReadIdentity;
+exports.loadDecisionReadIdentityIndex = loadDecisionReadIdentityIndex;
+const db_manager_js_1 = require("../db-manager.js");
+function normalizeText(value) {
+    return value.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+function normalizeLooseText(value) {
+    return normalizeText(value ?? '')
+        .replace(/[_-]+/gu, ' ')
+        .replace(/[^\p{Letter}\p{Number}\s/]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function humanizeTopicSegment(segment) {
+    return segment.normalize('NFKC').replace(/[_]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+}
+function humanizeTopicLabel(topic) {
+    if (typeof topic !== 'string') {
+        return null;
+    }
+    const segments = topic
+        .split('/')
+        .map((segment) => humanizeTopicSegment(segment))
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        const fallback = humanizeTopicSegment(topic);
+        return fallback.length > 0 ? fallback : null;
+    }
+    return segments.join(' / ');
+}
+function hasProjectishSignal(label) {
+    return /(?:案件|相談|窓|民泊|project|room|board|launch|client|feedback|delivery)/iu.test(label ?? '');
+}
+function looksLikeMachineGeneratedLabel(label) {
+    return /^(slack|chatwork|telegram|line|kakao)(:|$)/iu.test(label ?? '');
+}
+function looksLikeParticipantLabel(label) {
+    if (!label) {
+        return false;
+    }
+    const trimmed = label.trim();
+    if (/^(kagemusha|system)$/iu.test(trimmed)) {
+        return true;
+    }
+    if (hasProjectishSignal(trimmed)) {
+        return false;
+    }
+    if (/[·,]/u.test(trimmed)) {
+        return true;
+    }
+    if (trimmed.length === 0 || trimmed.length > 20) {
+        return false;
+    }
+    if (/[A-Za-z0-9]/u.test(trimmed)) {
+        return false;
+    }
+    return /^[\p{Script=Hangul}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\s()]+$/u.test(trimmed);
+}
+function hasNonEmptyTopic(record) {
+    return typeof record.topic === 'string' && record.topic.trim().length > 0;
+}
+function sortCanonicalReadEntities(entities) {
+    return [...entities].sort((left, right) => {
+        if (left.kind !== right.kind) {
+            return left.kind.localeCompare(right.kind);
+        }
+        if (left.label !== right.label) {
+            return left.label.localeCompare(right.label);
+        }
+        return left.id.localeCompare(right.id);
+    });
+}
+function hasShadowConflict(record, primaryEntity) {
+    if (!hasNonEmptyTopic(record)) {
+        return false;
+    }
+    const summary = normalizeText(record.summary ?? '');
+    const label = normalizeText(primaryEntity.label);
+    if (!summary || !label) {
+        return false;
+    }
+    if (summary === label) {
+        return false;
+    }
+    if (summary.includes(label) || label.includes(summary)) {
+        return false;
+    }
+    return true;
+}
+function getLegacyTopic(record) {
+    return hasNonEmptyTopic(record) ? record.topic.trim() : null;
+}
+function getLegacyNamespace(record) {
+    const legacyTopic = getLegacyTopic(record);
+    if (!legacyTopic) {
+        return null;
+    }
+    const humanized = humanizeTopicSegment(legacyTopic.split('/')[0] ?? '');
+    if (normalizeLooseText(humanized) === 'entity') {
+        return null;
+    }
+    return humanized || null;
+}
+function selectDisplayEntity(entities, primaryEntity) {
+    return (entities.find((entity) => ['project', 'work_item', 'organization'].includes(entity.kind)) ??
+        primaryEntity);
+}
+function buildDisplaySubject(record, entities, primaryEntity) {
+    const preferredEntity = selectDisplayEntity(entities, primaryEntity);
+    const preferredLabel = preferredEntity.label?.trim();
+    const legacyNamespace = getLegacyNamespace(record);
+    const summary = record.summary?.trim();
+    if (summary && typeof record.topic === 'string' && record.topic.startsWith('entity/')) {
+        return summary;
+    }
+    if (legacyNamespace &&
+        preferredLabel &&
+        normalizeLooseText(preferredLabel) !== normalizeLooseText(legacyNamespace) &&
+        (looksLikeMachineGeneratedLabel(preferredLabel) || looksLikeParticipantLabel(preferredLabel))) {
+        return legacyNamespace;
+    }
+    if (preferredLabel && !looksLikeMachineGeneratedLabel(preferredLabel)) {
+        return preferredLabel;
+    }
+    if (legacyNamespace) {
+        return legacyNamespace;
+    }
+    return summary || humanizeTopicLabel(getLegacyTopic(record)) || preferredLabel || null;
+}
+function buildDisplayTopic(record, entities, primaryEntity) {
+    const summary = record.summary?.trim();
+    if (summary && typeof record.topic === 'string' && record.topic.startsWith('entity/')) {
+        return summary;
+    }
+    const preferredEntity = selectDisplayEntity(entities, primaryEntity);
+    const subjectLabel = preferredEntity.kind !== 'person' && preferredEntity.label.trim().length > 0
+        ? preferredEntity.label.trim()
+        : '';
+    const humanizedTopic = humanizeTopicLabel(getLegacyTopic(record));
+    if (!subjectLabel) {
+        return humanizedTopic || summary || null;
+    }
+    if (!humanizedTopic) {
+        return subjectLabel;
+    }
+    const normalizedSubject = normalizeLooseText(subjectLabel);
+    const normalizedTopic = normalizeLooseText(humanizedTopic);
+    const tokens = normalizedTopic.split(' ').filter((token) => token.length > 0);
+    const genericTokens = new Set(['spine', 'fb', 'fix', 'pdf', 'sd', 'ex', 'ar', 'r18', 'sp']);
+    const informativeTokens = tokens.filter((token) => !genericTokens.has(token) && !/^\d+$/u.test(token) && token.length > 1);
+    const lowSignalTopic = normalizedTopic.length === 0 || informativeTokens.length === 0;
+    if (lowSignalTopic || normalizedTopic === normalizedSubject) {
+        return subjectLabel;
+    }
+    return humanizedTopic;
+}
+function buildDisplaySuffix(record, entities, primaryEntity) {
+    const displaySubject = buildDisplaySubject(record, entities, primaryEntity);
+    const displayTopic = buildDisplayTopic(record, entities, primaryEntity);
+    if (!displaySubject || !displayTopic) {
+        return null;
+    }
+    const normalizedSubject = normalizeLooseText(displaySubject);
+    const normalizedTopic = normalizeLooseText(displayTopic);
+    if (!normalizedTopic || normalizedTopic === normalizedSubject) {
+        return null;
+    }
+    const subjectParts = displaySubject
+        .split('/')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const topicParts = displayTopic
+        .split('/')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (topicParts.length > 1 && subjectParts.length > 0) {
+        const firstTopicPart = topicParts[0] ?? '';
+        const firstSubjectPart = subjectParts[subjectParts.length - 1] ?? '';
+        if (normalizeLooseText(firstTopicPart) === normalizeLooseText(firstSubjectPart)) {
+            const suffix = topicParts.slice(1).join(' / ').trim();
+            return suffix.length > 0 ? suffix : null;
+        }
+    }
+    return displayTopic;
+}
+function resolveReadIdentity(record, entities) {
+    if (entities.length > 0) {
+        const sortedEntities = sortCanonicalReadEntities(entities);
+        const primaryEntity = sortedEntities[0];
+        return {
+            kind: 'canonical',
+            entities: sortedEntities,
+            primaryEntity,
+            legacyTopic: getLegacyTopic(record),
+            shadowConflict: hasShadowConflict(record, primaryEntity),
+            displaySubject: buildDisplaySubject(record, sortedEntities, primaryEntity),
+            displayTopic: buildDisplayTopic(record, sortedEntities, primaryEntity),
+            displaySuffix: buildDisplaySuffix(record, sortedEntities, primaryEntity),
+        };
+    }
+    if (hasNonEmptyTopic(record)) {
+        return {
+            kind: 'topic',
+            topic: record.topic.trim(),
+            displaySubject: null,
+            displayTopic: humanizeTopicLabel(record.topic),
+            displaySuffix: null,
+        };
+    }
+    return {
+        kind: 'raw',
+        label: record.summary.trim() || '<unknown>',
+        displaySubject: null,
+        displayTopic: record.summary.trim() || '<unknown>',
+        displaySuffix: null,
+    };
+}
+async function loadDecisionReadIdentityIndex(decisionIds) {
+    await (0, db_manager_js_1.initDB)();
+    const uniqueDecisionIds = Array.from(new Set(decisionIds
+        .filter((decisionId) => typeof decisionId === 'string')
+        .map((decisionId) => decisionId.trim())
+        .filter((decisionId) => decisionId.length > 0)));
+    const index = new Map();
+    if (uniqueDecisionIds.length === 0) {
+        return index;
+    }
+    const placeholders = uniqueDecisionIds.map(() => '?').join(', ');
+    const rows = (0, db_manager_js_1.getAdapter)()
+        .prepare(`
+        SELECT
+          des.decision_id,
+          n.id AS entity_id,
+          n.preferred_label AS entity_label,
+          n.kind AS entity_kind
+        FROM decision_entity_sources des
+        JOIN entity_lineage_links l
+          ON l.entity_observation_id = des.entity_observation_id
+         AND l.status = 'active'
+        JOIN entity_nodes n
+          ON n.id = l.canonical_entity_id
+        WHERE des.decision_id IN (${placeholders})
+          AND n.status = 'active'
+          AND n.merged_into IS NULL
+        GROUP BY des.decision_id, n.id, n.preferred_label, n.kind
+      `)
+        .all(...uniqueDecisionIds);
+    for (const row of rows) {
+        const existing = index.get(row.decision_id) ?? [];
+        existing.push({
+            id: row.entity_id,
+            label: row.entity_label,
+            kind: row.entity_kind,
+        });
+        index.set(row.decision_id, existing);
+    }
+    for (const [decisionId, entities] of index.entries()) {
+        index.set(decisionId, sortCanonicalReadEntities(entities));
+    }
+    return index;
+}
+//# sourceMappingURL=read-identity.js.map

package/dist/entities/recall-bridge.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryRecord, MemoryScopeRef } from '../memory/types.js';
+export declare function queryCanonicalEntities(query: string, scopes: MemoryScopeRef[], options?: {
+    limit?: number;
+}): Promise<MemoryRecord[]>;
+//# sourceMappingURL=recall-bridge.d.ts.map

package/dist/entities/recall-bridge.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryCanonicalEntities = queryCanonicalEntities;
+const db_manager_js_1 = require("../db-manager.js");
+const projection_js_1 = require("./projection.js");
+const read_identity_js_1 = require("./read-identity.js");
+const store_js_1 = require("./store.js");
+function mapNode(row) {
+    return {
+        id: String(row.id),
+        kind: row.kind,
+        preferred_label: String(row.preferred_label),
+        status: row.status,
+        scope_kind: typeof row.scope_kind === 'string' ? row.scope_kind : null,
+        scope_id: typeof row.scope_id === 'string' ? row.scope_id : null,
+        merged_into: typeof row.merged_into === 'string' ? row.merged_into : null,
+        created_at: Number(row.created_at),
+        updated_at: Number(row.updated_at),
+    };
+}
+function mapAlias(row) {
+    return {
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        label: String(row.label),
+        normalized_label: String(row.normalized_label),
+        lang: typeof row.lang === 'string' ? row.lang : null,
+        script: typeof row.script === 'string' ? row.script : null,
+        label_type: row.label_type,
+        source_type: String(row.source_type),
+        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
+        confidence: typeof row.confidence === 'number' ? row.confidence : null,
+        status: row.status,
+        created_at: Number(row.created_at),
+    };
+}
+function mapTimeline(row) {
+    return {
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        event_type: String(row.event_type),
+        valid_from: typeof row.valid_from === 'number' ? row.valid_from : null,
+        valid_to: typeof row.valid_to === 'number' ? row.valid_to : null,
+        observed_at: typeof row.observed_at === 'number' ? row.observed_at : null,
+        source_ref: typeof row.source_ref === 'string' ? row.source_ref : null,
+        summary: String(row.summary),
+        details: typeof row.details === 'string' ? row.details : null,
+        created_at: Number(row.created_at),
+    };
+}
+function escapeLikeQuery(query) {
+    return query.replace(/[\\%_]/g, '\\$&');
+}
+async function queryCanonicalEntities(query, scopes, options = {}) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const escapedQuery = escapeLikeQuery(query);
+    // Match aliases and labels regardless of whether the owning node is merged,
+    // then chain-walk each match to its canonical terminal. Without this,
+    // searching by the old name of a merged entity returns nothing because the
+    // filter `n.status='active' AND n.merged_into IS NULL` would drop the
+    // source row. Matches the read-time chain-walking approach in the canonical
+    // entity ontology implementation plan.
+    const matchedRows = adapter
+        .prepare(`
+        SELECT DISTINCT n.id AS matched_id
+        FROM entity_nodes n
+        LEFT JOIN entity_aliases a ON a.entity_id = n.id
+        LEFT JOIN entity_lineage_links l ON l.canonical_entity_id = n.id AND l.status = 'active'
+        LEFT JOIN entity_observations o ON o.id = l.entity_observation_id
+        WHERE (
+          lower(n.preferred_label) LIKE '%' || lower(?) || '%' ESCAPE '\\'
+          OR lower(COALESCE(a.label, '')) LIKE '%' || lower(?) || '%' ESCAPE '\\'
+          OR lower(COALESCE(o.surface_form, '')) LIKE '%' || lower(?) || '%' ESCAPE '\\'
+        )
+      `)
+        .all(escapedQuery, escapedQuery, escapedQuery);
+    const canonicalIdSet = new Set();
+    for (const match of matchedRows) {
+        try {
+            canonicalIdSet.add((0, store_js_1.resolveCanonicalEntityId)(adapter, match.matched_id));
+        }
+        catch (err) {
+            // Cycle or missing node — skip this match rather than poison the whole
+            // recall. Merge integrity errors are surfaced elsewhere (the review
+            // handler 409 path) where the user can actually act on them.
+            if (!(err instanceof store_js_1.EntityMergeError)) {
+                throw err;
+            }
+        }
+    }
+    if (canonicalIdSet.size === 0) {
+        return [];
+    }
+    const canonicalIds = Array.from(canonicalIdSet);
+    const placeholders = canonicalIds.map(() => '?').join(', ');
+    const rows = adapter
+        .prepare(`
+        SELECT *
+        FROM entity_nodes
+        WHERE id IN (${placeholders})
+          AND status = 'active'
+          AND merged_into IS NULL
+        ORDER BY updated_at DESC
+      `)
+        .all(...canonicalIds);
+    const scopedRows = scopes.length === 0
+        ? rows
+        : rows.filter((row) => 
+        // Fix 2 part B (P0): globally-scoped entities are not bound to
+        // any narrower scope and must surface in every scoped query.
+        // Without this passthrough, switching person observations from
+        // channel-scope to global-scope (Fix 2 part A in
+        // history-extractor.ts) would make persons invisible to scoped
+        // recall callers, breaking the time-travel use case the fix is
+        // meant to enable. scope_id is intentionally not compared for
+        // globals — the global predicate is `scope_kind='global'` alone.
+        row.scope_kind === 'global' ||
+            scopes.some((scope) => scope.kind === row.scope_kind && row.scope_id === scope.id));
+    const limitedRows = scopedRows.slice(0, options.limit ?? 10);
+    const nodeLookup = Object.fromEntries(limitedRows.map((row) => [String(row.id), mapNode(row)]));
+    const entityIds = limitedRows.map((row) => String(row.id));
+    const aliasesByEntity = new Map();
+    const latestTimelineByEntity = new Map();
+    if (entityIds.length > 0) {
+        const placeholders = entityIds.map(() => '?').join(', ');
+        const aliasRows = adapter
+            .prepare(`
+        SELECT * FROM entity_aliases
+        WHERE entity_id IN (${placeholders})
+        ORDER BY entity_id ASC, created_at ASC
+      `)
+            .all(...entityIds);
+        for (const row of aliasRows) {
+            const alias = mapAlias(row);
+            const existing = aliasesByEntity.get(alias.entity_id) ?? [];
+            existing.push(alias);
+            aliasesByEntity.set(alias.entity_id, existing);
+        }
+        const timelineRows = adapter
+            .prepare(`
+        SELECT *
+        FROM (
+          SELECT *,
+                 ROW_NUMBER() OVER (
+                   PARTITION BY entity_id
+                   ORDER BY COALESCE(observed_at, created_at) DESC
+                 ) AS row_num
+          FROM entity_timeline_events
+          WHERE entity_id IN (${placeholders})
+        )
+        WHERE row_num = 1
+      `)
+            .all(...entityIds);
+        for (const row of timelineRows) {
+            const timeline = mapTimeline(row);
+            latestTimelineByEntity.set(timeline.entity_id, timeline);
+        }
+    }
+    const result = [];
+    for (const row of limitedRows) {
+        const node = mapNode(row);
+        const projected = (0, projection_js_1.projectEntityToRecallSummary)(node, aliasesByEntity.get(node.id) ?? [], latestTimelineByEntity.get(node.id) ?? null, { nodeLookup });
+        projected.read_identity = (0, read_identity_js_1.resolveReadIdentity)(projected, [
+            { id: node.id, label: node.preferred_label, kind: node.kind },
+        ]);
+        result.push(projected);
+    }
+    return result;
+}
+//# sourceMappingURL=recall-bridge.js.map

package/dist/entities/resolution-engine.d.ts

@@ -0,0 +1,15 @@
+import type { EntityMergeAction, EntityObservation, EntityResolutionCandidate } from './types.js';
+export interface ResolutionDecision {
+    candidate: EntityResolutionCandidate;
+    decision: 'auto_merge' | 'review';
+    reason: string;
+    actions: EntityMergeAction[];
+}
+export declare function shouldAutoMerge(result: ResolutionDecision): boolean;
+export declare function buildReviewReason(result: ResolutionDecision): string;
+export declare function evaluateResolutionCandidate(input: {
+    candidate: EntityResolutionCandidate;
+    left: EntityObservation;
+    right: EntityObservation;
+}): ResolutionDecision;
+//# sourceMappingURL=resolution-engine.d.ts.map

package/dist/entities/resolution-engine.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldAutoMerge = shouldAutoMerge;
+exports.buildReviewReason = buildReviewReason;
+exports.evaluateResolutionCandidate = evaluateResolutionCandidate;
+const errors_js_1 = require("./errors.js");
+function isCrossLanguage(left, right) {
+    return Boolean(left.lang && right.lang && left.lang !== right.lang);
+}
+function shouldAutoMerge(result) {
+    return result.decision === 'auto_merge';
+}
+function buildReviewReason(result) {
+    return result.reason;
+}
+function evaluateResolutionCandidate(input) {
+    const { candidate, left, right } = input;
+    if (left.entity_kind_hint &&
+        right.entity_kind_hint &&
+        left.entity_kind_hint !== right.entity_kind_hint) {
+        throw new errors_js_1.OntologyViolationError({
+            left_entity_kind: left.entity_kind_hint,
+            right_entity_kind: right.entity_kind_hint,
+            candidate_id: candidate.id,
+        });
+    }
+    const sameNormalized = left.normalized_form === right.normalized_form;
+    const exactStructural = candidate.score_structural >= 1 && sameNormalized;
+    const crossLanguage = isCrossLanguage(left, right);
+    if (exactStructural && !crossLanguage) {
+        return {
+            candidate,
+            decision: 'auto_merge',
+            reason: 'Exact structural match with no cross-language ambiguity.',
+            actions: [
+                {
+                    id: `merge_${candidate.id}`,
+                    action_type: 'merge',
+                    source_entity_id: candidate.left_ref,
+                    target_entity_id: candidate.right_ref,
+                    candidate_id: candidate.id,
+                    actor_type: 'system',
+                    actor_id: 'resolution-engine',
+                    reason: 'Exact structural match with no cross-language ambiguity.',
+                    evidence_json: JSON.stringify({
+                        score_structural: candidate.score_structural,
+                        normalized_form: left.normalized_form,
+                    }),
+                    created_at: Date.now(),
+                },
+            ],
+        };
+    }
+    if (crossLanguage && candidate.score_embedding > 0) {
+        return {
+            candidate,
+            decision: 'review',
+            reason: 'High-similarity cross-language candidate requires human review.',
+            actions: [],
+        };
+    }
+    return {
+        candidate,
+        decision: 'review',
+        reason: 'Candidate requires manual review before merge.',
+        actions: [],
+    };
+}
+//# sourceMappingURL=resolution-engine.js.map

package/dist/entities/rollback-preview.d.ts

@@ -0,0 +1,39 @@
+import { type EntityStoreAdapter } from './store.js';
+export interface RollbackPreviewInput {
+    entityId: string;
+    mergeActionId?: string;
+    observationId?: string;
+    maxAffectedRows?: number;
+}
+export interface RollbackPreviewEntityChange {
+    entity_id: string;
+    label: string;
+    status_after: 'active' | 'merged';
+    active_lineage_after: number;
+    summary: string;
+}
+export interface RollbackPreviewMemoryChange {
+    id: string;
+    topic: string;
+    summary: string;
+    created_at: number;
+}
+export interface RollbackPreviewMetricMovement {
+    metric: 'false_merge_rate' | 'projection_fragmentation_rate';
+    direction: 'increase' | 'decrease';
+    reason: string;
+}
+export interface RollbackPreviewResult {
+    entity_id: string;
+    merge_action_id: string | null;
+    preview_unavailable: boolean;
+    history_incomplete: boolean;
+    truncated: boolean;
+    changed_entities: RollbackPreviewEntityChange[];
+    changed_memories: RollbackPreviewMemoryChange[];
+    metric_movement: RollbackPreviewMetricMovement[];
+}
+export declare function previewEntityRollback(input: RollbackPreviewInput, options?: {
+    adapter?: EntityStoreAdapter;
+}): Promise<RollbackPreviewResult>;
+//# sourceMappingURL=rollback-preview.d.ts.map