@jungjaehoon/mama-core 2.4.1 → 4.1.0

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

@@ -1,155 +0,0 @@
-import type { MemoryScopeRef } from '../memory/types.js';
-export declare const CONTEXT_REF_KINDS: readonly ["memory", "raw", "entity", "case"];
-export type ContextRefKind = (typeof CONTEXT_REF_KINDS)[number];
-export declare const UNSUPPORTED_CONTEXT_REF_KINDS: readonly ["decision", "wiki_page", "context_packet", "report"];
-export type UnsupportedContextRefKind = (typeof UNSUPPORTED_CONTEXT_REF_KINDS)[number];
-export type ContextRef = {
-    kind: 'memory';
-    id: string;
-} | {
-    kind: 'raw';
-    raw_id: string;
-    connector: string;
-    source_id?: string;
-    channel_id?: string | null;
-} | {
-    kind: 'entity';
-    id: string;
-} | {
-    kind: 'case';
-    id: string;
-};
-export interface ContextRange {
-    start_ms?: number;
-    end_ms?: number;
-}
-export interface ContextProjectRef {
-    kind: 'project';
-    id: string;
-}
-export interface ContextCompileInput {
-    task: string;
-    scopes?: MemoryScopeRef[];
-    seed_refs?: ContextRef[];
-    connectors?: string[];
-    project_refs?: ContextProjectRef[];
-    tenant_id?: string | null;
-    range?: ContextRange;
-    as_of?: string | number | null;
-    limit?: number;
-    max_tool_calls?: number;
-    max_ms?: number;
-    max_tokens?: number;
-    strictness?: 'recall' | 'balanced' | 'strict' | 'low' | 'medium' | 'high';
-}
-export interface ContextBoundary {
-    scopes?: MemoryScopeRef[];
-    connectors?: string[];
-    project_refs?: ContextProjectRef[];
-    tenant_id?: string | null;
-    as_of?: string | number | null;
-    range?: ContextRange;
-    /**
-     * Which channels of each connector may be read, keyed by connector.
-     *
-     * When present this DECIDES raw visibility, and the scope/project/tenant clauses are not
-     * applied to raw rows. That is a deliberate replacement, not a relaxation, and the reason
-     * is measurable: on a live index of 30,671 events, `memory_scope_id` is populated on 37%
-     * of rows in three mutually incompatible namespaces, and 63% carry no scope at all - so a
-     * caller that names any specific scope loses exactly the two thirds of the corpus that
-     * were never labelled. A filter that hides most of the data from anyone precise enough to
-     * ask a narrow question is not a privacy boundary; it is a leak of a different kind, the
-     * kind where the system quietly answers from nothing.
-     *
-     * The grant is (connector, channel) because that is what the owner actually configures
-     * and what the connector actually emits. The caller computes it - this module enforces
-     * what it is given and never widens it.
-     */
-    channels?: Record<string, readonly string[]>;
-}
-export interface CanonicalContextScopes {
-    scopes: MemoryScopeRef[];
-    scopeJson: string;
-    scopeHash: string;
-}
-export interface ContextVisibility {
-    scopes: MemoryScopeRef[];
-    scope_json: string;
-    scope_hash: string;
-    connectors: string[];
-    project_refs: ContextProjectRef[];
-    tenant_id: string | null;
-    as_of: string | number | null;
-    range: ContextRange | null;
-}
-export interface ContextEvidence {
-    ref: ContextRef;
-    title?: string;
-    excerpt?: string;
-    score?: number;
-    reasons?: string[];
-    retrieval_diagnostics?: unknown;
-}
-export interface ContextPacket {
-    packet_id: string;
-    mode: 'general';
-    task: string;
-    scopes: MemoryScopeRef[];
-    scope_hash: string;
-    generated_at: string;
-    range: ContextRange | null;
-    as_of: string | number | null;
-    compiler_version: string;
-    source_refs: ContextRef[];
-    selected_evidence: ContextEvidence[];
-    evidence_clusters: unknown[];
-    related_decisions: unknown[];
-    rejected_refs: ContextRef[];
-    rejected_refs_truncated: boolean;
-    rejected_summary: string[];
-    missing_context: string[];
-    caveats: string[];
-    expansion_trace: unknown[];
-    retrieval_diagnostics: unknown;
-    budget: {
-        max_tool_calls?: number;
-        used_tool_calls: number;
-        max_ms?: number;
-        elapsed_ms: number;
-        max_tokens?: number;
-        estimated_tokens: number;
-        budget_exhausted: boolean;
-    };
-    budget_manifest: {
-        budget_exhausted: boolean;
-        skipped_operators: string[];
-    };
-}
-export interface ContextPacketRecord {
-    packet_id: string;
-    task: string;
-    packet_json: string;
-    packet: ContextPacket;
-    scope_json: string;
-    scopes: MemoryScopeRef[];
-    scope_hash: string;
-    envelope_hash: string;
-    model_run_id: string;
-    agent_id: string;
-    input_snapshot_ref: string;
-    source_refs_json: string;
-    source_refs: ContextRef[];
-    tenant_id: string;
-    project_id: string;
-    memory_scope_kind: MemoryScopeRef['kind'];
-    memory_scope_id: string;
-    created_at: number;
-}
-export interface TrustedContextPacketLookupInput {
-    packetId: string;
-    envelopeHash: string;
-    modelRunId?: string;
-    callerModelRunId?: string;
-    includeFailed?: boolean;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/context-compile/types.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNSUPPORTED_CONTEXT_REF_KINDS = exports.CONTEXT_REF_KINDS = void 0;
-exports.CONTEXT_REF_KINDS = ['memory', 'raw', 'entity', 'case'];
-exports.UNSUPPORTED_CONTEXT_REF_KINDS = [
-    'decision',
-    'wiki_page',
-    'context_packet',
-    'report',
-];
-//# sourceMappingURL=types.js.map

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

@@ -1,21 +0,0 @@
-import { type MemoryScopeRef } from '../memory/types.js';
-import type { ContextBoundary, ContextProjectRef, ContextRef } from './types.js';
-type BoundaryCheckInput = {
-    boundary: ContextBoundary;
-    requestedScopes?: readonly MemoryScopeRef[];
-    requestedConnectors?: readonly string[];
-    requestedProjectRefs?: readonly ContextProjectRef[];
-    requestedTenantId?: string | null;
-    seedRefs?: readonly unknown[];
-};
-export declare function canonicalizeContextScopes(scopes: readonly MemoryScopeRef[] | undefined): {
-    scopes: MemoryScopeRef[];
-    scopeJson: string;
-    scopeHash: string;
-};
-export declare function derivePrimaryContextScope(scopes: readonly MemoryScopeRef[]): MemoryScopeRef;
-export declare function assertContextBoundaryAllowsInput(input: BoundaryCheckInput): void;
-export declare function sanitizeContextPacketForVisibility<T>(packet: T): T;
-export declare function normalizeSeedRefs(seedRefs: readonly unknown[] | undefined): ContextRef[];
-export {};
-//# sourceMappingURL=visibility.d.ts.map

package/dist/context-compile/visibility.js

@@ -1,224 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.canonicalizeContextScopes = canonicalizeContextScopes;
-exports.derivePrimaryContextScope = derivePrimaryContextScope;
-exports.assertContextBoundaryAllowsInput = assertContextBoundaryAllowsInput;
-exports.sanitizeContextPacketForVisibility = sanitizeContextPacketForVisibility;
-exports.normalizeSeedRefs = normalizeSeedRefs;
-const node_crypto_1 = require("node:crypto");
-const types_js_1 = require("../memory/types.js");
-const ref_js_1 = require("./ref.js");
-const channel_grant_js_1 = require("./channel-grant.js");
-const SCOPE_ORDER = {
-    project: 0,
-    channel: 1,
-    user: 2,
-    global: 3,
-};
-function assertScope(scope) {
-    if (!types_js_1.MEMORY_SCOPE_KINDS.includes(scope.kind)) {
-        throw new Error(`Unsupported memory scope kind: ${scope.kind}`);
-    }
-    const id = scope.id.trim();
-    if (id.length === 0) {
-        throw new Error('Memory scope id must not be empty');
-    }
-    return { kind: scope.kind, id };
-}
-function scopeKey(scope) {
-    return `${scope.kind}\0${scope.id}`;
-}
-function connectorKey(connector) {
-    const trimmed = connector.trim();
-    if (trimmed.length === 0) {
-        throw new Error('Connector must not be empty');
-    }
-    return trimmed;
-}
-function projectKey(project) {
-    const kind = project.kind.trim();
-    const id = project.id.trim();
-    if (kind.length === 0 || id.length === 0) {
-        throw new Error('Project ref kind and id must not be empty');
-    }
-    return `${kind}\0${id}`;
-}
-function sortScopes(scopes) {
-    return [...scopes].sort((left, right) => {
-        const orderDiff = SCOPE_ORDER[left.kind] - SCOPE_ORDER[right.kind];
-        if (orderDiff !== 0) {
-            return orderDiff;
-        }
-        return left.id.localeCompare(right.id);
-    });
-}
-function canonicalizeContextScopes(scopes) {
-    const unique = new Map();
-    for (const scope of scopes ?? []) {
-        const normalized = assertScope(scope);
-        unique.set(scopeKey(normalized), normalized);
-    }
-    const canonicalScopes = sortScopes([...unique.values()]);
-    const scopeJson = JSON.stringify(canonicalScopes);
-    const scopeHash = (0, node_crypto_1.createHash)('sha256').update(scopeJson).digest('hex');
-    return {
-        scopes: canonicalScopes,
-        scopeJson,
-        scopeHash,
-    };
-}
-function derivePrimaryContextScope(scopes) {
-    const canonical = canonicalizeContextScopes(scopes).scopes;
-    const primary = canonical.find((scope) => scope.kind === 'project') ?? canonical[0];
-    return primary ?? { kind: 'global', id: 'default' };
-}
-function assertContextBoundaryAllowsInput(input) {
-    const hasScopeBoundary = Array.isArray(input.boundary.scopes);
-    const boundaryScopes = canonicalizeContextScopes(input.boundary.scopes).scopes;
-    const requestedScopes = canonicalizeContextScopes(input.requestedScopes).scopes;
-    if (hasScopeBoundary && requestedScopes.length > 0) {
-        const allowed = new Set(boundaryScopes.map(scopeKey));
-        const disallowed = requestedScopes.find((scope) => !allowed.has(scopeKey(scope)));
-        if (disallowed) {
-            throw new Error(`Requested scope is outside the context boundary: ${disallowed.kind}:${disallowed.id}`);
-        }
-    }
-    const hasConnectorBoundary = Array.isArray(input.boundary.connectors);
-    const boundaryConnectors = new Set((input.boundary.connectors ?? []).map(connectorKey));
-    const requestedConnectors = (input.requestedConnectors ?? []).map(connectorKey);
-    if (hasConnectorBoundary) {
-        const disallowedConnector = requestedConnectors.find((connector) => !boundaryConnectors.has(connector));
-        if (disallowedConnector) {
-            throw new Error(`Requested connector is outside the context boundary: ${disallowedConnector}`);
-        }
-    }
-    const hasProjectBoundary = Array.isArray(input.boundary.project_refs);
-    const boundaryProjects = new Set((input.boundary.project_refs ?? []).map(projectKey));
-    const requestedProjects = (input.requestedProjectRefs ?? []).map(projectKey);
-    if (hasProjectBoundary && requestedProjects.length > 0) {
-        const disallowedProject = requestedProjects.find((project) => !boundaryProjects.has(project));
-        if (disallowedProject) {
-            const [kind, id] = disallowedProject.split('\0');
-            throw new Error(`Requested project ref is outside the context boundary: ${kind}:${id}`);
-        }
-    }
-    const boundaryTenantId = input.boundary.tenant_id;
-    if (typeof boundaryTenantId === 'string' &&
-        boundaryTenantId.length > 0 &&
-        input.requestedTenantId !== undefined &&
-        input.requestedTenantId !== null &&
-        input.requestedTenantId !== boundaryTenantId) {
-        throw new Error('Requested tenant is outside the context boundary');
-    }
-    const seedRefs = (0, ref_js_1.normalizeContextRefs)(input.seedRefs);
-    assertSeedRefsAllowed(seedRefs, boundaryConnectors, hasConnectorBoundary, input.boundary.channels);
-}
-/**
- * A seed ref must satisfy the same visibility rule as a row the reader would have returned.
- *
- * The connector check alone was never enough, and once raw visibility is decided by
- * (connector, channel) it is plainly not: a caller could name the raw id of an event in an
- * ungranted channel and have its identifiers - upstream source id and channel - come back
- * in the packet's source_refs, which is then persisted. That is a citation path reaching
- * past the reading path, the exact asymmetry this rebuild exists to remove.
- *
- * The channel is checked only when the boundary carries a grant. Without one there is no
- * channel rule to enforce and the connector check stands, unchanged.
- */
-function assertSeedRefsAllowed(seedRefs, boundaryConnectors, hasConnectorBoundary, channelGrant) {
-    for (const ref of seedRefs) {
-        if (ref.kind !== 'raw')
-            continue;
-        if (hasConnectorBoundary && !boundaryConnectors.has(ref.connector)) {
-            throw new Error(`Seed raw ref connector is outside the context boundary: ${ref.connector}`);
-        }
-        if (!channelGrant)
-            continue;
-        // Calls the shared rule rather than re-deriving membership. An inline re-derivation
-        // here already disagreed with it on the empty-channel case, which is how a fourth copy
-        // of a decision starts: not by being written as a copy, but by being written as
-        // "obviously the same check".
-        if (!(0, channel_grant_js_1.isChannelGranted)(ref.connector, ref.channel_id, channelGrant)) {
-            throw new Error(`Seed raw ref channel is outside the context boundary: ${ref.connector}`);
-        }
-    }
-}
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function collectHiddenIdentifiers(value, hidden) {
-    if (Array.isArray(value)) {
-        for (const item of value) {
-            collectHiddenIdentifiers(item, hidden);
-        }
-        return;
-    }
-    if (!isRecord(value)) {
-        return;
-    }
-    const maybeHidden = value;
-    if (maybeHidden.visible === false) {
-        for (const field of ['id', 'raw_id', 'source_id', 'channel_id']) {
-            const fieldValue = value[field];
-            if (typeof fieldValue === 'string' && fieldValue.length > 0) {
-                hidden.add(fieldValue);
-            }
-        }
-    }
-    for (const child of Object.values(value)) {
-        collectHiddenIdentifiers(child, hidden);
-    }
-}
-function isIdentifierBoundary(character) {
-    return character === undefined || !/[A-Za-z0-9_]/.test(character);
-}
-function containsHiddenIdentifier(value, identifier) {
-    if (identifier.length === 0) {
-        return false;
-    }
-    let index = value.indexOf(identifier);
-    while (index !== -1) {
-        const before = value[index - 1];
-        const after = value[index + identifier.length];
-        if (isIdentifierBoundary(before) && isIdentifierBoundary(after)) {
-            return true;
-        }
-        index = value.indexOf(identifier, index + 1);
-    }
-    return false;
-}
-function sanitizeValue(value, hidden) {
-    if (typeof value === 'string') {
-        return [...hidden].some((identifier) => containsHiddenIdentifier(value, identifier))
-            ? undefined
-            : value;
-    }
-    if (Array.isArray(value)) {
-        return value
-            .map((item) => sanitizeValue(item, hidden))
-            .filter((item) => item !== undefined);
-    }
-    if (!isRecord(value)) {
-        return value;
-    }
-    if (value.visible === false) {
-        return undefined;
-    }
-    const sanitized = {};
-    for (const [key, child] of Object.entries(value)) {
-        const next = sanitizeValue(child, hidden);
-        if (next !== undefined) {
-            sanitized[key] = next;
-        }
-    }
-    return sanitized;
-}
-function sanitizeContextPacketForVisibility(packet) {
-    const hidden = new Set();
-    collectHiddenIdentifiers(packet, hidden);
-    return sanitizeValue(packet, hidden);
-}
-function normalizeSeedRefs(seedRefs) {
-    return (0, ref_js_1.normalizeContextRefs)(seedRefs).map((ref) => (0, ref_js_1.normalizeContextRef)(ref));
-}
-//# sourceMappingURL=visibility.js.map

package/dist/decision-tracker.d.ts

@@ -1,206 +0,0 @@
-/**
- * MAMA (Memory-Augmented MCP Architecture) - Decision Tracker
- *
- * Learn and store decisions with graph relationships
- * Tasks: 3.1-3.9 (Learn decision, ID generation, supersedes edges, refinement, embeddings)
- * AC #1: Decision stored with outcome=NULL, confidence from LLM
- * AC #2: Supersedes relationship creation
- * AC #5: Multi-parent refinement with confidence calculation
- *
- * Updated for PostgreSQL compatibility via db-manager
- *
- * @module decision-tracker
- * @version 2.0
- * @date 2025-11-17
- */
-import type { DecisionRecord } from './db-manager.js';
-export type { DecisionRecord };
-export declare const VALID_EDGE_TYPES: readonly ["supersedes", "refines", "contradicts", "builds_on", "debates", "synthesizes"];
-export type EdgeType = (typeof VALID_EDGE_TYPES)[number];
-/**
- * Decision detection result from analysis
- */
-export interface DecisionDetection {
-    topic: string;
-    decision: string;
-    reasoning: string;
-    confidence: number;
-    type?: string;
-    trust_context?: Record<string, unknown>;
-    evidence?: string | string[];
-    alternatives?: string | string[];
-    risks?: string;
-}
-/**
- * Tool execution context
- */
-export interface ToolExecution {
-    timestamp?: number;
-    tool_name?: string;
-    tool_input?: unknown;
-    exit_code?: number;
-}
-/**
- * Session context for decision tracking
- */
-export interface SessionContext {
-    session_id?: string;
-    latest_user_message?: string;
-    recent_exchange?: string;
-}
-/**
- * Learn decision result
- */
-export interface LearnDecisionResult {
-    decisionId: string;
-    notification: unknown | null;
-}
-/**
- * Parsed relationship from reasoning
- */
-export interface ParsedRelationship {
-    type: string;
-    targetIds: string[];
-}
-/**
- * Generate decision ID
- *
- * Task 3.2: Generate decision ID: `decision_${topic}_${timestamp}`
- *
- * @param topic - Decision topic
- * @returns Decision ID
- */
-export declare function generateDecisionId(topic: string): string;
-/**
- * Check for previous decision on same topic
- *
- * Task 3.3: Query decisions table WHERE topic=? AND superseded_by IS NULL
- * AC #2: Find previous decision to create supersedes relationship
- *
- * @param topic - Decision topic
- * @returns Previous decision or null
- */
-export declare function getPreviousDecision(topic: string): Promise<DecisionRecord | null>;
-/**
- * Create a decision edge with specified relationship type
- *
- * Story 2.1: Generic edge creation supporting all relationship types
- *
- * @param fromId - Source decision ID
- * @param toId - Target decision ID
- * @param relationship - Edge type (supersedes, builds_on, debates, synthesizes, etc.)
- * @param reason - Reason for the relationship
- * @returns Success status
- */
-export declare function createEdge(fromId: string, toId: string, relationship: string, reason: string): Promise<boolean>;
-/**
- * Create supersedes edge
- *
- * Task 3.5: Create supersedes edge (INSERT INTO decision_edges)
- * AC #2: Supersedes relationship creation
- *
- * @param fromId - New decision ID
- * @param toId - Previous decision ID
- * @param reason - Reason for superseding
- */
-export declare function createSupersedesEdge(fromId: string, toId: string, reason: string): Promise<boolean>;
-/**
- * Update previous decision's superseded_by field
- *
- * Task 3.5: Update previous decision's superseded_by field
- * AC #2: Previous decision's superseded_by field updated
- *
- * @param previousId - Previous decision ID
- * @param newId - New decision ID
- */
-export declare function markSuperseded(previousId: string, newId: string): Promise<void>;
-/**
- * Calculate combined confidence (Bayesian update)
- *
- * Task 3.6: Calculate combined confidence for multi-parent refinement
- * AC #5: Confidence score calculated based on history
- *
- * @param prior - Prior confidence
- * @param parents - Parent decisions
- * @returns Updated confidence (0.0-1.0)
- */
-export declare function calculateCombinedConfidence(prior: number, parents: Array<{
-    confidence?: number;
-}>): number;
-/**
- * Detect multi-parent refinement
- *
- * Task 3.6: Detect if new decision refines multiple previous decisions
- * AC #5: Multi-parent refinement
- *
- * @param _detection - Decision detection result
- * @param _sessionContext - Session context
- * @returns Array of parent decision IDs or null
- */
-export declare function detectRefinement(_detection: DecisionDetection, _sessionContext: SessionContext): string[] | null;
-/**
- * Parse reasoning field for relationship references
- *
- * Story 2.2: Detect patterns like:
- * - builds_on: <decision_id>
- * - debates: <decision_id>
- * - synthesizes: [id1, id2]
- *
- * @param reasoning - Decision reasoning text
- * @returns Detected relationships
- */
-export declare function parseReasoningForRelationships(reasoning: string): ParsedRelationship[];
-/**
- * Create edges from parsed reasoning relationships
- *
- * Story 2.2: Auto-create edges when reasoning references other decisions
- *
- * @param fromId - Source decision ID
- * @param reasoning - Decision reasoning text
- * @returns Edge creation stats
- */
-export declare function createEdgesFromReasoning(fromId: string, reasoning: string): Promise<{
-    created: number;
-    failed: number;
-}>;
-/**
- * Learn Decision Function (Main API)
- *
- * Task 3.1: Create Learn Decision Function
- * Task 3.2: Generate decision ID
- * Task 3.3: Check for previous decision on same topic
- * Task 3.4: Insert new decision with outcome=NULL, confidence from LLM
- * Task 3.5: If previous exists: Create supersedes edge, Update previous superseded_by
- * Task 3.6: If multi-parent refinement: Store refined_from, Calculate combined confidence
- * Task 3.7: Generate enhanced embedding
- * Task 3.8: Store embedding (link via rowid)
- *
- * AC #1: Decision stored with outcome=NULL, confidence from LLM
- * AC #2: Supersedes relationship creation
- * AC #5: Multi-parent refinement with confidence calculation
- *
- * @param detection - Decision detection result
- * @param toolExecution - Tool execution data
- * @param sessionContext - Session context
- * @returns decisionId and notification
- */
-export declare function learnDecision(detection: DecisionDetection, toolExecution: ToolExecution, sessionContext: SessionContext): Promise<LearnDecisionResult>;
-/**
- * Evidence item for confidence updates
- */
-export interface EvidenceItem {
-    type: 'success' | 'failure' | 'partial';
-    impact: number;
-}
-/**
- * Update confidence score
- *
- * Task 6: Confidence evolution (used in outcome tracking)
- * AC #5: Confidence score calculated based on history
- *
- * @param prior - Prior confidence
- * @param evidence - Evidence items
- * @returns Updated confidence (0.0-1.0)
- */
-export declare function updateConfidence(prior: number, evidence: EvidenceItem[]): number;
-//# sourceMappingURL=decision-tracker.d.ts.map