@jungjaehoon/mama-core 1.4.1 → 1.5.0

package/dist/entities/entity-list.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCanonicalEntities = listCanonicalEntities;
+const db_manager_js_1 = require("../db-manager.js");
+const entity_linked_decision_counts_js_1 = require("./entity-linked-decision-counts.js");
+function normalizeBrowseLabel(input) {
+    return input.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+function buildBrowseCollapseKey(row) {
+    return JSON.stringify([
+        row.kind,
+        row.scope_kind,
+        row.scope_id ?? '',
+        normalizeBrowseLabel(row.preferred_label),
+    ]);
+}
+function compareCanonicalRows(left, right) {
+    if (right.created_at !== left.created_at) {
+        return right.created_at - left.created_at;
+    }
+    const labelCompare = left.preferred_label.localeCompare(right.preferred_label);
+    if (labelCompare !== 0) {
+        return labelCompare;
+    }
+    return left.id.localeCompare(right.id);
+}
+function decodeCursor(cursor) {
+    if (!cursor) {
+        return 0;
+    }
+    try {
+        const decoded = Number(Buffer.from(cursor, 'base64').toString('utf8'));
+        return Number.isFinite(decoded) && decoded >= 0 ? decoded : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), 'utf8').toString('base64');
+}
+function isNoisyCanonicalEntity(row) {
+    const label = row.preferred_label.trim().toLowerCase();
+    if (row.kind === 'person') {
+        return label === 'user' || label === 'claude';
+    }
+    if (row.kind === 'project') {
+        return label === 'workspace';
+    }
+    return false;
+}
+async function listCanonicalEntities(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const rows = adapter
+        .prepare(`
+        SELECT id, kind, preferred_label, scope_kind, scope_id, created_at
+        FROM entity_nodes
+        WHERE status = 'active'
+          AND merged_into IS NULL
+      `)
+        .all();
+    const sorted = rows.sort(compareCanonicalRows);
+    const collapsedByKey = new Map();
+    for (const row of sorted) {
+        const key = buildBrowseCollapseKey(row);
+        const existing = collapsedByKey.get(key);
+        if (!existing) {
+            collapsedByKey.set(key, row);
+            continue;
+        }
+        if (row.created_at > existing.created_at ||
+            (row.created_at === existing.created_at && row.id.localeCompare(existing.id) < 0)) {
+            collapsedByKey.set(key, row);
+        }
+    }
+    const collapsed = Array.from(collapsedByKey.values()).sort(compareCanonicalRows);
+    const totalCount = sorted.length;
+    const visibleBase = input.include_noisy === false
+        ? collapsed.filter((row) => !isNoisyCanonicalEntity(row))
+        : collapsed;
+    const offset = decodeCursor(input.cursor);
+    const limit = Math.max(1, input.limit);
+    const page = visibleBase.slice(offset, offset + limit);
+    const linkedCounts = (0, entity_linked_decision_counts_js_1.loadLinkedDecisionCounts)(adapter, page.map((row) => row.id));
+    const entities = page.map((row) => ({
+        ...row,
+        linked_decision_count: linkedCounts.get(row.id) ?? 0,
+    }));
+    const visibleCount = visibleBase.length;
+    const nextCursor = offset + limit < visibleBase.length ? encodeCursor(offset + limit) : null;
+    return {
+        entities,
+        next_cursor: nextCursor,
+        total_count: totalCount,
+        visible_count: visibleCount,
+    };
+}
+//# sourceMappingURL=entity-list.js.map

package/dist/entities/entity-orphan-list.d.ts

@@ -0,0 +1,26 @@
+import type { EntityNode } from './types.js';
+export interface CanonicalEntityOrphanRow {
+    entity_id: string;
+    title: string;
+    kind: EntityNode['kind'];
+    scope_kind: EntityNode['scope_kind'];
+    scope_id: string | null;
+    scope_label: string;
+    created_at: number;
+    linked_decision_count: number;
+    evidence_summary: {
+        lineage_rows: number;
+        raw_evidence_rows: number;
+        last_seen_at: number | null;
+    };
+}
+interface ReadAdapter {
+    prepare(sql: string): {
+        all: (...params: unknown[]) => unknown[];
+    };
+}
+export declare function listCanonicalEntityOrphans(adapter?: ReadAdapter, options?: {
+    min_age_ms?: number | null;
+}): CanonicalEntityOrphanRow[];
+export {};
+//# sourceMappingURL=entity-orphan-list.d.ts.map

