@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/entities/errors.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaseMergeChainCycleError = exports.AuditRunInProgressError = exports.CandidateStaleError = exports.EntityLabelMissingError = exports.MergeTargetStaleError = exports.OntologyViolationError = exports.EmbeddingUnavailableError = exports.InvalidEntityLabelError = exports.EntityError = void 0;
+class EntityError extends Error {
+    context;
+    hint;
+    constructor(opts) {
+        super(opts.message);
+        this.name = new.target.name;
+        this.context = opts.context ?? {};
+        this.hint = opts.hint;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+    toErrorEnvelope() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                hint: this.hint,
+                doc_url: `docs/operations/entity-substrate-runbook.md${this.doc_section}`,
+            },
+        };
+    }
+}
+exports.EntityError = EntityError;
+class InvalidEntityLabelError extends EntityError {
+    code = 'entity.invalid_label';
+    doc_section = '#invalid-label';
+    constructor(context = {}) {
+        super({
+            message: 'Invalid entity label.',
+            context,
+            hint: 'Provide a non-empty entity label before normalization.',
+        });
+    }
+}
+exports.InvalidEntityLabelError = InvalidEntityLabelError;
+class EmbeddingUnavailableError extends EntityError {
+    code = 'entity.embedding_unavailable';
+    doc_section = '#embedding-unavailable';
+    constructor(context = {}) {
+        super({
+            message: 'Entity embedding model is unavailable.',
+            context,
+            hint: 'Verify the embedding model is installed and reachable before generating candidates.',
+        });
+    }
+}
+exports.EmbeddingUnavailableError = EmbeddingUnavailableError;
+class OntologyViolationError extends EntityError {
+    code = 'entity.ontology_violation';
+    doc_section = '#ontology-violation';
+    constructor(context = {}) {
+        super({
+            message: 'Entity operation violates ontology constraints.',
+            context,
+            hint: 'Check entity kinds and relation signatures before applying the change.',
+        });
+    }
+}
+exports.OntologyViolationError = OntologyViolationError;
+class MergeTargetStaleError extends EntityError {
+    code = 'entity.merge_target_stale';
+    doc_section = '#merge-target-stale';
+    constructor(context = {}) {
+        super({
+            message: 'Merge target is stale.',
+            context,
+            hint: 'Reload the target entity state and retry the merge against the latest version.',
+        });
+    }
+}
+exports.MergeTargetStaleError = MergeTargetStaleError;
+class EntityLabelMissingError extends EntityError {
+    code = 'entity.label_missing';
+    doc_section = '#label-missing';
+    constructor(context = {}) {
+        super({
+            message: 'Canonical entity label is missing.',
+            context,
+            hint: 'Set a preferred label before projecting or displaying the entity.',
+        });
+    }
+}
+exports.EntityLabelMissingError = EntityLabelMissingError;
+class CandidateStaleError extends EntityError {
+    code = 'entity.candidate_stale';
+    doc_section = '#candidate-stale';
+    constructor(context = {}) {
+        super({
+            message: 'Resolution candidate is stale.',
+            context,
+            hint: 'Refresh the candidate list and review the latest evidence before acting.',
+        });
+    }
+}
+exports.CandidateStaleError = CandidateStaleError;
+class AuditRunInProgressError extends EntityError {
+    code = 'entity.audit_run_in_progress';
+    doc_section = '#audit-run-in-progress';
+    constructor(context = {}) {
+        super({
+            message: 'Another entity audit run is already in progress.',
+            context,
+            hint: 'Wait for the current audit to finish or inspect its run status before starting a new one.',
+        });
+    }
+}
+exports.AuditRunInProgressError = AuditRunInProgressError;
+class CaseMergeChainCycleError extends EntityError {
+    code = 'case.merge_chain_cycle';
+    doc_section = '#case-merge-chain-cycle';
+    constructor(context) {
+        super({
+            message: `Case merge chain cycle detected at depth ${context.detected_at_depth} starting from case_id=${context.case_id}. Chain=${context.chain.join(' -> ')}.`,
+            context,
+            hint: 'Inspect case_truth.canonical_case_id links and remove the cycle before retrying.',
+        });
+    }
+}
+exports.CaseMergeChainCycleError = CaseMergeChainCycleError;
+//# sourceMappingURL=errors.js.map

