@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/entities/rollback-preview.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewEntityRollback = previewEntityRollback;
+const db_manager_js_1 = require("../db-manager.js");
+const projection_js_1 = require("./projection.js");
+const store_js_1 = require("./store.js");
+const lineage_store_js_1 = require("./lineage-store.js");
+function unavailableResult(entityId, mergeActionId, historyIncomplete) {
+    return {
+        entity_id: entityId,
+        merge_action_id: mergeActionId,
+        preview_unavailable: true,
+        history_incomplete: historyIncomplete,
+        truncated: false,
+        changed_entities: [],
+        changed_memories: [],
+        metric_movement: [],
+    };
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values.filter((value) => Boolean(value))));
+}
+function getLatestTimeline(adapter, entityId) {
+    const row = adapter
+        .prepare(`
+        SELECT *
+        FROM entity_timeline_events
+        WHERE entity_id = ?
+        ORDER BY COALESCE(observed_at, created_at) DESC
+        LIMIT 1
+      `)
+        .get(entityId);
+    if (!row) {
+        return null;
+    }
+    return {
+        id: String(row.id),
+        entity_id: String(row.entity_id),
+        event_type: row.event_type,
+        role: typeof row.role === 'string' ? row.role : null,
+        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),
+    };
+}
+const DEFAULT_MAX_AFFECTED_ROWS = 50;
+function normalizeMaxAffectedRows(input) {
+    return Math.max(1, input.maxAffectedRows ?? DEFAULT_MAX_AFFECTED_ROWS);
+}
+function projectLabel(adapter, node) {
+    const summary = (0, projection_js_1.projectEntityToRecallSummary)(node, (0, store_js_1.listEntityAliases)(node.id, adapter), getLatestTimeline(adapter, node.id), { nodeLookup: { [node.id]: node } });
+    return summary.summary;
+}
+function loadMergeAction(adapter, entityId, mergeActionId) {
+    const sql = mergeActionId
+        ? `
+        SELECT id, source_entity_id, target_entity_id, created_at
+        FROM entity_merge_actions
+        WHERE id = ?
+          AND (source_entity_id = ? OR target_entity_id = ?)
+        LIMIT 1
+      `
+        : `
+        SELECT id, source_entity_id, target_entity_id, created_at
+        FROM entity_merge_actions
+        WHERE target_entity_id = ?
+        ORDER BY created_at DESC
+        LIMIT 1
+      `;
+    const row = (mergeActionId
+        ? adapter.prepare(sql).get(mergeActionId, entityId, entityId)
+        : adapter.prepare(sql).get(entityId));
+    return row ?? null;
+}
+function resolveMergePreviewRows(input) {
+    let removedRows = input.targetActive.filter((row) => row.source_entity_id === input.sourceEntityId &&
+        (!input.mergeActionId || row.review_action_id === input.mergeActionId));
+    const removedObservationIds = new Set(removedRows.map((row) => row.entity_observation_id));
+    const restoredRows = input.sourceHistory.filter((row) => row.status === 'superseded' &&
+        (!input.mergeActionId ||
+            row.review_action_id === input.mergeActionId ||
+            removedObservationIds.has(row.entity_observation_id)));
+    if (removedRows.length === 0 && restoredRows.length > 0) {
+        const restorableObservationIds = new Set(restoredRows.map((row) => row.entity_observation_id));
+        removedRows = input.targetActive.filter((row) => restorableObservationIds.has(row.entity_observation_id) &&
+            (!input.mergeActionId || row.review_action_id === input.mergeActionId));
+    }
+    return { restoredRows, removedRows };
+}
+function loadChangedMemories(adapter, observationIds) {
+    if (observationIds.length === 0) {
+        return [];
+    }
+    const placeholders = observationIds.map(() => '?').join(', ');
+    const rows = adapter
+        .prepare(`
+        SELECT DISTINCT d.id, d.topic, d.summary, d.created_at
+        FROM decision_entity_sources des
+        JOIN decisions d ON d.id = des.decision_id
+        WHERE des.entity_observation_id IN (${placeholders})
+        ORDER BY d.created_at DESC
+      `)
+        .all(...observationIds);
+    return rows.map((row) => ({
+        id: row.id,
+        topic: row.topic,
+        summary: row.summary ?? row.topic,
+        created_at: row.created_at,
+    }));
+}
+function buildMetricMovement(sourceLabel) {
+    return [
+        {
+            metric: 'false_merge_rate',
+            direction: 'decrease',
+            reason: `Splitting ${sourceLabel} back out would likely reduce false merge pressure.`,
+        },
+        {
+            metric: 'projection_fragmentation_rate',
+            direction: 'increase',
+            reason: `Reactivating a second canonical entity likely increases projection fragmentation.`,
+        },
+    ];
+}
+async function previewMergeRollback(adapter, input, mergeAction) {
+    const sourceNode = (0, store_js_1.getEntityNode)(mergeAction.source_entity_id, adapter);
+    const targetNode = (0, store_js_1.getEntityNode)(mergeAction.target_entity_id, adapter);
+    if (!sourceNode || !targetNode) {
+        return unavailableResult(input.entityId, mergeAction.id, true);
+    }
+    const sourceHistory = await (0, lineage_store_js_1.listEntityLineageHistory)(sourceNode.id, adapter);
+    const targetActive = await (0, lineage_store_js_1.listActiveEntityLineage)(targetNode.id, adapter);
+    const { restoredRows, removedRows } = resolveMergePreviewRows({
+        sourceHistory,
+        targetActive,
+        sourceEntityId: sourceNode.id,
+        mergeActionId: input.mergeActionId,
+    });
+    if (restoredRows.length === 0 || removedRows.length === 0) {
+        return unavailableResult(input.entityId, mergeAction.id, true);
+    }
+    const affectedObservationIds = uniqueStrings([
+        ...restoredRows.map((row) => row.entity_observation_id),
+        ...removedRows.map((row) => row.entity_observation_id),
+    ]);
+    const allChangedMemories = loadChangedMemories(adapter, affectedObservationIds);
+    const maxAffectedRows = normalizeMaxAffectedRows(input);
+    const truncated = allChangedMemories.length > maxAffectedRows;
+    return {
+        entity_id: input.entityId,
+        merge_action_id: mergeAction.id,
+        preview_unavailable: false,
+        history_incomplete: false,
+        truncated,
+        changed_entities: [
+            {
+                entity_id: sourceNode.id,
+                label: sourceNode.preferred_label,
+                status_after: 'active',
+                active_lineage_after: restoredRows.length,
+                summary: projectLabel(adapter, { ...sourceNode, status: 'active', merged_into: null }),
+            },
+            {
+                entity_id: targetNode.id,
+                label: targetNode.preferred_label,
+                status_after: 'active',
+                active_lineage_after: Math.max(0, targetActive.length - removedRows.length),
+                summary: projectLabel(adapter, targetNode),
+            },
+        ],
+        changed_memories: allChangedMemories.slice(0, maxAffectedRows),
+        metric_movement: buildMetricMovement(sourceNode.preferred_label),
+    };
+}
+async function previewObservationDetach(adapter, input) {
+    const activeTarget = await (0, lineage_store_js_1.listActiveEntityLineage)(input.entityId, adapter);
+    const targetNode = (0, store_js_1.getEntityNode)(input.entityId, adapter);
+    if (!targetNode) {
+        return unavailableResult(input.entityId, null, false);
+    }
+    const row = activeTarget.find((candidate) => candidate.entity_observation_id === input.observationId);
+    if (!row) {
+        return unavailableResult(input.entityId, null, false);
+    }
+    const changedMemories = loadChangedMemories(adapter, [row.entity_observation_id]);
+    const maxAffectedRows = normalizeMaxAffectedRows(input);
+    return {
+        entity_id: input.entityId,
+        merge_action_id: null,
+        preview_unavailable: false,
+        history_incomplete: false,
+        truncated: changedMemories.length > maxAffectedRows,
+        changed_entities: [
+            {
+                entity_id: targetNode.id,
+                label: targetNode.preferred_label,
+                status_after: 'active',
+                active_lineage_after: Math.max(0, activeTarget.length - 1),
+                summary: projectLabel(adapter, targetNode),
+            },
+        ],
+        changed_memories: changedMemories.slice(0, maxAffectedRows),
+        metric_movement: [
+            {
+                metric: 'false_merge_rate',
+                direction: 'decrease',
+                reason: 'Removing one supporting observation may reduce merge confidence for the current entity.',
+            },
+            {
+                metric: 'projection_fragmentation_rate',
+                direction: 'increase',
+                reason: 'Detaching one observation may increase fragmentation if it needs a separate entity later.',
+            },
+        ],
+    };
+}
+async function previewEntityRollback(input, options = {}) {
+    if (!options.adapter) {
+        await (0, db_manager_js_1.initDB)();
+    }
+    const adapter = options.adapter ?? (0, db_manager_js_1.getAdapter)();
+    if (input.observationId) {
+        return previewObservationDetach(adapter, input);
+    }
+    const mergeAction = loadMergeAction(adapter, input.entityId, input.mergeActionId);
+    if (!mergeAction) {
+        return unavailableResult(input.entityId, input.mergeActionId ?? null, false);
+    }
+    return previewMergeRollback(adapter, input, mergeAction);
+}
+//# sourceMappingURL=rollback-preview.js.map