package/dist/entities/entity-orphan-list.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCanonicalEntityOrphans = listCanonicalEntityOrphans;
+const db_manager_js_1 = require("../db-manager.js");
+const entity_linked_decision_counts_js_1 = require("./entity-linked-decision-counts.js");
+function buildScopeLabel(scopeKind, scopeId) {
+    return scopeKind ? `${scopeKind}:${scopeId ?? ''}` : 'global';
+}
+function isNoisyCanonicalEntity(row) {
+    const label = row.title.trim().toLowerCase();
+    if (row.kind === 'person') {
+        return label === 'user' || label === 'claude';
+    }
+    if (row.kind === 'project') {
+        return label === 'workspace';
+    }
+    return false;
+}
+function compareOrphanRows(left, right) {
+    const leftSeen = typeof left.evidence_summary.last_seen_at === 'number' ? left.evidence_summary.last_seen_at : 0;
+    const rightSeen = typeof right.evidence_summary.last_seen_at === 'number'
+        ? right.evidence_summary.last_seen_at
+        : 0;
+    if (rightSeen !== leftSeen) {
+        return rightSeen - leftSeen;
+    }
+    return left.entity_id.localeCompare(right.entity_id);
+}
+function listCanonicalEntityOrphans(adapter = (0, db_manager_js_1.getAdapter)(), options = {}) {
+    const minAgeMs = typeof options.min_age_ms === 'number' && Number.isFinite(options.min_age_ms)
+        ? Math.max(0, options.min_age_ms)
+        : 0;
+    const minCreatedAt = Date.now() - minAgeMs;
+    const rows = adapter
+        .prepare(`
+        SELECT
+          n.id AS entity_id,
+          n.kind AS kind,
+          n.preferred_label AS title,
+          n.scope_kind AS scope_kind,
+          n.scope_id AS scope_id,
+          n.created_at AS created_at,
+          COUNT(DISTINCT l.entity_observation_id) AS lineage_rows,
+          COUNT(
+            DISTINCT CASE
+              WHEN COALESCE(o.source_raw_record_id, '') <> '' THEN l.entity_observation_id
+              ELSE NULL
+            END
+          ) AS raw_evidence_rows,
+          MAX(COALESCE(o.timestamp_observed, o.created_at)) AS last_seen_at
+        FROM entity_nodes n
+        INNER JOIN entity_lineage_links l
+          ON l.canonical_entity_id = n.id
+         AND l.status = 'active'
+        INNER JOIN entity_observations o
+          ON o.id = l.entity_observation_id
+        WHERE n.status = 'active'
+          AND n.merged_into IS NULL
+          AND n.created_at <= ?
+        GROUP BY n.id, n.kind, n.preferred_label, n.scope_kind, n.scope_id, n.created_at
+      `)
+        .all(minCreatedAt);
+    const orphanRows = rows.map((row) => ({
+        entity_id: row.entity_id,
+        title: row.title,
+        kind: row.kind,
+        scope_kind: row.scope_kind,
+        scope_id: row.scope_id,
+        scope_label: buildScopeLabel(row.scope_kind, row.scope_id),
+        created_at: Number(row.created_at),
+        linked_decision_count: 0,
+        evidence_summary: {
+            lineage_rows: Number(row.lineage_rows ?? 0),
+            raw_evidence_rows: Number(row.raw_evidence_rows ?? 0),
+            last_seen_at: row.last_seen_at === null || row.last_seen_at === undefined
+                ? null
+                : Number(row.last_seen_at),
+        },
+    }));
+    const linkedCounts = (0, entity_linked_decision_counts_js_1.loadLinkedDecisionCounts)(adapter, orphanRows.map((row) => row.entity_id));
+    return orphanRows
+        .map((row) => ({
+        ...row,
+        linked_decision_count: linkedCounts.get(row.entity_id) ?? 0,
+    }))
+        .filter((row) => row.evidence_summary.lineage_rows > 0 &&
+        row.linked_decision_count === 0 &&
+        !isNoisyCanonicalEntity(row))
+        .sort(compareOrphanRows);
+}
+//# sourceMappingURL=entity-orphan-list.js.map

