@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/entities/policy-types.d.ts

@@ -0,0 +1,72 @@
+export declare const ENTITY_POLICY_ROLES: readonly ["viewer", "operator", "admin"];
+export type EntityRole = (typeof ENTITY_POLICY_ROLES)[number];
+export declare const ENTITY_POLICY_KINDS: readonly ["entity_kind", "merge_guardrails", "review_thresholds", "connector_policy"];
+export type EntityPolicyKind = (typeof ENTITY_POLICY_KINDS)[number];
+export declare const ENTITY_POLICY_PROPOSAL_STATUSES: readonly ["pending", "approved", "rejected"];
+export type EntityPolicyProposalStatus = (typeof ENTITY_POLICY_PROPOSAL_STATUSES)[number];
+export interface EntityPolicyRow {
+    policy_key: string;
+    policy_kind: EntityPolicyKind;
+    value_json: string;
+    value: Record<string, unknown>;
+    version: number;
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityRoleBinding {
+    actor_id: string;
+    role: EntityRole;
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityRoleBindingInput {
+    actor_id: string;
+    role: EntityRole;
+}
+export interface EntityPolicyProposalRow {
+    proposal_id: string;
+    policy_key: string;
+    policy_kind: EntityPolicyKind;
+    proposed_value_json: string;
+    proposed_value: Record<string, unknown>;
+    proposer_actor: string;
+    approver_actor: string | null;
+    reason: string;
+    status: EntityPolicyProposalStatus;
+    created_at: number;
+    approved_at: number | null;
+}
+export interface EntityPolicyProposalInput {
+    policy_key: string;
+    policy_kind: EntityPolicyKind;
+    proposed_value: Record<string, unknown>;
+    proposer_actor: string;
+    reason: string;
+    proposal_id?: string;
+    created_at?: number;
+}
+export interface EntityPolicyApprovalInput {
+    proposal_id: string;
+    approver_actor: string;
+    approved_at?: number;
+}
+export interface EntityPolicyBootstrapPolicy {
+    policy_key: string;
+    policy_kind: EntityPolicyKind;
+    value: Record<string, unknown>;
+}
+export interface EntityPolicyBootstrapRoleBinding {
+    actor_id: string;
+    role: EntityRole;
+}
+export interface EntityPolicyBootstrapDocument {
+    version: number;
+    policies: EntityPolicyBootstrapPolicy[];
+    role_bindings: EntityPolicyBootstrapRoleBinding[];
+}
+export declare const ENTITY_ROLE_ORDER: Record<EntityRole, number>;
+export declare function isEntityRole(value: string): value is EntityRole;
+export declare function isEntityPolicyKind(value: string): value is EntityPolicyKind;
+export declare function isEntityPolicyProposalStatus(value: string): value is EntityPolicyProposalStatus;
+export declare function createDefaultEntityPolicyBootstrap(adminActor?: string): EntityPolicyBootstrapDocument;
+//# sourceMappingURL=policy-types.d.ts.map

package/dist/entities/policy-types.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITY_ROLE_ORDER = exports.ENTITY_POLICY_PROPOSAL_STATUSES = exports.ENTITY_POLICY_KINDS = exports.ENTITY_POLICY_ROLES = void 0;
+exports.isEntityRole = isEntityRole;
+exports.isEntityPolicyKind = isEntityPolicyKind;
+exports.isEntityPolicyProposalStatus = isEntityPolicyProposalStatus;
+exports.createDefaultEntityPolicyBootstrap = createDefaultEntityPolicyBootstrap;
+exports.ENTITY_POLICY_ROLES = ['viewer', 'operator', 'admin'];
+exports.ENTITY_POLICY_KINDS = [
+    'entity_kind',
+    'merge_guardrails',
+    'review_thresholds',
+    'connector_policy',
+];
+exports.ENTITY_POLICY_PROPOSAL_STATUSES = ['pending', 'approved', 'rejected'];
+exports.ENTITY_ROLE_ORDER = {
+    viewer: 0,
+    operator: 1,
+    admin: 2,
+};
+function isEntityRole(value) {
+    return exports.ENTITY_POLICY_ROLES.includes(value);
+}
+function isEntityPolicyKind(value) {
+    return exports.ENTITY_POLICY_KINDS.includes(value);
+}
+function isEntityPolicyProposalStatus(value) {
+    return exports.ENTITY_POLICY_PROPOSAL_STATUSES.includes(value);
+}
+function createDefaultEntityPolicyBootstrap(adminActor = 'local:viewer') {
+    return {
+        version: 1,
+        policies: [
+            {
+                policy_key: 'merge_guardrails.default',
+                policy_kind: 'merge_guardrails',
+                value: {
+                    max_false_merge_rate: 0.02,
+                    require_review_for_cross_scope: true,
+                },
+            },
+            {
+                policy_key: 'review_thresholds.default',
+                policy_kind: 'review_thresholds',
+                value: {
+                    approve_score_min: 0.92,
+                    defer_score_min: 0.78,
+                },
+            },
+        ],
+        role_bindings: [
+            {
+                actor_id: adminActor,
+                role: 'admin',
+            },
+        ],
+    };
+}
+//# sourceMappingURL=policy-types.js.map

package/dist/entities/projection.d.ts

@@ -0,0 +1,8 @@
+import type { EntityAlias, EntityNode, EntityTimelineEvent } from './types.js';
+import type { MemoryRecord } from '../memory/types.js';
+interface ProjectionOptions {
+    nodeLookup?: Record<string, EntityNode>;
+}
+export declare function projectEntityToRecallSummary(node: EntityNode, aliases: EntityAlias[], latestEvent: EntityTimelineEvent | null, options?: ProjectionOptions): MemoryRecord;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/dist/entities/projection.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectEntityToRecallSummary = projectEntityToRecallSummary;
+const errors_js_1 = require("./errors.js");
+function formatTimelineEventForRecall(latestEvent) {
+    if (!latestEvent) {
+        return null;
+    }
+    const parts = [];
+    const eventType = latestEvent.event_type.trim();
+    const summary = latestEvent.summary.trim();
+    const details = latestEvent.details?.trim() ?? '';
+    if (eventType.length > 0) {
+        parts.push(eventType);
+    }
+    if (summary.length > 0) {
+        parts.push(summary);
+    }
+    if (details.length > 0 && details !== summary) {
+        try {
+            const parsed = JSON.parse(details);
+            if (parsed && typeof parsed === 'object') {
+                parts.push(JSON.stringify(parsed));
+            }
+            else {
+                parts.push(details);
+            }
+        }
+        catch {
+            parts.push(details);
+        }
+    }
+    return parts.length > 0 ? parts.join('\n') : null;
+}
+function assertNoCircularMerge(node, options) {
+    if (!options?.nodeLookup) {
+        return;
+    }
+    const seen = new Set();
+    let current = options.nodeLookup[node.id] ?? node;
+    while (current?.merged_into) {
+        if (seen.has(current.id)) {
+            throw new errors_js_1.EntityLabelMissingError({
+                entity_id: node.id,
+                reason: 'circular_merged_into_chain',
+            });
+        }
+        seen.add(current.id);
+        current = options.nodeLookup[current.merged_into];
+    }
+}
+function projectEntityToRecallSummary(node, aliases, latestEvent, options) {
+    if (!node.preferred_label.trim()) {
+        throw new errors_js_1.EntityLabelMissingError({
+            entity_id: node.id,
+            reason: 'missing_preferred_label',
+        });
+    }
+    assertNoCircularMerge(node, options);
+    const aliasText = aliases.map((alias) => alias.label).join(', ');
+    const detailParts = [formatTimelineEventForRecall(latestEvent), aliasText].filter((value) => Boolean(value));
+    const scopeKind = node.scope_kind ?? 'global';
+    const scopeId = node.scope_kind === null ? 'global' : (node.scope_id ?? 'global');
+    return {
+        id: node.id,
+        topic: `entity/${node.id}`,
+        kind: 'fact',
+        summary: node.preferred_label,
+        details: detailParts.join('\n'),
+        confidence: 0.9,
+        status: 'active',
+        scopes: [{ kind: scopeKind, id: scopeId }],
+        source: {
+            package: 'mama-core',
+            source_type: 'entity_canonical',
+            project_id: node.scope_id ?? undefined,
+        },
+        created_at: node.created_at,
+        updated_at: node.updated_at,
+    };
+}
+//# sourceMappingURL=projection.js.map

package/dist/entities/provenance-query.d.ts

@@ -0,0 +1,33 @@
+import { type SourceLocatorKind } from './source-locator.js';
+import type { MemoryRecord } from '../memory/types.js';
+export interface ProvenanceObservationSummary {
+    id: string;
+    observation_type: string;
+    entity_kind_hint: string | null;
+    surface_form: string;
+    normalized_form: string;
+    lang: string | null;
+    script: string | null;
+    context_summary: string | null;
+    scope_kind: string;
+    scope_id: string | null;
+    extractor_version: string;
+    embedding_model_version: string | null;
+    source_connector: string;
+    source_locator: string | null;
+    source_locator_kind: SourceLocatorKind;
+    source_raw_record_id: string;
+    created_at: number;
+}
+export interface MemoryProvenanceResult {
+    status: 'legacy' | 'manual' | 'dropped' | 'resolved';
+    memory: MemoryRecord;
+    observations: ProvenanceObservationSummary[];
+    audit: {
+        event_type: 'provenance.empty_batch' | 'provenance.link_write_failed';
+        reason: string | null;
+        created_at: number;
+    } | null;
+}
+export declare function queryProvenanceForMemory(memoryId: string): Promise<MemoryProvenanceResult>;
+//# sourceMappingURL=provenance-query.d.ts.map

package/dist/entities/provenance-query.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryProvenanceForMemory = queryProvenanceForMemory;
+const db_manager_js_1 = require("../db-manager.js");
+const source_locator_js_1 = require("./source-locator.js");
+function parseSource(trustContext) {
+    if (typeof trustContext !== 'string' || trustContext.length === 0) {
+        return { package: 'mama-core', source_type: 'db' };
+    }
+    try {
+        const parsed = JSON.parse(trustContext);
+        if (parsed?.source && typeof parsed.source === 'object') {
+            return parsed.source;
+        }
+    }
+    catch {
+        // ignore malformed trust_context
+    }
+    return { package: 'mama-core', source_type: 'db' };
+}
+function mapMemoryRecord(row, scopes) {
+    return {
+        id: row.id,
+        topic: row.topic,
+        kind: (row.kind ?? 'decision'),
+        summary: row.summary ?? row.decision,
+        details: row.reasoning ?? row.decision,
+        confidence: row.confidence ?? 0.5,
+        status: (row.status ?? 'active'),
+        scopes,
+        source: parseSource(row.trust_context),
+        created_at: row.created_at,
+        updated_at: row.updated_at ?? row.created_at,
+        event_date: row.event_date,
+    };
+}
+function loadScopes(memoryId) {
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const rows = adapter
+        .prepare(`
+        SELECT msb.memory_id, ms.kind, ms.external_id
+        FROM memory_scope_bindings msb
+        JOIN memory_scopes ms ON ms.id = msb.scope_id
+        WHERE msb.memory_id = ?
+        ORDER BY msb.is_primary DESC
+      `)
+        .all(memoryId);
+    return rows.map((row) => ({
+        kind: row.kind,
+        id: row.external_id,
+    }));
+}
+function loadObservations(memoryId) {
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const rows = adapter
+        .prepare(`
+        SELECT
+          o.id,
+          o.observation_type,
+          o.entity_kind_hint,
+          o.surface_form,
+          o.normalized_form,
+          o.lang,
+          o.script,
+          o.context_summary,
+          o.scope_kind,
+          o.scope_id,
+          o.extractor_version,
+          o.embedding_model_version,
+          o.source_connector,
+          o.source_locator,
+          o.source_raw_record_id,
+          o.created_at
+        FROM decision_entity_sources des
+        JOIN entity_observations o ON o.id = des.entity_observation_id
+        WHERE des.decision_id = ?
+        ORDER BY des.created_at ASC, o.created_at ASC
+      `)
+        .all(memoryId);
+    return rows.map((row) => ({
+        id: row.id,
+        observation_type: row.observation_type,
+        entity_kind_hint: row.entity_kind_hint,
+        surface_form: row.surface_form,
+        normalized_form: row.normalized_form,
+        lang: row.lang,
+        script: row.script,
+        context_summary: row.context_summary,
+        scope_kind: row.scope_kind,
+        scope_id: row.scope_id,
+        extractor_version: row.extractor_version,
+        embedding_model_version: row.embedding_model_version,
+        source_connector: row.source_connector,
+        source_locator: row.source_locator,
+        source_locator_kind: (0, source_locator_js_1.detectSourceLocatorKind)(row.source_locator),
+        source_raw_record_id: row.source_raw_record_id,
+        created_at: row.created_at,
+    }));
+}
+function loadProvenanceAudit(memoryId) {
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const row = adapter
+        .prepare(`
+        SELECT event_type, reason, created_at
+        FROM memory_events
+        WHERE memory_id = ?
+          AND event_type IN ('provenance.empty_batch', 'provenance.link_write_failed')
+        ORDER BY created_at DESC
+        LIMIT 1
+      `)
+        .get(memoryId);
+    if (!row) {
+        return null;
+    }
+    return {
+        event_type: row.event_type,
+        reason: row.reason,
+        created_at: row.created_at,
+    };
+}
+async function queryProvenanceForMemory(memoryId) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const row = adapter
+        .prepare(`
+        SELECT
+          id,
+          topic,
+          decision,
+          reasoning,
+          confidence,
+          created_at,
+          updated_at,
+          trust_context,
+          kind,
+          status,
+          summary,
+          event_date
+        FROM decisions
+        WHERE id = ?
+      `)
+        .get(memoryId);
+    if (!row) {
+        throw new Error(`Decision not found: ${memoryId}`);
+    }
+    const scopes = loadScopes(memoryId);
+    const memory = mapMemoryRecord(row, scopes);
+    const observations = loadObservations(memoryId);
+    const audit = loadProvenanceAudit(memoryId);
+    let status = 'legacy';
+    if (observations.length > 0) {
+        status = 'resolved';
+    }
+    else if (audit?.event_type === 'provenance.link_write_failed') {
+        status = 'dropped';
+    }
+    else if (audit?.event_type === 'provenance.empty_batch') {
+        status = 'manual';
+    }
+    return {
+        status,
+        memory,
+        observations,
+        audit,
+    };
+}
+//# sourceMappingURL=provenance-query.js.map

package/dist/entities/read-identity.d.ts

@@ -0,0 +1,31 @@
+import type { MemoryRecord } from '../memory/types.js';
+export interface CanonicalReadEntity {
+    id: string;
+    label: string;
+    kind: string;
+}
+export type ReadIdentity = {
+    kind: 'canonical';
+    entities: CanonicalReadEntity[];
+    primaryEntity: CanonicalReadEntity;
+    legacyTopic: string | null;
+    shadowConflict: boolean;
+    displaySubject?: string | null;
+    displayTopic?: string | null;
+    displaySuffix?: string | null;
+} | {
+    kind: 'topic';
+    topic: string;
+    displaySubject?: string | null;
+    displayTopic?: string | null;
+    displaySuffix?: string | null;
+} | {
+    kind: 'raw';
+    label: string;
+    displaySubject?: string | null;
+    displayTopic?: string | null;
+    displaySuffix?: string | null;
+};
+export declare function resolveReadIdentity(record: Pick<MemoryRecord, 'topic' | 'summary'>, entities: CanonicalReadEntity[]): ReadIdentity;
+export declare function loadDecisionReadIdentityIndex(decisionIds: string[]): Promise<Map<string, CanonicalReadEntity[]>>;
+//# sourceMappingURL=read-identity.d.ts.map