@jungjaehoon/mama-core 1.4.2 → 1.6.0

package/dist/cases/target-ref.d.ts

@@ -0,0 +1,25 @@
+import type { CaseMembershipSourceType } from './types.js';
+export type CaseFieldName = 'case_id' | 'canonical_case_id' | 'title' | 'status' | 'status_reason' | 'primary_actors' | 'blockers' | 'confidence' | 'last_activity_at';
+export interface CaseFieldTargetRef {
+    kind: 'case_field';
+    field: CaseFieldName;
+}
+export interface CaseMembershipTargetRef {
+    kind: 'membership';
+    source_type: CaseMembershipSourceType;
+    source_id: string;
+}
+export interface CaseWikiSectionTargetRef {
+    kind: 'wiki_section';
+    section_heading: string;
+}
+export type CaseTargetRef = CaseFieldTargetRef | CaseMembershipTargetRef | CaseWikiSectionTargetRef;
+export interface CanonicalTargetRef {
+    json: string;
+    hash: Buffer;
+}
+export declare function buildCaseFieldTargetRef(fieldName: CaseFieldName): CaseFieldTargetRef;
+export declare function buildMembershipTargetRef(sourceType: CaseMembershipSourceType, sourceId: string): CaseMembershipTargetRef;
+export declare function buildWikiSectionTargetRef(sectionHeading: string): CaseWikiSectionTargetRef;
+export declare function canonicalTargetRef(targetRef: CaseTargetRef): CanonicalTargetRef;
+//# sourceMappingURL=target-ref.d.ts.map

package/dist/cases/target-ref.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCaseFieldTargetRef = buildCaseFieldTargetRef;
+exports.buildMembershipTargetRef = buildMembershipTargetRef;
+exports.buildWikiSectionTargetRef = buildWikiSectionTargetRef;
+exports.canonicalTargetRef = canonicalTargetRef;
+const canonicalize_js_1 = require("../canonicalize.js");
+function buildCaseFieldTargetRef(fieldName) {
+    return { kind: 'case_field', field: fieldName };
+}
+function buildMembershipTargetRef(sourceType, sourceId) {
+    return { kind: 'membership', source_type: sourceType, source_id: sourceId };
+}
+function buildWikiSectionTargetRef(sectionHeading) {
+    return { kind: 'wiki_section', section_heading: sectionHeading };
+}
+function canonicalTargetRef(targetRef) {
+    const json = (0, canonicalize_js_1.canonicalizeJSON)(targetRef);
+    const hash = (0, canonicalize_js_1.targetRefHashCanonicalJSON)(json);
+    return { json, hash };
+}
+//# sourceMappingURL=target-ref.js.map

package/dist/cases/timeline-range.d.ts

@@ -0,0 +1,6 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { CaseTimelineRangeInput, CaseTimelineRangeResult } from './types.js';
+type CaseTimelineRangeAdapter = Pick<DatabaseAdapter, 'prepare' | 'transaction'>;
+export declare function caseTimelineRange(adapter: CaseTimelineRangeAdapter, input: CaseTimelineRangeInput): CaseTimelineRangeResult;
+export type { CaseTimelineRangeInput, CaseTimelineRangeItem, CaseTimelineRangeResult, } from './types.js';
+//# sourceMappingURL=timeline-range.d.ts.map