package/dist/entities/exact-merge-backfill.d.ts

@@ -0,0 +1,11 @@
+export interface ExactMergeBackfillOptions {
+    dryRun?: boolean;
+}
+export interface ExactMergeBackfillResult {
+    groups: number;
+    merged: number;
+    incomplete: number;
+    skipped: number;
+}
+export declare function backfillExactDuplicateCanonicals(opts?: ExactMergeBackfillOptions): Promise<ExactMergeBackfillResult>;
+//# sourceMappingURL=exact-merge-backfill.d.ts.map

package/dist/entities/exact-merge-backfill.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillExactDuplicateCanonicals = backfillExactDuplicateCanonicals;
+const db_manager_js_1 = require("../db-manager.js");
+const store_js_1 = require("./store.js");
+const lineage_store_js_1 = require("./lineage-store.js");
+function normalizeExactLabel(input) {
+    return input.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+function buildExactGroupKey(row) {
+    if (row.normalized_form) {
+        return {
+            key: JSON.stringify([row.kind, row.scope_kind, row.scope_id ?? '', row.normalized_form]),
+            fromObservation: true,
+        };
+    }
+    const fallback = normalizeExactLabel(row.preferred_label);
+    if (!fallback) {
+        return null;
+    }
+    return {
+        key: JSON.stringify([row.kind, row.scope_kind, row.scope_id ?? '', fallback]),
+        fromObservation: false,
+    };
+}
+function compareRows(left, right) {
+    if (left.created_at !== right.created_at) {
+        return left.created_at - right.created_at;
+    }
+    return left.id.localeCompare(right.id);
+}
+function runAdapterTransaction(adapter, fn) {
+    const result = adapter.transaction(fn);
+    return typeof result === 'function' ? result() : result;
+}
+function requireTransactionAdapter(adapter) {
+    if (!('transaction' in adapter) || typeof adapter.transaction !== 'function') {
+        throw new Error('exact-merge-backfill requires adapter.transaction');
+    }
+    return adapter;
+}
+function mergeAndAdoptLineage(input) {
+    const mergeResult = (0, store_js_1.mergeEntityNodes)({
+        adapter: input.adapter,
+        source_id: input.source.id,
+        target_id: input.target.id,
+        actor_type: 'system',
+        actor_id: 'exact-duplicate-backfill',
+        reason: 'Exact duplicate canonical backfill',
+        candidate_id: null,
+        evidence_json: JSON.stringify({
+            strategy: 'exact_duplicate_backfill',
+            group_key: input.groupKey,
+            normalized_form: input.source.normalized_form,
+            target_id: input.target.id,
+        }),
+    });
+    (0, lineage_store_js_1.adoptLineageAfterMergeSync)({
+        adapter: input.adapter,
+        source_entity_id: input.source.id,
+        target_entity_id: input.target.id,
+        candidate_id: null,
+        review_action_id: mergeResult.merge_action_id,
+    });
+}
+async function backfillExactDuplicateCanonicals(opts = {}) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const dryRun = opts.dryRun === true;
+    let groups = 0;
+    let merged = 0;
+    let incomplete = 0;
+    let skipped = 0;
+    const rows = adapter
+        .prepare(`
+        SELECT
+          n.id,
+          n.kind,
+          n.preferred_label,
+          n.scope_kind,
+          n.scope_id,
+          n.created_at,
+          MIN(o.normalized_form) AS normalized_form
+        FROM entity_nodes n
+        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 n.status = 'active'
+          AND n.merged_into IS NULL
+        GROUP BY n.id, n.kind, n.preferred_label, n.scope_kind, n.scope_id, n.created_at
+      `)
+        .all();
+    const grouped = new Map();
+    const fallbackRows = new Set();
+    for (const row of rows) {
+        const keyInfo = buildExactGroupKey(row);
+        if (!keyInfo) {
+            incomplete += 1;
+            continue;
+        }
+        if (!keyInfo.fromObservation) {
+            fallbackRows.add(row.id);
+        }
+        const bucket = grouped.get(keyInfo.key) ?? [];
+        bucket.push(row);
+        grouped.set(keyInfo.key, bucket);
+    }
+    for (const bucket of grouped.values()) {
+        if (bucket.length >= 2) {
+            continue;
+        }
+        for (const row of bucket) {
+            if (fallbackRows.has(row.id)) {
+                incomplete += 1;
+            }
+        }
+    }
+    for (const [groupKey, bucket] of grouped.entries()) {
+        if (bucket.length < 2) {
+            continue;
+        }
+        groups += 1;
+        const sorted = [...bucket].sort(compareRows);
+        const target = sorted[0];
+        const sources = sorted.slice(1);
+        if (dryRun) {
+            merged += sources.length;
+            continue;
+        }
+        try {
+            const transactionalAdapter = requireTransactionAdapter(adapter);
+            runAdapterTransaction(transactionalAdapter, () => {
+                for (const source of sources) {
+                    mergeAndAdoptLineage({
+                        adapter,
+                        source,
+                        target,
+                        groupKey,
+                    });
+                }
+            });
+            merged += sources.length;
+        }
+        catch (error) {
+            if (error instanceof store_js_1.EntityMergeError) {
+                skipped += sources.length;
+                continue;
+            }
+            throw error;
+        }
+    }
+    return {
+        groups,
+        merged,
+        incomplete,
+        skipped,
+    };
+}
+//# sourceMappingURL=exact-merge-backfill.js.map