package/dist/entities/source-locator.d.ts

@@ -0,0 +1,3 @@
+export type SourceLocatorKind = 'db' | 'file' | 'url' | 'connector' | 'unknown';
+export declare function detectSourceLocatorKind(locator: string | null | undefined): SourceLocatorKind;
+//# sourceMappingURL=source-locator.d.ts.map

package/dist/entities/source-locator.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSourceLocatorKind = detectSourceLocatorKind;
+function detectSourceLocatorKind(locator) {
+    if (typeof locator !== 'string' || locator.trim().length === 0) {
+        return 'unknown';
+    }
+    const trimmed = locator.trim();
+    const normalized = trimmed.toLowerCase();
+    if (normalized.startsWith('http://') || normalized.startsWith('https://')) {
+        return 'url';
+    }
+    if (normalized.startsWith('file://')) {
+        return 'file';
+    }
+    if (normalized.startsWith('drive://') ||
+        normalized.startsWith('gmail://') ||
+        normalized.startsWith('calendar://') ||
+        normalized.startsWith('sheets://')) {
+        return 'connector';
+    }
+    if (normalized.endsWith('.db') ||
+        normalized.includes('/raw.db') ||
+        normalized.includes('\\raw.db')) {
+        return 'db';
+    }
+    if (trimmed.startsWith('/') || trimmed.startsWith('~/') || /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return 'file';
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=source-locator.js.map

package/dist/entities/store.d.ts

@@ -0,0 +1,75 @@
+import { type EntityAlias, type EntityNode, type EntityObservation, type EntityTimelineEvent } from './types.js';
+export interface EntityStoreAdapter {
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            changes: number;
+            lastInsertRowid: number | bigint;
+        };
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+}
+export declare class EntityMergeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+type CreateEntityNodeInput = Omit<EntityNode, 'created_at' | 'updated_at'>;
+type AttachEntityAliasInput = Omit<EntityAlias, 'created_at'>;
+type UpsertEntityObservationInput = Omit<EntityObservation, 'created_at'>;
+type AppendEntityTimelineEventInput = {
+    event: Omit<EntityTimelineEvent, 'id' | 'created_at'> & {
+        id?: string;
+        created_at?: number;
+    };
+    adapter?: EntityStoreAdapter;
+};
+export interface UpsertEntityObservationResult {
+    id: string;
+    created: boolean;
+}
+export declare function parseObservationRow(row: Record<string, unknown>): EntityObservation;
+export declare function createEntityNode(input: CreateEntityNodeInput): Promise<EntityNode>;
+export declare function getEntityNode(id: string, adapter?: EntityStoreAdapter): EntityNode | null;
+export declare function listEntityNodes(): EntityNode[];
+export declare function attachEntityAlias(input: AttachEntityAliasInput): Promise<EntityAlias>;
+export declare function listEntityAliases(entityId: string, adapter?: EntityStoreAdapter): EntityAlias[];
+export declare function upsertEntityObservation(input: UpsertEntityObservationInput): Promise<EntityObservation>;
+export declare function upsertEntityObservations(inputs: UpsertEntityObservationInput[]): Promise<UpsertEntityObservationResult[]>;
+export declare function appendEntityTimelineEvent(input: AppendEntityTimelineEventInput): Promise<EntityTimelineEvent>;
+/**
+ * Walks the `entity_nodes.merged_into` chain from the given id and returns the
+ * terminal (unmerged) entity id. Detects cycles and caps depth. Read-only.
+ *
+ * Matches the read-time chain-walking approach described in the canonical
+ * entity ontology implementation plan.
+ */
+export declare function resolveCanonicalEntityId(adapter: EntityStoreAdapter, id: string): string;
+export interface MergeEntityNodesInput {
+    adapter: EntityStoreAdapter;
+    source_id: string;
+    target_id: string;
+    actor_type: 'system' | 'user' | 'agent';
+    actor_id: string;
+    reason: string;
+    candidate_id: string | null;
+    evidence_json: string;
+}
+export interface MergeEntityNodesResult {
+    merge_action_id: string;
+    timeline_event_id: string;
+    merged_at: number;
+}
+/**
+ * Marks `source_id` as merged into `target_id`, emits a timeline event, and
+ * inserts the entity_merge_actions audit row with both entity IDs populated.
+ *
+ * Intentionally NOT wrapped in its own transaction — the caller is expected
+ * to wrap the call in `adapter.transaction(...)` so the candidate status
+ * update and this merge land atomically (Policy B1, hard transaction).
+ *
+ * Validates: source != target, both exist, both active/unmerged, same kind,
+ * same scope. Throws `EntityMergeError` with a stable `code` on any violation.
+ */
+export declare function mergeEntityNodes(input: MergeEntityNodesInput): MergeEntityNodesResult;
+export {};
+//# sourceMappingURL=store.d.ts.map