package/dist/cases/timeline-range.js

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.caseTimelineRange = caseTimelineRange;
+const event_index_js_1 = require("../connectors/event-index.js");
+const store_js_1 = require("./store.js");
+function codedError(code, message, context) {
+    const error = new Error(`${code}: ${message}`);
+    error.code = code;
+    error.context = context;
+    return error;
+}
+function placeholders(values) {
+    if (values.length === 0) {
+        throw new Error('Cannot build SQL placeholders for an empty list.');
+    }
+    return values.map(() => '?').join(', ');
+}
+function nullableString(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return String(value);
+}
+function nullableNumber(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const numberValue = Number(value);
+    return Number.isFinite(numberValue) ? numberValue : null;
+}
+function parseDateBound(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw codedError('case.timeline_range_invalid_date', `${field} must be a finite number.`, {
+                field,
+                value,
+            });
+        }
+        return Math.floor(value);
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        throw codedError('case.timeline_range_invalid_date', `${field} is not a valid date.`, {
+            field,
+            value,
+        });
+    }
+    return parsed;
+}
+function parseBounds(input) {
+    const fromMs = parseDateBound(input.from, 'from');
+    const toMs = parseDateBound(input.to, 'to');
+    if (fromMs !== null && toMs !== null && fromMs > toMs) {
+        throw codedError('case.timeline_range_invalid_order', 'from must be before or equal to to.', {
+            from: input.from,
+            to: input.to,
+        });
+    }
+    return { fromMs, toMs };
+}
+function normalizeLimit(limit) {
+    if (limit === undefined) {
+        return 100;
+    }
+    return Math.min(500, Math.max(0, Math.floor(limit)));
+}
+function timestampMs(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    const text = String(value);
+    if (text.length === 0) {
+        return null;
+    }
+    const numeric = Number(text);
+    if (Number.isFinite(numeric) && /^\d+$/u.test(text)) {
+        return numeric;
+    }
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function eventDateFromMs(ms) {
+    if (ms === null) {
+        return null;
+    }
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function withinBounds(ms, bounds) {
+    if (ms === null) {
+        return bounds.fromMs === null && bounds.toMs === null;
+    }
+    if (bounds.fromMs !== null && ms < bounds.fromMs) {
+        return false;
+    }
+    if (bounds.toMs !== null && ms > bounds.toMs) {
+        return false;
+    }
+    return true;
+}
+function compareItemsAsc(left, right) {
+    const leftMs = left.event_datetime ?? Number.NEGATIVE_INFINITY;
+    const rightMs = right.event_datetime ?? Number.NEGATIVE_INFINITY;
+    if (leftMs !== rightMs) {
+        return leftMs - rightMs;
+    }
+    const itemDelta = left.item_type.localeCompare(right.item_type);
+    if (itemDelta !== 0) {
+        return itemDelta;
+    }
+    const sourceTypeDelta = left.source_type.localeCompare(right.source_type);
+    if (sourceTypeDelta !== 0) {
+        return sourceTypeDelta;
+    }
+    return left.source_id.localeCompare(right.source_id);
+}
+function connectorEventSnapshot(row) {
+    if (!row) {
+        return null;
+    }
+    return {
+        event_index_id: row.event_index_id,
+        source_connector: row.source_connector,
+        source_id: row.source_id,
+        source_locator: row.source_locator,
+        artifact_locator: row.artifact_locator,
+        title: row.title,
+        content: row.content,
+        event_datetime: row.event_datetime,
+        event_date: row.event_date,
+    };
+}
+function membershipById(memberships, sourceType) {
+    return new Map(memberships
+        .filter((membership) => membership.source_type === sourceType)
+        .map((membership) => [membership.source_id, membership]));
+}
+function loadDecisionItems(adapter, memberships, bounds) {
+    const membershipMap = membershipById(memberships, 'decision');
+    const ids = Array.from(membershipMap.keys());
+    if (ids.length === 0) {
+        return [];
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT id, topic, decision, summary, reasoning, confidence, event_datetime, event_date, created_at
+        FROM decisions
+        WHERE id IN (${placeholders(ids)})
+      `)
+        .all(...ids);
+    return rows
+        .map((row) => {
+        const sourceId = String(row.id);
+        const membership = membershipMap.get(sourceId);
+        const eventDatetime = timestampMs(row.event_datetime) ??
+            timestampMs(row.event_date) ??
+            timestampMs(row.created_at);
+        return {
+            item_type: 'decision',
+            source_type: 'decision',
+            source_id: sourceId,
+            source_locator: null,
+            event_datetime: eventDatetime,
+            event_date: nullableString(row.event_date) ?? eventDateFromMs(eventDatetime),
+            title: nullableString(row.topic),
+            summary: nullableString(row.summary ?? row.decision),
+            role: membership?.role ?? null,
+            confidence: membership?.confidence ?? nullableNumber(row.confidence),
+            membership_reason: membership?.reason ?? null,
+        };
+    })
+        .filter((item) => withinBounds(item.event_datetime, bounds));
+}
+function loadEventItems(adapter, memberships, bounds) {
+    const membershipMap = membershipById(memberships, 'event');
+    const ids = Array.from(membershipMap.keys());
+    if (ids.length === 0) {
+        return [];
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT id, event_type, role, observed_at, source_ref, summary, details, created_at
+        FROM entity_timeline_events
+        WHERE id IN (${placeholders(ids)})
+      `)
+        .all(...ids);
+    return rows
+        .map((row) => {
+        const sourceId = String(row.id);
+        const membership = membershipMap.get(sourceId);
+        const eventDatetime = timestampMs(row.observed_at) ?? timestampMs(row.created_at);
+        return {
+            item_type: 'event',
+            source_type: 'event',
+            source_id: sourceId,
+            source_locator: nullableString(row.source_ref),
+            event_datetime: eventDatetime,
+            event_date: eventDateFromMs(eventDatetime),
+            title: nullableString(row.event_type),
+            summary: nullableString(row.summary),
+            role: membership?.role ?? nullableString(row.role),
+            confidence: membership?.confidence ?? null,
+            membership_reason: membership?.reason ?? null,
+        };
+    })
+        .filter((item) => withinBounds(item.event_datetime, bounds));
+}
+function loadObservationItems(adapter, memberships, bounds, includeConnectorEnrichments) {
+    const membershipMap = membershipById(memberships, 'observation');
+    const ids = Array.from(membershipMap.keys());
+    if (ids.length === 0) {
+        return [];
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT id, surface_form, context_summary, source_connector, source_raw_record_id,
+               source_locator, timestamp_observed, created_at
+        FROM entity_observations
+        WHERE id IN (${placeholders(ids)})
+      `)
+        .all(...ids);
+    return rows
+        .map((row) => {
+        const sourceId = String(row.id);
+        const membership = membershipMap.get(sourceId);
+        const eventDatetime = timestampMs(row.timestamp_observed) ?? timestampMs(row.created_at);
+        const connectorEvent = includeConnectorEnrichments &&
+            typeof row.source_connector === 'string' &&
+            typeof row.source_raw_record_id === 'string'
+            ? (0, event_index_js_1.getConnectorEventIndexRecord)(adapter, String(row.source_connector), String(row.source_raw_record_id))
+            : null;
+        return {
+            item_type: 'observation',
+            source_type: 'observation',
+            source_id: sourceId,
+            source_locator: nullableString(row.source_locator),
+            event_datetime: eventDatetime,
+            event_date: eventDateFromMs(eventDatetime),
+            title: nullableString(row.surface_form),
+            summary: nullableString(row.context_summary ?? row.surface_form),
+            role: membership?.role ?? null,
+            confidence: membership?.confidence ?? null,
+            membership_reason: membership?.reason ?? null,
+            ...(includeConnectorEnrichments
+                ? { connector_event: connectorEventSnapshot(connectorEvent) }
+                : {}),
+        };
+    })
+        .filter((item) => withinBounds(item.event_datetime, bounds));
+}
+function loadArtifactConnectorEvent(adapter, sourceId) {
+    const row = adapter
+        .prepare(`
+        SELECT *
+        FROM connector_event_index
+        WHERE event_index_id = ?
+           OR artifact_locator = ?
+        ORDER BY event_datetime ASC, event_index_id ASC
+        LIMIT 1
+      `)
+        .get(sourceId, sourceId);
+    if (!row) {
+        return null;
+    }
+    const sourceConnector = String(row.source_connector);
+    const connectorSourceId = String(row.source_id);
+    return (0, event_index_js_1.getConnectorEventIndexRecord)(adapter, sourceConnector, connectorSourceId);
+}
+function loadArtifactItems(adapter, memberships, bounds, includeConnectorEnrichments) {
+    const artifactMemberships = memberships.filter((membership) => membership.source_type === 'artifact');
+    return artifactMemberships
+        .map((membership) => {
+        const connectorEvent = loadArtifactConnectorEvent(adapter, membership.source_id);
+        const eventDatetime = connectorEvent?.event_datetime ?? null;
+        return {
+            item_type: 'artifact',
+            source_type: 'artifact',
+            source_id: membership.source_id,
+            source_locator: connectorEvent?.artifact_locator ??
+                connectorEvent?.source_locator ??
+                membership.source_id,
+            event_datetime: eventDatetime,
+            event_date: connectorEvent?.event_date ?? eventDateFromMs(eventDatetime),
+            title: connectorEvent?.artifact_title ?? connectorEvent?.title ?? membership.source_id,
+            summary: connectorEvent?.content ?? null,
+            role: membership.role,
+            confidence: membership.confidence,
+            membership_reason: membership.reason,
+            ...(includeConnectorEnrichments
+                ? { connector_event: connectorEventSnapshot(connectorEvent) }
+                : {}),
+        };
+    })
+        .filter((item) => withinBounds(item.event_datetime, bounds));
+}
+function caseTimelineRange(adapter, input) {
+    const bounds = parseBounds(input);
+    const limit = normalizeLimit(input.limit);
+    const resolution = (0, store_js_1.resolveCanonicalCaseChain)(adapter, input.case_id);
+    const chainResult = (0, store_js_1.listActiveCorrectionsForCase)(adapter, input.case_id);
+    const chain = chainResult.chain;
+    const memberships = (0, store_js_1.listActiveMembershipsForCaseChain)(adapter, chain);
+    const items = [
+        ...loadDecisionItems(adapter, memberships, bounds),
+        ...loadEventItems(adapter, memberships, bounds),
+        ...loadObservationItems(adapter, memberships, bounds, input.include_connector_enrichments === true),
+        ...loadArtifactItems(adapter, memberships, bounds, input.include_connector_enrichments === true),
+    ].sort(compareItemsAsc);
+    const orderedItems = input.order === 'desc' ? [...items].reverse() : items;
+    return {
+        terminal_case_id: resolution.terminal_case_id,
+        resolved_via_case_id: resolution.resolved_via_case_id,
+        chain,
+        items: orderedItems.slice(0, limit),
+    };
+}
+//# sourceMappingURL=timeline-range.js.map

package/dist/cases/tombstone-sweeper.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+export interface SweepStaleCaseMembershipsOptions {
+    now?: string;
+    limit?: number;
+}
+export interface SweepStaleCaseMembershipsResult {
+    scanned_count: number;
+    stale_count: number;
+    locked_stale_count: number;
+    audit_event_ids: string[];
+}
+export declare function sweepStaleCaseMemberships(adapter: DatabaseAdapter, options?: SweepStaleCaseMembershipsOptions): SweepStaleCaseMembershipsResult;
+//# sourceMappingURL=tombstone-sweeper.d.ts.map

package/dist/cases/tombstone-sweeper.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sweepStaleCaseMemberships = sweepStaleCaseMemberships;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_js_1 = require("../canonicalize.js");
+const sqlite_transaction_js_1 = require("./sqlite-transaction.js");
+const SWEEP_SOURCE_TYPES = ['decision', 'event', 'observation'];
+const SOURCE_EXISTS_SQL = {
+    decision: 'SELECT 1 AS id FROM decisions WHERE id = ?',
+    event: 'SELECT 1 AS id FROM entity_timeline_events WHERE id = ?',
+    observation: 'SELECT 1 AS id FROM entity_observations WHERE id = ?',
+};
+function normalizeNow(value) {
+    return value ?? new Date().toISOString();
+}
+function createdAtMs(now) {
+    const parsed = Date.parse(now);
+    return Number.isFinite(parsed) ? parsed : Date.now();
+}
+function isSweptSourceType(value) {
+    return SWEEP_SOURCE_TYPES.includes(value);
+}
+function readCandidates(adapter, limit) {
+    const sql = `
+    SELECT source_type, source_id
+      FROM case_memberships
+     WHERE status IN ('active', 'candidate', 'removed', 'excluded')
+       AND source_type IN ('decision', 'event', 'observation')
+     GROUP BY source_type, source_id
+     ORDER BY source_type ASC, source_id ASC
+     ${limit === undefined ? '' : 'LIMIT ?'}
+  `;
+    const stmt = adapter.prepare(sql);
+    return (limit === undefined ? stmt.all() : stmt.all(limit));
+}
+function sourceExists(adapter, sourceType, sourceId) {
+    const row = adapter.prepare(SOURCE_EXISTS_SQL[sourceType]).get(sourceId);
+    return row !== undefined;
+}
+function countTransitionTargets(adapter, sourceType, sourceId) {
+    return adapter
+        .prepare(`
+        SELECT COUNT(*) AS count,
+               SUM(CASE WHEN user_locked = 1 THEN 1 ELSE 0 END) AS locked_count
+          FROM case_memberships
+         WHERE status <> 'stale'
+           AND source_type = ?
+           AND source_id = ?
+      `)
+        .get(sourceType, sourceId);
+}
+function markSourceStale(adapter, sourceType, sourceId, now) {
+    const result = adapter
+        .prepare(`
+        UPDATE case_memberships
+           SET status = 'stale',
+               updated_at = ?
+         WHERE status <> 'stale'
+           AND source_type = ?
+           AND source_id = ?
+           AND NOT EXISTS (${SOURCE_EXISTS_SQL[sourceType]})
+      `)
+        .run(now, sourceType, sourceId, sourceId);
+    return result.changes;
+}
+function insertTombstoneAuditEvent(input) {
+    const eventId = `me_${(0, node_crypto_1.randomUUID)()}`;
+    input.adapter
+        .prepare(`
+        INSERT INTO memory_events (
+          event_id, event_type, actor, source_turn_id, memory_id, topic,
+          scope_refs, evidence_refs, reason, created_at
+        )
+        VALUES (?, 'case.membership_tombstoned', 'system', NULL, NULL, ?, ?, ?, ?, ?)
+      `)
+        .run(eventId, 'case:tombstone-sweeper', (0, canonicalize_js_1.canonicalizeJSON)([{ kind: 'project', id: 'case-first' }]), (0, canonicalize_js_1.canonicalizeJSON)(input.sources), (0, canonicalize_js_1.canonicalizeJSON)({
+        stale_count: input.stale_count,
+        locked_stale_count: input.locked_stale_count,
+    }), createdAtMs(input.now));
+    return eventId;
+}
+function sweepStaleCaseMemberships(adapter, options = {}) {
+    const sweepAdapter = adapter;
+    return (0, sqlite_transaction_js_1.runImmediateTransaction)(sweepAdapter, () => {
+        const now = normalizeNow(options.now);
+        const candidates = readCandidates(sweepAdapter, options.limit);
+        let staleCount = 0;
+        let lockedStaleCount = 0;
+        const tombstonedSources = [];
+        for (const candidate of candidates) {
+            if (!isSweptSourceType(candidate.source_type)) {
+                continue;
+            }
+            if (sourceExists(sweepAdapter, candidate.source_type, candidate.source_id)) {
+                continue;
+            }
+            const before = countTransitionTargets(sweepAdapter, candidate.source_type, candidate.source_id);
+            if (before.count === 0) {
+                continue;
+            }
+            const changes = markSourceStale(sweepAdapter, candidate.source_type, candidate.source_id, now);
+            if (changes === 0) {
+                continue;
+            }
+            staleCount += changes;
+            lockedStaleCount += Math.min(changes, before.locked_count ?? 0);
+            tombstonedSources.push(candidate);
+        }
+        const auditEventIds = staleCount > 0
+            ? [
+                insertTombstoneAuditEvent({
+                    adapter: sweepAdapter,
+                    now,
+                    stale_count: staleCount,
+                    locked_stale_count: lockedStaleCount,
+                    sources: tombstonedSources,
+                }),
+            ]
+            : [];
+        return {
+            scanned_count: candidates.length,
+            stale_count: staleCount,
+            locked_stale_count: lockedStaleCount,
+            audit_event_ids: auditEventIds,
+        };
+    });
+}
+//# sourceMappingURL=tombstone-sweeper.js.map