package/dist/entities/entity-search.d.ts

@@ -0,0 +1,21 @@
+import type { EntityNode } from './types.js';
+export interface SearchCanonicalEntitiesInput {
+    query: string;
+    limit: number;
+    cursor?: string | null;
+}
+export interface EntitySearchRow {
+    id: string;
+    kind: EntityNode['kind'];
+    preferred_label: string;
+    scope_kind: EntityNode['scope_kind'];
+    scope_id: string | null;
+    score: number;
+    linked_decision_count: number;
+}
+export interface SearchCanonicalEntitiesResult {
+    entities: EntitySearchRow[];
+    next_cursor: string | null;
+}
+export declare function searchCanonicalEntities(input: SearchCanonicalEntitiesInput): Promise<SearchCanonicalEntitiesResult>;
+//# sourceMappingURL=entity-search.d.ts.map

package/dist/entities/entity-search.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchCanonicalEntities = searchCanonicalEntities;
+const db_manager_js_1 = require("../db-manager.js");
+const entity_linked_decision_counts_js_1 = require("./entity-linked-decision-counts.js");
+const store_js_1 = require("./store.js");
+function normalizeSearchLabel(input) {
+    return input.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+function buildSearchCollapseKey(row) {
+    return JSON.stringify([
+        row.kind,
+        row.scope_kind,
+        row.scope_id ?? '',
+        normalizeSearchLabel(row.preferred_label),
+    ]);
+}
+function escapeLikeQuery(query) {
+    return query.replace(/[\\%_]/g, '\\$&');
+}
+function decodeCursor(cursor) {
+    if (!cursor) {
+        return 0;
+    }
+    try {
+        const decoded = Number(Buffer.from(cursor, 'base64').toString('utf8'));
+        return Number.isFinite(decoded) && decoded >= 0 ? decoded : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), 'utf8').toString('base64');
+}
+async function searchCanonicalEntities(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const query = input.query.trim();
+    if (!query) {
+        return { entities: [], next_cursor: null };
+    }
+    const escaped = escapeLikeQuery(query);
+    const normalizedQuery = normalizeSearchLabel(query);
+    const rows = adapter
+        .prepare(`
+        SELECT
+          n.id AS matched_id,
+          n.preferred_label,
+          n.kind,
+          n.scope_kind,
+          n.scope_id,
+          a.label AS alias_label,
+          o.surface_form AS observation_surface_form
+        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(escaped, escaped, escaped);
+    const canonicalIdByMatchedId = new Map();
+    for (const matchedId of new Set(rows.map((row) => row.matched_id))) {
+        try {
+            canonicalIdByMatchedId.set(matchedId, (0, store_js_1.resolveCanonicalEntityId)(adapter, matchedId));
+        }
+        catch (error) {
+            if (error instanceof store_js_1.EntityMergeError) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    const canonicalIds = Array.from(new Set(canonicalIdByMatchedId.values()));
+    const canonicalLookup = new Map();
+    if (canonicalIds.length > 0) {
+        const fetched = adapter
+            .prepare(`
+          SELECT id, kind, preferred_label, scope_kind, scope_id
+          FROM entity_nodes
+          WHERE id IN (${canonicalIds.map(() => '?').join(', ')})
+            AND status = 'active'
+            AND merged_into IS NULL
+        `)
+            .all(...canonicalIds);
+        for (const row of fetched) {
+            canonicalLookup.set(row.id, row);
+        }
+    }
+    const canonicalRows = new Map();
+    for (const row of rows) {
+        const canonicalId = canonicalIdByMatchedId.get(row.matched_id);
+        const canonical = canonicalId ? canonicalLookup.get(canonicalId) : undefined;
+        if (!canonical) {
+            continue;
+        }
+        const score = normalizeSearchLabel(row.preferred_label).includes(normalizedQuery)
+            ? 3
+            : row.alias_label && normalizeSearchLabel(row.alias_label).includes(normalizedQuery)
+                ? 2
+                : 1;
+        const existing = canonicalRows.get(canonical.id);
+        if (!existing || score > existing.score) {
+            canonicalRows.set(canonical.id, {
+                id: canonical.id,
+                kind: canonical.kind,
+                preferred_label: canonical.preferred_label,
+                scope_kind: canonical.scope_kind,
+                scope_id: canonical.scope_id,
+                score,
+                linked_decision_count: 0,
+            });
+        }
+    }
+    const collapsedRows = new Map();
+    for (const row of canonicalRows.values()) {
+        const key = buildSearchCollapseKey(row);
+        const existing = collapsedRows.get(key);
+        if (!existing ||
+            row.score > existing.score ||
+            (row.score === existing.score && row.id.localeCompare(existing.id) < 0)) {
+            collapsedRows.set(key, row);
+        }
+    }
+    const sorted = Array.from(collapsedRows.values()).sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        const labelCompare = left.preferred_label.localeCompare(right.preferred_label);
+        if (labelCompare !== 0) {
+            return labelCompare;
+        }
+        return left.id.localeCompare(right.id);
+    });
+    const offset = decodeCursor(input.cursor);
+    const limit = Math.max(1, input.limit);
+    const page = sorted.slice(offset, offset + limit);
+    const linkedCounts = (0, entity_linked_decision_counts_js_1.loadLinkedDecisionCounts)(adapter, page.map((row) => row.id));
+    const entities = page.map((row) => ({
+        ...row,
+        linked_decision_count: linkedCounts.get(row.id) ?? 0,
+    }));
+    const next_cursor = offset + limit < sorted.length ? encodeCursor(offset + limit) : null;
+    return { entities, next_cursor };
+}
+//# sourceMappingURL=entity-search.js.map

package/dist/entities/errors.d.ts

@@ -0,0 +1,65 @@
+export interface EntityErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        hint: string;
+        doc_url: string;
+    };
+}
+export declare abstract class EntityError extends Error {
+    abstract readonly code: string;
+    abstract readonly doc_section: string;
+    readonly context: Record<string, unknown>;
+    readonly hint: string;
+    constructor(opts: {
+        message: string;
+        context?: Record<string, unknown>;
+        hint: string;
+    });
+    toErrorEnvelope(): EntityErrorEnvelope;
+}
+export declare class InvalidEntityLabelError extends EntityError {
+    readonly code = "entity.invalid_label";
+    readonly doc_section = "#invalid-label";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class EmbeddingUnavailableError extends EntityError {
+    readonly code = "entity.embedding_unavailable";
+    readonly doc_section = "#embedding-unavailable";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class OntologyViolationError extends EntityError {
+    readonly code = "entity.ontology_violation";
+    readonly doc_section = "#ontology-violation";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class MergeTargetStaleError extends EntityError {
+    readonly code = "entity.merge_target_stale";
+    readonly doc_section = "#merge-target-stale";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class EntityLabelMissingError extends EntityError {
+    readonly code = "entity.label_missing";
+    readonly doc_section = "#label-missing";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class CandidateStaleError extends EntityError {
+    readonly code = "entity.candidate_stale";
+    readonly doc_section = "#candidate-stale";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class AuditRunInProgressError extends EntityError {
+    readonly code = "entity.audit_run_in_progress";
+    readonly doc_section = "#audit-run-in-progress";
+    constructor(context?: Record<string, unknown>);
+}
+export declare class CaseMergeChainCycleError extends EntityError {
+    readonly code = "case.merge_chain_cycle";
+    readonly doc_section = "#case-merge-chain-cycle";
+    constructor(context: {
+        case_id: string;
+        chain: string[];
+        detected_at_depth: number;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

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