@jungjaehoon/mama-core 1.6.0 → 1.7.0

package/dist/context-compile/packet-store.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertContextPacket = insertContextPacket;
+exports.getContextPacket = getContextPacket;
+exports.listContextPacketsForModelRun = listContextPacketsForModelRun;
+exports.getContextPacketForTrustedUse = getContextPacketForTrustedUse;
+function parseJson(row, field) {
+    const value = row[field];
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid context packet JSON field ${field}: expected string`);
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid context packet JSON field ${field}: ${message}`);
+    }
+}
+function stringField(row, field) {
+    const value = row[field];
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid context packet field ${field}: expected string`);
+    }
+    return value;
+}
+function numberField(row, field) {
+    const value = row[field];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new Error(`Invalid context packet field ${field}: expected non-negative finite number`);
+    }
+    return Math.floor(value);
+}
+function mapPacketRow(row) {
+    return {
+        packet_id: stringField(row, 'packet_id'),
+        task: stringField(row, 'task'),
+        packet_json: stringField(row, 'packet_json'),
+        packet: parseJson(row, 'packet_json'),
+        scope_json: stringField(row, 'scope_json'),
+        scopes: parseJson(row, 'scope_json'),
+        scope_hash: stringField(row, 'scope_hash'),
+        envelope_hash: stringField(row, 'envelope_hash'),
+        model_run_id: stringField(row, 'model_run_id'),
+        agent_id: stringField(row, 'agent_id'),
+        input_snapshot_ref: stringField(row, 'input_snapshot_ref'),
+        source_refs_json: stringField(row, 'source_refs_json'),
+        source_refs: parseJson(row, 'source_refs_json'),
+        tenant_id: stringField(row, 'tenant_id'),
+        project_id: stringField(row, 'project_id'),
+        memory_scope_kind: stringField(row, 'memory_scope_kind'),
+        memory_scope_id: stringField(row, 'memory_scope_id'),
+        created_at: numberField(row, 'created_at'),
+    };
+}
+function normalizeJsonInput(value, field) {
+    try {
+        if (typeof value === 'string') {
+            return JSON.stringify(JSON.parse(value));
+        }
+        const serialized = JSON.stringify(value);
+        if (typeof serialized !== 'string') {
+            throw new Error('value is not JSON serializable');
+        }
+        return serialized;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid context packet JSON field ${field}: ${message}`);
+    }
+}
+function normalizePacketCreatedAt(value) {
+    let createdAt;
+    if (typeof value === 'number') {
+        createdAt = value;
+    }
+    else if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            throw new Error('Invalid context packet field created_at: expected valid timestamp');
+        }
+        const numeric = Number(trimmed);
+        createdAt = Number.isFinite(numeric) ? numeric : Date.parse(trimmed);
+    }
+    else {
+        throw new Error('Invalid context packet field created_at: expected valid timestamp');
+    }
+    if (!Number.isFinite(createdAt) ||
+        createdAt < 0 ||
+        !Number.isFinite(new Date(createdAt).getTime())) {
+        throw new Error('Invalid context packet field created_at: expected valid timestamp');
+    }
+    return Math.floor(createdAt);
+}
+function modelRunsTableExists(adapter) {
+    const row = adapter
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'model_runs'")
+        .get();
+    return row?.name === 'model_runs';
+}
+function modelRunStatus(adapter, modelRunId) {
+    if (!modelRunsTableExists(adapter)) {
+        return null;
+    }
+    const row = adapter
+        .prepare('SELECT status FROM model_runs WHERE model_run_id = ?')
+        .get(modelRunId);
+    return typeof row?.status === 'string' ? row.status : null;
+}
+function modelRunLineageNode(adapter, modelRunId) {
+    if (!modelRunsTableExists(adapter)) {
+        return null;
+    }
+    const row = adapter
+        .prepare(`
+        SELECT model_run_id, parent_model_run_id, envelope_hash
+        FROM model_runs
+        WHERE model_run_id = ?
+      `)
+        .get(modelRunId);
+    if (typeof row?.model_run_id !== 'string') {
+        return null;
+    }
+    return {
+        model_run_id: row.model_run_id,
+        parent_model_run_id: typeof row.parent_model_run_id === 'string' && row.parent_model_run_id.length > 0
+            ? row.parent_model_run_id
+            : null,
+        envelope_hash: typeof row.envelope_hash === 'string' && row.envelope_hash.length > 0
+            ? row.envelope_hash
+            : null,
+    };
+}
+function modelRunLineage(adapter, modelRunId) {
+    const lineage = [];
+    const seen = new Set();
+    let currentId = modelRunId;
+    while (currentId && !seen.has(currentId) && lineage.length < 1_000) {
+        seen.add(currentId);
+        const node = modelRunLineageNode(adapter, currentId);
+        if (!node) {
+            break;
+        }
+        lineage.push(node);
+        currentId = node.parent_model_run_id;
+    }
+    return lineage;
+}
+function sharesTrustedModelRunLineage(adapter, packet, callerModelRunId) {
+    const packetLineage = modelRunLineage(adapter, packet.model_run_id);
+    const callerLineage = modelRunLineage(adapter, callerModelRunId);
+    if (packetLineage.length === 0 || callerLineage.length === 0) {
+        return false;
+    }
+    if (packetLineage.some((node) => node.envelope_hash !== packet.envelope_hash)) {
+        return false;
+    }
+    if (callerLineage.some((node) => node.envelope_hash !== packet.envelope_hash)) {
+        return false;
+    }
+    const callerAncestors = new Set(callerLineage.map((node) => node.model_run_id));
+    return packetLineage.some((node) => callerAncestors.has(node.model_run_id));
+}
+function assertTrustedModelRunStatus(adapter, packet, includeFailed) {
+    if (!modelRunsTableExists(adapter)) {
+        return;
+    }
+    const status = modelRunStatus(adapter, packet.model_run_id);
+    if (!status) {
+        throw new Error(`Context packet model run not found: ${packet.model_run_id}`);
+    }
+    if (status === 'committed') {
+        return;
+    }
+    if (includeFailed && status === 'failed') {
+        return;
+    }
+    throw new Error(`Context packet model run must be committed before trusted use: ${packet.model_run_id} (${status})`);
+}
+function assertTrustedModelRunLineage(adapter, packet, callerModelRunId) {
+    if (!callerModelRunId) {
+        return;
+    }
+    if (packet.model_run_id === callerModelRunId) {
+        return;
+    }
+    if (!modelRunsTableExists(adapter)) {
+        throw new Error(`Context packet model run lineage cannot be verified: ${packet.model_run_id}`);
+    }
+    if (sharesTrustedModelRunLineage(adapter, packet, callerModelRunId)) {
+        return;
+    }
+    throw new Error(`Context packet model run lineage mismatch for ${packet.packet_id}: caller ${callerModelRunId}, packet ${packet.model_run_id}`);
+}
+function insertContextPacket(adapter, packet) {
+    const packetToInsert = {
+        ...packet,
+        packet_json: normalizeJsonInput(packet.packet_json, 'packet_json'),
+        scope_json: normalizeJsonInput(packet.scope_json, 'scope_json'),
+        source_refs_json: normalizeJsonInput(packet.source_refs_json, 'source_refs_json'),
+        created_at: normalizePacketCreatedAt(packet.created_at),
+    };
+    adapter
+        .prepare(`
+        INSERT INTO context_packets (
+          packet_id, task, packet_json, scope_json, scope_hash, envelope_hash, model_run_id,
+          agent_id, input_snapshot_ref, source_refs_json, tenant_id, project_id,
+          memory_scope_kind, memory_scope_id, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `)
+        .run(packetToInsert.packet_id, packetToInsert.task, packetToInsert.packet_json, packetToInsert.scope_json, packetToInsert.scope_hash, packetToInsert.envelope_hash, packetToInsert.model_run_id, packetToInsert.agent_id, packetToInsert.input_snapshot_ref, packetToInsert.source_refs_json, packetToInsert.tenant_id, packetToInsert.project_id, packetToInsert.memory_scope_kind, packetToInsert.memory_scope_id, packetToInsert.created_at);
+    const inserted = adapter
+        .prepare('SELECT * FROM context_packets WHERE packet_id = ?')
+        .get(packetToInsert.packet_id);
+    if (!inserted) {
+        throw new Error(`Context packet insert failed: ${packetToInsert.packet_id}`);
+    }
+    return mapPacketRow(inserted);
+}
+function getContextPacket(adapter, packetId) {
+    const row = adapter.prepare('SELECT * FROM context_packets WHERE packet_id = ?').get(packetId);
+    return row ? mapPacketRow(row) : null;
+}
+function listContextPacketsForModelRun(adapter, modelRunId, limit = 50) {
+    if (!Number.isFinite(limit) || limit <= 0) {
+        return [];
+    }
+    const rows = adapter
+        .prepare(`
+        SELECT *
+        FROM context_packets
+        WHERE model_run_id = ?
+        ORDER BY created_at DESC, packet_id DESC
+        LIMIT ?
+      `)
+        .all(modelRunId, Math.floor(limit));
+    return rows.map((row) => mapPacketRow(row));
+}
+function getContextPacketForTrustedUse(adapter, input) {
+    const packet = getContextPacket(adapter, input.packetId);
+    if (!packet) {
+        return null;
+    }
+    if (packet.envelope_hash !== input.envelopeHash) {
+        throw new Error(`Context packet envelope mismatch for ${input.packetId}: expected ${input.envelopeHash}, got ${packet.envelope_hash}`);
+    }
+    if (input.modelRunId && packet.model_run_id !== input.modelRunId) {
+        throw new Error(`Context packet model run mismatch for ${input.packetId}: expected ${input.modelRunId}, got ${packet.model_run_id}`);
+    }
+    assertTrustedModelRunLineage(adapter, packet, input.callerModelRunId);
+    assertTrustedModelRunStatus(adapter, packet, input.includeFailed === true);
+    return packet;
+}
+//# sourceMappingURL=packet-store.js.map