package/dist/entities/lineage-backfill.d.ts

@@ -0,0 +1,12 @@
+interface BackfillEntityLineageOptions {
+    dryRun?: boolean;
+    now?: number;
+}
+interface BackfillEntityLineageResult {
+    seeded: number;
+    adopted: number;
+    incomplete: number;
+}
+export declare function backfillEntityLineage(opts?: BackfillEntityLineageOptions): Promise<BackfillEntityLineageResult>;
+export {};
+//# sourceMappingURL=lineage-backfill.d.ts.map

package/dist/entities/lineage-backfill.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillEntityLineage = backfillEntityLineage;
+const db_manager_js_1 = require("../db-manager.js");
+const lineage_store_js_1 = require("./lineage-store.js");
+async function backfillEntityLineage(opts = {}) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const dryRun = opts.dryRun === true;
+    const seedConfidence = 0.75;
+    const adoptConfidence = 0.6;
+    let seeded = 0;
+    let adopted = 0;
+    let incomplete = 0;
+    const activeRows = adapter
+        .prepare(`
+        SELECT n.id, o.id AS observation_id
+        FROM entity_nodes n
+        LEFT JOIN entity_observations o ON o.id = n.id
+        WHERE n.status = 'active'
+          AND n.merged_into IS NULL
+      `)
+        .all();
+    for (const row of activeRows) {
+        if (!row.observation_id) {
+            incomplete += 1;
+            continue;
+        }
+        const existing = adapter
+            .prepare(`
+          SELECT id
+          FROM entity_lineage_links
+          WHERE canonical_entity_id = ?
+            AND entity_observation_id = ?
+            AND status = 'active'
+          LIMIT 1
+        `)
+            .get(row.id, row.observation_id);
+        if (existing) {
+            continue;
+        }
+        seeded += 1;
+        if (!dryRun) {
+            await (0, lineage_store_js_1.appendEntityLineageLink)({
+                canonical_entity_id: row.id,
+                entity_observation_id: row.observation_id,
+                source_entity_id: null,
+                contribution_kind: 'seed',
+                run_id: null,
+                candidate_id: null,
+                review_action_id: null,
+                capture_mode: 'backfilled',
+                confidence: seedConfidence,
+            });
+        }
+    }
+    const mergedRows = adapter
+        .prepare(`
+        SELECT n.id AS source_entity_id, n.merged_into AS target_entity_id, o.id AS observation_id
+        FROM entity_nodes n
+        LEFT JOIN entity_observations o ON o.id = n.id
+        WHERE n.status = 'merged'
+          AND n.merged_into IS NOT NULL
+      `)
+        .all();
+    for (const row of mergedRows) {
+        if (!row.observation_id) {
+            incomplete += 1;
+            continue;
+        }
+        const existing = adapter
+            .prepare(`
+          SELECT id
+          FROM entity_lineage_links
+          WHERE canonical_entity_id = ?
+            AND entity_observation_id = ?
+            AND status = 'active'
+          LIMIT 1
+        `)
+            .get(row.target_entity_id, row.observation_id);
+        if (existing) {
+            continue;
+        }
+        adopted += 1;
+        if (!dryRun) {
+            await (0, lineage_store_js_1.appendEntityLineageLink)({
+                canonical_entity_id: row.target_entity_id,
+                entity_observation_id: row.observation_id,
+                source_entity_id: row.source_entity_id,
+                contribution_kind: 'merge_adopt',
+                run_id: null,
+                candidate_id: null,
+                review_action_id: null,
+                capture_mode: 'backfilled',
+                confidence: adoptConfidence,
+            });
+        }
+    }
+    return { seeded, adopted, incomplete };
+}
+//# sourceMappingURL=lineage-backfill.js.map

