@jungjaehoon/mama-core 1.6.0 → 1.7.0

package/dist/context-compile/compiler.js

@@ -0,0 +1,401 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileContext = compileContext;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const ref_validation_js_1 = require("../edges/ref-validation.js");
+const ref_js_1 = require("./ref.js");
+const visibility_js_1 = require("./visibility.js");
+const visibility_js_2 = require("./visibility.js");
+const boundary_defaults_js_1 = require("./boundary-defaults.js");
+const source_readers_js_1 = require("./source-readers.js");
+const compiler_policy_js_1 = require("./compiler-policy.js");
+const COMPILER_VERSION = 'context-compile-v0';
+function packetId() {
+    return `ctxp_${node_crypto_1.default.randomUUID().replace(/-/g, '')}`;
+}
+function emptyResult() {
+    return {
+        candidates: [],
+        hidden: { total: 0, by_kind: {}, by_reason: {} },
+        source_refs: [],
+    };
+}
+function mergeHidden(left, right) {
+    left.total += right.total;
+    for (const [kind, count] of Object.entries(right.by_kind)) {
+        const key = kind;
+        left.by_kind[key] = (left.by_kind[key] ?? 0) + count;
+    }
+    for (const [reason, count] of Object.entries(right.by_reason)) {
+        left.by_reason[reason] = (left.by_reason[reason] ?? 0) + count;
+    }
+}
+function assertNotAborted(deps) {
+    if (deps.signal?.aborted) {
+        throw new Error('Context compile aborted');
+    }
+}
+function isBudgetDeadlineExceeded(deps, now) {
+    if (typeof deps.deadlineMs === 'number' && now() >= deps.deadlineMs) {
+        return true;
+    }
+    return false;
+}
+function maxToolCalls(input) {
+    if (typeof input.max_tool_calls !== 'number' || !Number.isFinite(input.max_tool_calls)) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return Math.max(0, Math.floor(input.max_tool_calls));
+}
+function parseTimeMs(value, field) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            throw new Error(`Invalid context compile ${field}: ${String(value)}`);
+        }
+        const numeric = Number(trimmed);
+        if (Number.isFinite(numeric)) {
+            return Math.floor(numeric);
+        }
+        const parsed = Date.parse(trimmed);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    throw new Error(`Invalid context compile ${field}: ${String(value)}`);
+}
+function rangeBoundaryMs(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value);
+    }
+    throw new Error(`Invalid context compile ${field}: ${String(value)}`);
+}
+function minVisibleMs(input) {
+    return rangeBoundaryMs(input.range?.start_ms, 'range.start_ms');
+}
+function maxVisibleMs(input) {
+    const ends = [
+        rangeBoundaryMs(input.range?.end_ms, 'range.end_ms'),
+        parseTimeMs(input.as_of, 'as_of'),
+    ].filter((value) => typeof value === 'number' && Number.isFinite(value));
+    return ends.length > 0 ? Math.min(...ends.map((value) => Math.floor(value))) : null;
+}
+function normalizeContextRange(range) {
+    if (range === undefined) {
+        return undefined;
+    }
+    if (range === null || typeof range !== 'object') {
+        throw new Error(`Invalid context compile range: ${String(range)}`);
+    }
+    const startMs = rangeBoundaryMs(range.start_ms, 'range.start_ms');
+    const endMs = rangeBoundaryMs(range.end_ms, 'range.end_ms');
+    if (startMs !== null && endMs !== null && startMs > endMs) {
+        throw new Error('Invalid context compile range: range.start_ms must be <= range.end_ms');
+    }
+    return {
+        ...(startMs !== null ? { start_ms: startMs } : {}),
+        ...(endMs !== null ? { end_ms: endMs } : {}),
+    };
+}
+function rawCanonicalRefForRef(adapter, rawId) {
+    const row = adapter
+        .prepare(`
+        SELECT source_connector, source_id, channel
+        FROM connector_event_index
+        WHERE event_index_id = ?
+        LIMIT 1
+      `)
+        .get(rawId);
+    if (typeof row?.source_connector !== 'string') {
+        return null;
+    }
+    const ref = {
+        kind: 'raw',
+        connector: row.source_connector,
+        raw_id: rawId,
+    };
+    if (typeof row.source_id === 'string' && row.source_id.length > 0) {
+        ref.source_id = row.source_id;
+    }
+    ref.channel_id = typeof row.channel === 'string' ? row.channel : null;
+    return ref;
+}
+function canonicalizeRawSeedRefs(adapter, seedRefs) {
+    if (!adapter) {
+        return [...seedRefs];
+    }
+    return seedRefs.map((ref) => {
+        if (ref.kind !== 'raw') {
+            return ref;
+        }
+        return rawCanonicalRefForRef(adapter, ref.raw_id) ?? ref;
+    });
+}
+function hasSeedRefVisibilityConstraints(input, boundary) {
+    return (boundary !== undefined ||
+        input.scopes !== undefined ||
+        input.connectors !== undefined ||
+        input.project_refs !== undefined ||
+        (input.tenant_id !== undefined && input.tenant_id !== null) ||
+        input.range !== undefined ||
+        (input.as_of !== undefined && input.as_of !== null));
+}
+function assertSeedRefsVisibleToInput(adapter, input, seedRefs) {
+    if (seedRefs.length === 0) {
+        return [];
+    }
+    if (Array.isArray(input.scopes) && input.scopes.length === 0) {
+        throw new Error('Seed refs are outside the empty requested context scope set');
+    }
+    if (Array.isArray(input.connectors) &&
+        input.connectors.length === 0 &&
+        seedRefs.some((ref) => ref.kind === 'raw')) {
+        throw new Error('Seed raw refs are outside the empty requested connector set');
+    }
+    if (Array.isArray(input.project_refs) &&
+        input.project_refs.length === 0 &&
+        seedRefs.some((ref) => ref.kind === 'raw')) {
+        throw new Error('Seed raw refs are outside the empty requested project ref set');
+    }
+    if (!adapter) {
+        throw new Error('Context seed refs require adapter-backed visibility validation');
+    }
+    (0, ref_validation_js_1.assertTwinRefsVisible)(adapter, seedRefs.map(ref_js_1.toTwinRef), {
+        scopes: input.scopes,
+        connectors: input.connectors,
+        projectRefs: input.project_refs,
+        tenantId: input.tenant_id,
+        startMs: minVisibleMs(input),
+        asOfMs: maxVisibleMs(input),
+    });
+    for (const ref of seedRefs) {
+        if (ref.kind !== 'raw') {
+            continue;
+        }
+        const actualRef = rawCanonicalRefForRef(adapter, ref.raw_id);
+        if (actualRef?.kind !== 'raw' || actualRef.connector !== ref.connector) {
+            throw new Error(`Seed raw ref connector does not match visible raw record: ${ref.raw_id}`);
+        }
+    }
+    return canonicalizeRawSeedRefs(adapter, seedRefs);
+}
+function canReadMore(state, input) {
+    return state.usedToolCalls < maxToolCalls(input);
+}
+function sourceInput(input, boundary) {
+    const strictness = normalizeStrictness(input.strictness);
+    return {
+        task: input.task,
+        scopes: input.scopes,
+        connectors: input.connectors,
+        project_refs: input.project_refs,
+        tenant_id: input.tenant_id ?? null,
+        boundary,
+        range: input.range,
+        as_of: input.as_of,
+        limit: input.limit,
+        threshold: undefined,
+        strictness,
+    };
+}
+function normalizeStrictness(strictness) {
+    switch (strictness) {
+        case 'low':
+        case 'recall':
+            return 'recall';
+        case 'high':
+        case 'strict':
+            return 'strict';
+        case 'medium':
+        case 'balanced':
+        case undefined:
+            return 'balanced';
+        default: {
+            const _exhaustive = strictness;
+            throw new Error(`Unsupported context compile strictness: ${String(_exhaustive)}`);
+        }
+    }
+}
+async function appendResult(state, step, result) {
+    state.candidates.push(...result.candidates);
+    state.sourceRefs.push(...result.source_refs);
+    mergeHidden(state.hidden, result.hidden);
+    state.expansionTrace.push({
+        step,
+        candidates: result.candidates.length,
+        source_refs: result.source_refs.length,
+        hidden: result.hidden.total,
+    });
+}
+function uniqueRefs(refs) {
+    const seen = new Set();
+    const unique = [];
+    for (const ref of refs) {
+        const key = (0, ref_js_1.serializeContextRefForProvenance)(ref);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(ref);
+    }
+    return unique;
+}
+async function compileContext(input, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    const effectiveDeadline = typeof input.max_ms === 'number' && Number.isFinite(input.max_ms)
+        ? Math.min(deps.deadlineMs ?? Number.POSITIVE_INFINITY, startedAt + Math.max(0, input.max_ms))
+        : deps.deadlineMs;
+    const effectiveDeps = { ...deps, deadlineMs: effectiveDeadline };
+    assertNotAborted(effectiveDeps);
+    const boundary = deps.boundary;
+    const seedRefs = (0, visibility_js_1.normalizeSeedRefs)(input.seed_refs);
+    let canonicalSeedRefs = canonicalizeRawSeedRefs(deps.adapter, seedRefs);
+    const effectiveInput = (0, boundary_defaults_js_1.applyContextBoundaryReadDefaults)(input, boundary);
+    const effectiveRange = normalizeContextRange(effectiveInput.range);
+    effectiveInput.range = effectiveRange;
+    parseTimeMs(effectiveInput.as_of, 'as_of');
+    if (boundary) {
+        (0, visibility_js_2.assertContextBoundaryAllowsInput)({
+            boundary,
+            requestedScopes: effectiveInput.scopes,
+            requestedConnectors: effectiveInput.connectors,
+            requestedProjectRefs: effectiveInput.project_refs,
+            requestedTenantId: effectiveInput.tenant_id,
+            seedRefs,
+        });
+    }
+    if (deps.adapter || hasSeedRefVisibilityConstraints(effectiveInput, boundary)) {
+        canonicalSeedRefs = assertSeedRefsVisibleToInput(deps.adapter, effectiveInput, seedRefs);
+    }
+    const canonicalScopes = (0, visibility_js_2.canonicalizeContextScopes)(effectiveInput.scopes);
+    const readInput = sourceInput(effectiveInput, boundary);
+    const state = {
+        candidates: [],
+        sourceRefs: [...canonicalSeedRefs],
+        hidden: { total: 0, by_kind: {}, by_reason: {} },
+        expansionTrace: [{ step: 'seed_refs', source_refs: canonicalSeedRefs.length }],
+        usedToolCalls: 0,
+    };
+    let budgetExhausted = isBudgetDeadlineExceeded(effectiveDeps, now);
+    const skippedOperators = [];
+    const markBudgetSkipped = (operator) => {
+        budgetExhausted = true;
+        skippedOperators.push(operator);
+    };
+    if (!canReadMore(state, effectiveInput)) {
+        markBudgetSkipped('memory_recall');
+    }
+    else {
+        assertNotAborted(effectiveDeps);
+        if (isBudgetDeadlineExceeded(effectiveDeps, now)) {
+            markBudgetSkipped('memory_recall');
+        }
+        else {
+            state.usedToolCalls += 1;
+            const memoryResult = await (deps.readMemoryCandidates?.(readInput) ??
+                (0, source_readers_js_1.readMemoryCandidates)(readInput, deps.adapter ? { adapter: deps.adapter } : {}));
+            await appendResult(state, 'memory_recall', memoryResult);
+        }
+    }
+    const shouldReadRaw = (effectiveInput.connectors?.length ?? 0) > 0;
+    if (shouldReadRaw) {
+        if (!canReadMore(state, effectiveInput)) {
+            markBudgetSkipped('raw_window');
+        }
+        else {
+            assertNotAborted(effectiveDeps);
+            if (isBudgetDeadlineExceeded(effectiveDeps, now)) {
+                markBudgetSkipped('raw_window');
+            }
+            else {
+                state.usedToolCalls += 1;
+                const rawResult = await (deps.readRawCandidates?.(readInput) ??
+                    (deps.adapter ? (0, source_readers_js_1.readRawCandidates)(deps.adapter, readInput) : emptyResult()));
+                await appendResult(state, 'raw_window', rawResult);
+            }
+        }
+    }
+    const visibleRefsForGraph = uniqueRefs([...state.sourceRefs]);
+    if (visibleRefsForGraph.length > 0) {
+        if (!canReadMore(state, effectiveInput)) {
+            markBudgetSkipped('graph_neighborhood');
+        }
+        else {
+            assertNotAborted(effectiveDeps);
+            if (isBudgetDeadlineExceeded(effectiveDeps, now)) {
+                markBudgetSkipped('graph_neighborhood');
+            }
+            else {
+                state.usedToolCalls += 1;
+                const graphResult = await (deps.readGraphCandidates?.(readInput, visibleRefsForGraph) ??
+                    (deps.adapter
+                        ? (0, source_readers_js_1.readGraphCandidates)(deps.adapter, readInput, visibleRefsForGraph)
+                        : emptyResult()));
+                await appendResult(state, 'graph_neighborhood', graphResult);
+            }
+        }
+    }
+    assertNotAborted(effectiveDeps);
+    if (isBudgetDeadlineExceeded(effectiveDeps, now)) {
+        budgetExhausted = true;
+    }
+    const policy = (0, compiler_policy_js_1.applyContextCompilerPolicy)({
+        task: effectiveInput.task,
+        candidates: state.candidates,
+        hidden: state.hidden,
+        limit: effectiveInput.limit,
+        strictness: normalizeStrictness(effectiveInput.strictness),
+        max_tokens: effectiveInput.max_tokens,
+    });
+    const caveats = budgetExhausted ? [...policy.caveats, 'budget_exhausted'] : policy.caveats;
+    const completedAt = now();
+    return {
+        packet_id: deps.packetId?.() ?? packetId(),
+        mode: 'general',
+        task: effectiveInput.task,
+        scopes: canonicalScopes.scopes,
+        scope_hash: canonicalScopes.scopeHash,
+        generated_at: new Date(completedAt).toISOString(),
+        range: effectiveRange ?? null,
+        as_of: effectiveInput.as_of ?? null,
+        compiler_version: COMPILER_VERSION,
+        source_refs: uniqueRefs([...canonicalSeedRefs, ...policy.source_refs]),
+        selected_evidence: policy.selected_evidence,
+        evidence_clusters: policy.evidence_clusters,
+        related_decisions: policy.related_decisions,
+        rejected_refs: policy.rejected_refs,
+        rejected_refs_truncated: false,
+        rejected_summary: policy.rejected_summary,
+        missing_context: policy.missing_context,
+        caveats,
+        expansion_trace: state.expansionTrace,
+        retrieval_diagnostics: policy.retrieval_diagnostics,
+        budget: {
+            max_tool_calls: effectiveInput.max_tool_calls,
+            used_tool_calls: state.usedToolCalls,
+            max_ms: effectiveInput.max_ms,
+            elapsed_ms: Math.max(0, completedAt - startedAt),
+            max_tokens: effectiveInput.max_tokens,
+            estimated_tokens: policy.estimated_tokens,
+            budget_exhausted: budgetExhausted,
+        },
+        budget_manifest: {
+            budget_exhausted: budgetExhausted,
+            skipped_operators: skippedOperators,
+        },
+    };
+}
+//# sourceMappingURL=compiler.js.map

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

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './boundary-defaults.js';
+export * from './ref.js';
+export * from './visibility.js';
+export * from './packet-store.js';
+export * from './source-readers.js';
+export * from './compiler-policy.js';
+export * from './compiler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context-compile/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./boundary-defaults.js"), exports);
+__exportStar(require("./ref.js"), exports);
+__exportStar(require("./visibility.js"), exports);
+__exportStar(require("./packet-store.js"), exports);
+__exportStar(require("./source-readers.js"), exports);
+__exportStar(require("./compiler-policy.js"), exports);
+__exportStar(require("./compiler.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/context-compile/packet-store.d.ts

@@ -0,0 +1,9 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { ContextPacketRecord, TrustedContextPacketLookupInput } from './types.js';
+type ContextPacketAdapter = Pick<DatabaseAdapter, 'prepare'>;
+export declare function insertContextPacket(adapter: ContextPacketAdapter, packet: ContextPacketRecord): ContextPacketRecord;
+export declare function getContextPacket(adapter: ContextPacketAdapter, packetId: string): ContextPacketRecord | null;
+export declare function listContextPacketsForModelRun(adapter: ContextPacketAdapter, modelRunId: string, limit?: number): ContextPacketRecord[];
+export declare function getContextPacketForTrustedUse(adapter: ContextPacketAdapter, input: TrustedContextPacketLookupInput): ContextPacketRecord | null;
+export {};
+//# sourceMappingURL=packet-store.d.ts.map