package/dist/context-compile/ref.d.ts

@@ -0,0 +1,7 @@
+import type { TwinRef } from '../edges/types.js';
+import type { ContextRef } from './types.js';
+export declare function normalizeContextRef(input: unknown): ContextRef;
+export declare function normalizeContextRefs(refs: readonly unknown[] | undefined): ContextRef[];
+export declare function serializeContextRefForProvenance(ref: ContextRef): string;
+export declare function toTwinRef(ref: ContextRef): TwinRef;
+//# sourceMappingURL=ref.d.ts.map

package/dist/context-compile/ref.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeContextRef = normalizeContextRef;
+exports.normalizeContextRefs = normalizeContextRefs;
+exports.serializeContextRefForProvenance = serializeContextRefForProvenance;
+exports.toTwinRef = toTwinRef;
+const SUPPORTED_KINDS = new Set(['memory', 'raw', 'entity', 'case']);
+const UNSUPPORTED_KINDS = new Set(['decision', 'wiki_page', 'context_packet', 'report']);
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Context ref must be an object with a kind field');
+    }
+    return value;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string') {
+        throw new Error(`Context ref ${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error(`Context ref ${field} must not be empty`);
+    }
+    return trimmed;
+}
+function optionalString(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Context ref ${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function optionalNullableString(value, field) {
+    if (value === null) {
+        return null;
+    }
+    return optionalString(value, field);
+}
+function normalizeContextRef(input) {
+    const record = asRecord(input);
+    const kind = record.kind;
+    if (typeof kind !== 'string') {
+        throw new Error('Context ref kind must be a string');
+    }
+    if (UNSUPPORTED_KINDS.has(kind) || !SUPPORTED_KINDS.has(kind)) {
+        throw new Error(`Unsupported V0 context ref kind: ${kind}`);
+    }
+    switch (kind) {
+        case 'raw': {
+            const normalized = {
+                kind,
+                raw_id: requiredString(record.raw_id, 'raw_id'),
+                connector: requiredString(record.connector, 'connector'),
+            };
+            const sourceId = optionalString(record.source_id, 'source_id');
+            const channelId = optionalNullableString(record.channel_id, 'channel_id');
+            if (sourceId !== undefined) {
+                normalized.source_id = sourceId;
+            }
+            if (channelId !== undefined) {
+                normalized.channel_id = channelId;
+            }
+            return normalized;
+        }
+        case 'memory':
+        case 'entity':
+        case 'case':
+            return {
+                kind,
+                id: requiredString(record.id, 'id'),
+            };
+        default:
+            throw new Error(`Unsupported V0 context ref kind: ${kind}`);
+    }
+}
+function normalizeContextRefs(refs) {
+    if (!Array.isArray(refs)) {
+        return [];
+    }
+    return refs.map((ref) => normalizeContextRef(ref));
+}
+function serializeContextRefForProvenance(ref) {
+    if (ref.kind === 'raw') {
+        return `raw:${ref.connector}:${ref.raw_id}`;
+    }
+    return `${ref.kind}:${ref.id}`;
+}
+function toTwinRef(ref) {
+    if (ref.kind === 'raw') {
+        return {
+            kind: 'raw',
+            id: ref.raw_id,
+        };
+    }
+    return {
+        kind: ref.kind,
+        id: ref.id,
+    };
+}
+//# sourceMappingURL=ref.js.map

package/dist/context-compile/source-readers.d.ts

@@ -0,0 +1,69 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { ListVisibleTwinEdgesOptions, TwinEdgeRecord, TwinRef } from '../edges/types.js';
+import type { RecallBundle, RecallMemoryOptions } from '../memory/types.js';
+import type { SearchHitDiagnostics, SearchStrictness } from '../search/search-quality.js';
+import type { ContextBoundary, ContextProjectRef, ContextRange, ContextRef } from './types.js';
+import type { MemoryScopeRef } from '../memory/types.js';
+type ContextSourceAdapter = Pick<DatabaseAdapter, 'prepare'>;
+export type ContextCandidateSource = 'memory' | 'raw' | 'graph';
+export type ContextCandidateKind = ContextRef['kind'];
+export interface ContextCandidateSupport {
+    retrieval_source?: string;
+    lexical_support?: boolean;
+    entity_support?: boolean;
+    scope_support?: boolean;
+    graph_source?: 'primary' | 'expanded' | null;
+    graph_expanded?: boolean;
+    is_vector_only?: boolean;
+    vector_similarity?: number | null;
+    confirmation_signals: string[];
+    metadata_signals: string[];
+}
+export interface ContextCandidate {
+    ref: ContextRef;
+    title: string;
+    excerpt: string;
+    score: number;
+    timestamp_ms: number | null;
+    source: ContextCandidateSource;
+    visible: boolean;
+    hidden_reason?: string;
+    support: ContextCandidateSupport;
+    retrieval_diagnostics?: SearchHitDiagnostics;
+    edge_id?: string;
+    edge_type?: string;
+}
+export interface HiddenCandidateAggregate {
+    total: number;
+    by_kind: Partial<Record<ContextCandidateKind, number>>;
+    by_reason: Record<string, number>;
+}
+export interface ContextSourceReadResult {
+    candidates: ContextCandidate[];
+    hidden: HiddenCandidateAggregate;
+    source_refs: ContextRef[];
+}
+export interface ContextSourceReadInput {
+    task: string;
+    scopes?: MemoryScopeRef[];
+    connectors?: string[];
+    project_refs?: ContextProjectRef[];
+    tenant_id?: string | null;
+    boundary?: ContextBoundary;
+    range?: ContextRange;
+    as_of?: string | number | null;
+    limit?: number;
+    threshold?: number;
+    strictness?: SearchStrictness;
+}
+export interface ContextSourceReaderDeps {
+    adapter?: ContextSourceAdapter;
+    recallMemory?: (query: string, options?: RecallMemoryOptions) => Promise<RecallBundle>;
+    listVisibleTwinEdgesForRefs?: (adapter: ContextSourceAdapter, refs: readonly TwinRef[], options?: ListVisibleTwinEdgesOptions) => TwinEdgeRecord[];
+}
+export declare function sourceRefsFromCandidates(candidates: readonly ContextCandidate[]): ContextRef[];
+export declare function readMemoryCandidates(input: ContextSourceReadInput, deps?: ContextSourceReaderDeps): Promise<ContextSourceReadResult>;
+export declare function readRawCandidates(adapter: ContextSourceAdapter, input: ContextSourceReadInput): ContextSourceReadResult;
+export declare function readGraphCandidates(adapter: ContextSourceAdapter, input: ContextSourceReadInput, visibleRefs: readonly ContextRef[], deps?: ContextSourceReaderDeps): ContextSourceReadResult;
+export {};
+//# sourceMappingURL=source-readers.d.ts.map