@jungjaehoon/mama-core 1.6.0 → 1.7.0

package/db/migrations/037-create-context-packets.sql

@@ -0,0 +1,32 @@
+CREATE TABLE IF NOT EXISTS context_packets (
+  packet_id TEXT PRIMARY KEY,
+  task TEXT NOT NULL,
+  packet_json TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  scope_hash TEXT NOT NULL,
+  envelope_hash TEXT NOT NULL,
+  model_run_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  input_snapshot_ref TEXT NOT NULL,
+  source_refs_json TEXT NOT NULL DEFAULT '[]',
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  project_id TEXT NOT NULL,
+  memory_scope_kind TEXT NOT NULL CHECK (memory_scope_kind IN ('global', 'user', 'channel', 'project')),
+  memory_scope_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL CHECK (created_at >= 0)
+);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_model_run
+  ON context_packets(model_run_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_envelope
+  ON context_packets(envelope_hash, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_scope
+  ON context_packets(tenant_id, project_id, memory_scope_kind, memory_scope_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_context_packets_scope_hash
+  ON context_packets(scope_hash, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (37, 'Create context packet append-only store');

package/dist/cases/wiki-page-index.js

@@ -153,7 +153,7 @@ function buildFtsQuery(query) {
         .match(/[\p{L}\p{N}_]+/gu)
         ?.filter((token) => token.length > 0);
     if (!tokens || tokens.length === 0) {
-        return query;
+        return '';
     }
     return tokens.map((token) => `"${token.replace(/"/g, '""')}"`).join(' OR ');
 }
@@ -264,6 +264,10 @@ function ftsSearchWikiPages(adapter, query, limit) {
     if (!searchTableExists(adapter, 'wiki_pages_fts')) {
         return [];
     }
+    const ftsQuery = buildFtsQuery(query);
+    if (!ftsQuery) {
+        return [];
+    }
     const schema = readSchema(adapter);
     const rows = adapter
         .prepare(`
@@ -273,7 +277,7 @@ function ftsSearchWikiPages(adapter, query, limit) {
         ORDER BY raw
         LIMIT ?
       `)
-        .all(buildFtsQuery(query), boundedLimit);
+        .all(ftsQuery, boundedLimit);
     const hits = [];
     for (const row of rows) {
         const record = selectByFtsPageId(adapter, schema, row.page_id);

package/dist/context-compile/boundary-defaults.d.ts

@@ -0,0 +1,12 @@
+import type { ContextBoundary, ContextProjectRef, ContextRange } from './types.js';
+import type { MemoryScopeRef } from '../memory/types.js';
+export type ContextBoundaryReadableInput = {
+    scopes?: MemoryScopeRef[];
+    connectors?: string[];
+    project_refs?: ContextProjectRef[];
+    tenant_id?: string | null;
+    range?: ContextRange;
+    as_of?: string | number | null;
+};
+export declare function applyContextBoundaryReadDefaults<T extends ContextBoundaryReadableInput>(input: T, boundary: ContextBoundary | undefined): T;
+//# sourceMappingURL=boundary-defaults.d.ts.map

package/dist/context-compile/boundary-defaults.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyContextBoundaryReadDefaults = applyContextBoundaryReadDefaults;
+function parseBoundaryTimeMs(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 boundary ${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 boundary ${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 boundary ${field}: ${String(value)}`);
+}
+function intersectRange(range, boundaryRange) {
+    if (!boundaryRange) {
+        return range;
+    }
+    const requestedStartMs = rangeBoundaryMs(range?.start_ms, 'range.start_ms');
+    const requestedEndMs = rangeBoundaryMs(range?.end_ms, 'range.end_ms');
+    const boundaryStartMs = rangeBoundaryMs(boundaryRange.start_ms, 'boundary.range.start_ms');
+    const boundaryEndMs = rangeBoundaryMs(boundaryRange.end_ms, 'boundary.range.end_ms');
+    const startMs = requestedStartMs === null
+        ? boundaryStartMs
+        : boundaryStartMs === null
+            ? requestedStartMs
+            : Math.max(requestedStartMs, boundaryStartMs);
+    const endMs = requestedEndMs === null
+        ? boundaryEndMs
+        : boundaryEndMs === null
+            ? requestedEndMs
+            : Math.min(requestedEndMs, boundaryEndMs);
+    if (startMs === null && endMs === null) {
+        return undefined;
+    }
+    if (startMs !== null && endMs !== null && startMs > endMs) {
+        throw new RangeError(`Context boundary range is empty after intersection: start_ms ${startMs} > end_ms ${endMs}`);
+    }
+    return {
+        ...(startMs !== null ? { start_ms: startMs } : {}),
+        ...(endMs !== null ? { end_ms: endMs } : {}),
+    };
+}
+function clampAsOf(requested, boundaryAsOf) {
+    const requestedMs = parseBoundaryTimeMs(requested, 'as_of');
+    const boundaryMs = parseBoundaryTimeMs(boundaryAsOf, 'boundary.as_of');
+    if (requestedMs === null) {
+        return boundaryAsOf ?? null;
+    }
+    if (boundaryMs === null) {
+        return requested ?? null;
+    }
+    return requestedMs <= boundaryMs ? (requested ?? null) : (boundaryAsOf ?? null);
+}
+function applyContextBoundaryReadDefaults(input, boundary) {
+    if (!boundary) {
+        return input;
+    }
+    const requestedTenantId = input.tenant_id;
+    const boundaryTenantId = boundary.tenant_id;
+    if (requestedTenantId !== undefined &&
+        requestedTenantId !== null &&
+        boundaryTenantId !== undefined &&
+        boundaryTenantId !== null &&
+        requestedTenantId !== boundaryTenantId) {
+        throw new Error('Requested tenant is outside the context boundary');
+    }
+    const scopedInput = {
+        ...input,
+        scopes: input.scopes === undefined ? boundary.scopes : input.scopes,
+        connectors: input.connectors === undefined ? boundary.connectors : input.connectors,
+        project_refs: input.project_refs === undefined ? boundary.project_refs : input.project_refs,
+        range: intersectRange(input.range, boundary.range),
+        as_of: clampAsOf(input.as_of, boundary.as_of),
+    };
+    if (boundaryTenantId !== undefined || requestedTenantId !== undefined) {
+        return {
+            ...scopedInput,
+            tenant_id: boundaryTenantId !== undefined ? boundaryTenantId : requestedTenantId,
+        };
+    }
+    return scopedInput;
+}
+//# sourceMappingURL=boundary-defaults.js.map

package/dist/context-compile/compiler-policy.d.ts

@@ -0,0 +1,39 @@
+import type { ContextEvidence, ContextRef } from './types.js';
+import type { ContextCandidate, HiddenCandidateAggregate } from './source-readers.js';
+export interface ContextCompilerPolicyInput {
+    task: string;
+    candidates: ContextCandidate[];
+    hidden: HiddenCandidateAggregate;
+    limit?: number;
+    strictness?: 'recall' | 'balanced' | 'strict' | 'low' | 'medium' | 'high';
+    max_tokens?: number;
+}
+export interface ContextCompilerPolicyResult {
+    selected_evidence: ContextEvidence[];
+    source_refs: ContextRef[];
+    evidence_clusters: unknown[];
+    related_decisions: Array<{
+        memory_id: string;
+        title: string;
+    }>;
+    rejected_refs: ContextRef[];
+    rejected_summary: string[];
+    missing_context: string[];
+    caveats: string[];
+    retrieval_diagnostics: {
+        candidate_count: number;
+        selected_count: number;
+        rejected_count: number;
+        hidden: HiddenCandidateAggregate;
+        deduplicated_count: number;
+        strict_vector_only_rejected_count: number;
+        token_budget_rejected_count: number;
+        limit_rejected_count: number;
+        truncated_by_tokens: boolean;
+        estimated_tokens: number;
+    };
+    estimated_tokens: number;
+}
+export declare function estimateEvidenceTokens(evidence: Pick<ContextEvidence, 'title' | 'excerpt'>): number;
+export declare function applyContextCompilerPolicy(input: ContextCompilerPolicyInput): ContextCompilerPolicyResult;
+//# sourceMappingURL=compiler-policy.d.ts.map

package/dist/context-compile/compiler-policy.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateEvidenceTokens = estimateEvidenceTokens;
+exports.applyContextCompilerPolicy = applyContextCompilerPolicy;
+const ref_js_1 = require("./ref.js");
+function normalizeLimit(limit) {
+    return Math.max(0, Math.min(100, Math.floor(limit ?? 10)));
+}
+function estimateEvidenceTokens(evidence) {
+    const text = `${evidence.title ?? ''}\n${evidence.excerpt ?? ''}`;
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+function sortedCandidates(candidates) {
+    return [...candidates].sort((left, right) => {
+        const scoreDiff = right.score - left.score;
+        if (scoreDiff !== 0) {
+            return scoreDiff;
+        }
+        return (right.timestamp_ms ?? 0) - (left.timestamp_ms ?? 0);
+    });
+}
+function shouldRejectVectorOnly(candidate, strictness) {
+    return (strictness === 'strict' &&
+        candidate.support.is_vector_only === true &&
+        candidate.support.confirmation_signals.length === 0);
+}
+function evidenceFromCandidate(candidate) {
+    return {
+        ref: candidate.ref,
+        title: candidate.title,
+        excerpt: candidate.excerpt,
+        score: candidate.score,
+        reasons: [
+            ...(candidate.support.confirmation_signals ?? []),
+            ...(candidate.support.graph_expanded ? ['graph_expanded'] : []),
+        ],
+        ...(candidate.retrieval_diagnostics
+            ? { retrieval_diagnostics: candidate.retrieval_diagnostics }
+            : {}),
+    };
+}
+function addCountSummary(parts, label, count) {
+    if (count > 0) {
+        parts.push(`${label}: ${count}`);
+    }
+}
+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';
+    }
+    return 'balanced';
+}
+function applyContextCompilerPolicy(input) {
+    const limit = normalizeLimit(input.limit);
+    const strictness = normalizeStrictness(input.strictness);
+    const maxTokens = typeof input.max_tokens === 'number' && Number.isFinite(input.max_tokens)
+        ? Math.max(0, Math.floor(input.max_tokens))
+        : null;
+    const seen = new Set();
+    const selected = [];
+    const sourceRefs = [];
+    const rejectedRefs = [];
+    const counters = {
+        deduplicated: 0,
+        strictVectorOnly: 0,
+        tokenBudget: 0,
+        limit: 0,
+    };
+    let estimatedTokens = 0;
+    for (const candidate of sortedCandidates(input.candidates)) {
+        if (!candidate.visible) {
+            continue;
+        }
+        const key = (0, ref_js_1.serializeContextRefForProvenance)(candidate.ref);
+        if (seen.has(key)) {
+            counters.deduplicated += 1;
+            rejectedRefs.push(candidate.ref);
+            continue;
+        }
+        if (shouldRejectVectorOnly(candidate, strictness)) {
+            counters.strictVectorOnly += 1;
+            rejectedRefs.push(candidate.ref);
+            continue;
+        }
+        if (selected.length >= limit) {
+            counters.limit += 1;
+            rejectedRefs.push(candidate.ref);
+            continue;
+        }
+        const evidence = evidenceFromCandidate(candidate);
+        const nextTokens = estimateEvidenceTokens(evidence);
+        if (maxTokens !== null && estimatedTokens + nextTokens > maxTokens) {
+            counters.tokenBudget += 1;
+            rejectedRefs.push(candidate.ref);
+            continue;
+        }
+        selected.push(evidence);
+        sourceRefs.push(candidate.ref);
+        seen.add(key);
+        estimatedTokens += nextTokens;
+    }
+    const rejectedSummary = [];
+    addCountSummary(rejectedSummary, 'deduplicated duplicate candidates', counters.deduplicated);
+    addCountSummary(rejectedSummary, 'strictness rejected vector-only candidates', counters.strictVectorOnly);
+    addCountSummary(rejectedSummary, 'token budget rejected candidates', counters.tokenBudget);
+    addCountSummary(rejectedSummary, 'limit rejected candidates', counters.limit);
+    const caveats = [];
+    if (input.hidden.total > 0) {
+        caveats.push(`hidden candidates omitted: ${input.hidden.total}`);
+    }
+    const relatedDecisions = selected.flatMap((evidence) => evidence.ref.kind === 'memory'
+        ? [{ memory_id: evidence.ref.id, title: evidence.title ?? evidence.ref.id }]
+        : []);
+    return {
+        selected_evidence: selected,
+        source_refs: sourceRefs,
+        evidence_clusters: [],
+        related_decisions: relatedDecisions,
+        rejected_refs: rejectedRefs,
+        rejected_summary: rejectedSummary,
+        missing_context: selected.length === 0 ? [`No visible evidence selected for task: ${input.task}`] : [],
+        caveats,
+        retrieval_diagnostics: {
+            candidate_count: input.candidates.length,
+            selected_count: selected.length,
+            rejected_count: rejectedRefs.length,
+            hidden: input.hidden,
+            deduplicated_count: counters.deduplicated,
+            strict_vector_only_rejected_count: counters.strictVectorOnly,
+            token_budget_rejected_count: counters.tokenBudget,
+            limit_rejected_count: counters.limit,
+            truncated_by_tokens: counters.tokenBudget > 0,
+            estimated_tokens: estimatedTokens,
+        },
+        estimated_tokens: estimatedTokens,
+    };
+}
+//# sourceMappingURL=compiler-policy.js.map

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

@@ -0,0 +1,18 @@
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { ContextBoundary, ContextCompileInput, ContextPacket, ContextRef } from './types.js';
+import { type ContextSourceReadInput, type ContextSourceReadResult } from './source-readers.js';
+type ContextCompilerAdapter = Pick<DatabaseAdapter, 'prepare'>;
+export interface ContextCompilerDeps {
+    adapter?: ContextCompilerAdapter;
+    boundary?: ContextBoundary;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+    now?: () => number;
+    packetId?: () => string;
+    readMemoryCandidates?: (input: ContextSourceReadInput) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
+    readRawCandidates?: (input: ContextSourceReadInput) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
+    readGraphCandidates?: (input: ContextSourceReadInput, visibleRefs: readonly ContextRef[]) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
+}
+export declare function compileContext(input: ContextCompileInput, deps?: ContextCompilerDeps): Promise<ContextPacket>;
+export {};
+//# sourceMappingURL=compiler.d.ts.map