package/dist/entities/lineage-store.d.ts

@@ -0,0 +1,51 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { EntityIngestRun, EntityLineageLink } from './types.js';
+import type { EntityStoreAdapter } from './store.js';
+type CreateEntityIngestRunInput = Omit<EntityIngestRun, 'status' | 'raw_count' | 'observation_count' | 'candidate_count' | 'reviewable_count' | 'audit_run_id' | 'audit_classification' | 'error_reason' | 'created_at' | 'completed_at'> & {
+    id?: string;
+};
+type AppendEntityLineageLinkInput = Omit<EntityLineageLink, 'id' | 'status' | 'created_at' | 'superseded_at'>;
+interface CompleteEntityIngestRunInput {
+    raw_count: number;
+    observation_count: number;
+    candidate_count: number;
+    reviewable_count: number;
+    audit_run_id?: string | null;
+    audit_classification?: EntityIngestRun['audit_classification'];
+}
+interface AdoptLineageAfterMergeInput {
+    adapter?: LineageMutationAdapter;
+    source_entity_id: string;
+    target_entity_id: string;
+    candidate_id?: string | null;
+    review_action_id?: string | null;
+    confidence?: number;
+    capture_mode?: EntityLineageLink['capture_mode'];
+}
+type LineageMutationAdapter = Pick<DatabaseAdapter, 'prepare'>;
+export interface AppendEntityLineageLinkResult {
+    link: EntityLineageLink;
+    created: boolean;
+}
+interface AdoptLineageAfterMergeSyncInput extends Omit<AdoptLineageAfterMergeInput, 'adapter'> {
+    adapter: LineageMutationAdapter;
+}
+export declare function parseEntityIngestRunRow(row: Record<string, unknown>): EntityIngestRun;
+export declare function createEntityIngestRun(input: CreateEntityIngestRunInput): Promise<EntityIngestRun>;
+export declare function completeEntityIngestRun(id: string, input: CompleteEntityIngestRunInput): Promise<EntityIngestRun>;
+export declare function failEntityIngestRun(id: string, errorReason: string): Promise<EntityIngestRun>;
+export declare function appendEntityLineageLink(input: AppendEntityLineageLinkInput): Promise<AppendEntityLineageLinkResult>;
+export declare function supersedeEntityLineageForEntity(entityId: string): Promise<number>;
+export declare function seedLineageForEntityMaterialization(input: {
+    canonical_entity_id: string;
+    entity_observation_id: string;
+    run_id?: string | null;
+    confidence?: number;
+    capture_mode?: EntityLineageLink['capture_mode'];
+}): Promise<EntityLineageLink>;
+export declare function adoptLineageAfterMerge(input: AdoptLineageAfterMergeInput): Promise<EntityLineageLink[]>;
+export declare function adoptLineageAfterMergeSync(input: AdoptLineageAfterMergeSyncInput): EntityLineageLink[];
+export declare function listActiveEntityLineage(entityId: string, adapter?: EntityStoreAdapter): Promise<EntityLineageLink[]>;
+export declare function listEntityLineageHistory(entityId: string, adapter?: EntityStoreAdapter): Promise<EntityLineageLink[]>;
+export {};
+//# sourceMappingURL=lineage-store.d.ts.map