@jungjaehoon/mama-core 1.6.0 → 1.8.1

package/dist/edges/ref-validation.js

@@ -9,15 +9,15 @@ const TABLE_COLUMN_PRAGMAS = {
     case_truth: 'PRAGMA table_info(case_truth)',
 };
 const tableColumnCache = new WeakMap();
+// Keep memory-truth quarantine semantics excluded for legacy/backcompat rows even though the
+// current decisions.status CHECK only admits superseded/contradicted/stale terminal states.
+const EXCLUDED_MEMORY_STATUSES = new Set(['superseded', 'quarantined', 'contradicted', 'stale']);
 function scopeKey(scope) {
     return `${scope.kind}\0${scope.id}`;
 }
 function hasScopes(scopes) {
     return Array.isArray(scopes) && scopes.length > 0;
 }
-function hasConnectors(connectors) {
-    return Array.isArray(connectors) && connectors.length > 0;
-}
 function hasProjectRefs(projectRefs) {
     return Array.isArray(projectRefs) && projectRefs.length > 0;
 }
@@ -27,16 +27,33 @@ function visibilityFromScopes(scopes) {
 function asOfMs(visibility) {
     return typeof visibility.asOfMs === 'number' ? visibility.asOfMs : null;
 }
-function isAtOrBeforeAsOf(value, visibility) {
+function startMs(visibility) {
+    return typeof visibility.startMs === 'number' ? visibility.startMs : null;
+}
+function isWithinVisibilityTime(value, visibility) {
+    const start = startMs(visibility);
     const asOf = asOfMs(visibility);
-    return asOf === null || (typeof value === 'number' && value <= asOf);
+    if (start === null && asOf === null) {
+        return true;
+    }
+    return (typeof value === 'number' &&
+        (start === null || value >= start) &&
+        (asOf === null || value <= asOf));
 }
 function parseTimestamp(value) {
     if (typeof value === 'number' && Number.isFinite(value)) {
         return Math.floor(value);
     }
     if (typeof value === 'string') {
-        const parsed = Date.parse(value);
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        const numeric = Number(trimmed);
+        if (Number.isFinite(numeric)) {
+            return Math.floor(numeric);
+        }
+        const parsed = Date.parse(trimmed);
         return Number.isFinite(parsed) ? parsed : null;
     }
     return null;
@@ -61,9 +78,14 @@ function tableColumns(adapter, table) {
     return columns;
 }
 function isMemoryVisible(adapter, id, visibility) {
+    const columns = tableColumns(adapter, 'decisions');
+    const statusSelect = columns.has('status') ? 'status' : 'NULL AS status';
+    const supersededBySelect = columns.has('superseded_by')
+        ? 'superseded_by'
+        : 'NULL AS superseded_by';
     const row = adapter
         .prepare(`
-        SELECT created_at, event_datetime
+        SELECT created_at, event_datetime, ${statusSelect}, ${supersededBySelect}
         FROM decisions
         WHERE id = ?
         LIMIT 1
@@ -72,7 +94,12 @@ function isMemoryVisible(adapter, id, visibility) {
     if (!row) {
         return false;
     }
-    if (!isAtOrBeforeAsOf(row.event_datetime ?? row.created_at, visibility)) {
+    const status = typeof row.status === 'string' ? row.status : 'active';
+    if (EXCLUDED_MEMORY_STATUSES.has(status) ||
+        (typeof row.superseded_by === 'string' && row.superseded_by.length > 0)) {
+        return false;
+    }
+    if (!isWithinVisibilityTime(row.event_datetime ?? row.created_at, visibility)) {
         return false;
     }
     const scopes = visibility.scopes;
@@ -94,7 +121,6 @@ function isMemoryVisible(adapter, id, visibility) {
     if (bindingRow?.ok) {
         return true;
     }
-    const columns = tableColumns(adapter, 'decisions');
     if (columns.has('memory_scope_kind') && columns.has('memory_scope_id')) {
         const row = adapter
             .prepare(`
@@ -133,7 +159,7 @@ function isCaseVisible(adapter, id, visibility) {
         return false;
     }
     const timestamp = parseTimestamp(row.last_activity_at) ?? parseTimestamp(row.updated_at);
-    if (!isAtOrBeforeAsOf(timestamp, visibility)) {
+    if (!isWithinVisibilityTime(timestamp, visibility)) {
         return false;
     }
     const scopes = visibility.scopes;
@@ -158,7 +184,7 @@ function isRawVisible(adapter, id, visibility) {
     if (!row) {
         return false;
     }
-    if (hasConnectors(visibility.connectors) &&
+    if (Array.isArray(visibility.connectors) &&
         !visibility.connectors.includes(String(row.source_connector))) {
         return false;
     }
@@ -171,7 +197,12 @@ function isRawVisible(adapter, id, visibility) {
         row.tenant_id !== visibility.tenantId) {
         return false;
     }
-    if (!isAtOrBeforeAsOf(Number(row.event_datetime ?? row.source_timestamp_ms), visibility)) {
+    const rawTs = row.event_datetime ?? row.source_timestamp_ms;
+    if (rawTs === null || rawTs === undefined || (typeof rawTs === 'string' && rawTs.trim() === '')) {
+        return false;
+    }
+    const eventTsMs = parseTimestamp(rawTs);
+    if (eventTsMs === null || eventTsMs < 0 || !isWithinVisibilityTime(eventTsMs, visibility)) {
         return false;
     }
     if (!hasScopes(visibility.scopes)) {
@@ -186,7 +217,7 @@ function isEntityVisible(adapter, id, visibility) {
     if (!row) {
         return false;
     }
-    if (!isAtOrBeforeAsOf(row.created_at, visibility)) {
+    if (!isWithinVisibilityTime(row.created_at, visibility)) {
         return false;
     }
     const scopes = visibility.scopes;
@@ -222,7 +253,7 @@ function isTwinRefVisible(adapter, ref, visibility, visitedEdges, edgeCache) {
     if (!edge) {
         return false;
     }
-    if (!isAtOrBeforeAsOf(edge.created_at, visibility)) {
+    if (!isWithinVisibilityTime(edge.created_at, visibility)) {
         return false;
     }
     const pathWithCurrent = new Set(visitedEdges);
@@ -245,13 +276,21 @@ function listVisibleTwinEdgesForRefs(adapter, refs, options = {}) {
     const edgeCache = new Map();
     const edgeTypes = normalizeEdgeTypes(options.edgeTypes);
     const edges = (0, store_js_1.listTwinEdgesForRefs)(adapter, refs).filter((edge) => (edgeTypes.size === 0 || edgeTypes.has(edge.edge_type)) &&
+        (typeof options.startMs !== 'number' || edge.created_at >= options.startMs) &&
         (typeof options.asOfMs !== 'number' || edge.created_at <= options.asOfMs) &&
         isTwinRefVisible(adapter, edge.subject_ref, options, new Set(), edgeCache) &&
         isTwinRefVisible(adapter, edge.object_ref, options, new Set(), edgeCache));
     const limit = typeof options.limit === 'number' && Number.isFinite(options.limit)
         ? Math.max(0, Math.floor(options.limit))
-        : edges.length;
-    return edges.slice(0, limit);
+        : null;
+    const sortedEdges = [...edges].sort((left, right) => {
+        const createdDiff = right.created_at - left.created_at;
+        return createdDiff !== 0 ? createdDiff : left.edge_id.localeCompare(right.edge_id);
+    });
+    if (limit === null) {
+        return sortedEdges;
+    }
+    return sortedEdges.slice(0, limit);
 }
 function normalizeEdgeTypes(edgeTypes) {
     if (!Array.isArray(edgeTypes) || edgeTypes.length === 0) {

package/dist/edges/types.d.ts

@@ -27,6 +27,7 @@ export interface TwinVisibility {
     connectors?: string[];
     projectRefs?: TwinProjectRef[];
     tenantId?: string | null;
+    startMs?: number | null;
     asOfMs?: number | null;
 }
 export interface InsertTwinEdgeInput {
@@ -80,6 +81,7 @@ export interface ListVisibleTwinEdgesOptions {
     projectRefs?: TwinProjectRef[];
     tenantId?: string | null;
     edgeTypes?: TwinEdgeType[];
+    startMs?: number | null;
     asOfMs?: number | null;
     limit?: number;
 }

package/dist/embedding-client.d.ts

@@ -11,6 +11,7 @@
  *
  * @module embedding-client
  */
+import type { EmbeddingRole } from './embeddings.js';
 export declare const DEFAULT_PORT: number;
 export declare const HOST = "127.0.0.1";
 export declare const TIMEOUT_MS = 500;
@@ -33,9 +34,10 @@ export declare function isServerRunning(): Promise<boolean>;
  * Generate embedding via HTTP server
  *
  * @param text - Text to embed
+ * @param role - e5 role: 'passage' (default, stored text) or 'query' (search)
  * @returns Embedding or null if failed
  */
-export declare function getEmbeddingFromServer(text: string): Promise<Float32Array | null>;
+export declare function getEmbeddingFromServer(text: string, role?: EmbeddingRole): Promise<Float32Array | null>;
 /**
  * Get server status
  */

package/dist/embedding-client.js

@@ -76,9 +76,10 @@ async function isServerRunning() {
  * Generate embedding via HTTP server
  *
  * @param text - Text to embed
+ * @param role - e5 role: 'passage' (default, stored text) or 'query' (search)
  * @returns Embedding or null if failed
  */
-async function getEmbeddingFromServer(text) {
+async function getEmbeddingFromServer(text, role = 'passage') {
     const port = getServerPort();
     try {
         const controller = new AbortController();
@@ -86,7 +87,7 @@ async function getEmbeddingFromServer(text) {
         const response = await fetch(`http://${exports.HOST}:${port}/embed`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ text }),
+            body: JSON.stringify({ text, role }),
             signal: controller.signal,
         });
         clearTimeout(timeout);

package/dist/embedding-server/index.d.ts

@@ -14,6 +14,7 @@
  */
 import type { IncomingMessage, ServerResponse, Server as HTTPServer } from 'http';
 export declare const SHUTDOWN_TOKEN: string;
+import type { EmbeddingRole } from '../embeddings.js';
 export declare const DEFAULT_PORT: number;
 export declare const HOST = "127.0.0.1";
 export declare const PORT_FILE: string;
@@ -42,6 +43,7 @@ export interface ServerOptions {
     sessionStore?: SessionStore;
     graphHandler?: RequestHandler;
 }
+export declare function resolveEmbeddingRole(raw: unknown): EmbeddingRole;
 /**
  * Clean up port file on exit
  */

package/dist/embedding-server/index.js

@@ -18,6 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PORT_FILE = exports.HOST = exports.DEFAULT_PORT = exports.SHUTDOWN_TOKEN = void 0;
+exports.resolveEmbeddingRole = resolveEmbeddingRole;
 exports.cleanupPortFile = cleanupPortFile;
 exports.startEmbeddingServer = startEmbeddingServer;
 exports.warmModel = warmModel;
@@ -63,6 +64,11 @@ const connections = new Set();
 // Graph handler (optional, passed from standalone)
 let graphHandler = null;
 let _wssInstance = null;
+// Resolve the e5 role from an HTTP body value. Absent/unknown -> passage, so old
+// clients that never send a role keep getting passage vectors (backward compatible).
+function resolveEmbeddingRole(raw) {
+    return raw === 'query' ? 'query' : 'passage';
+}
 /**
  * Read request body as JSON
  */
@@ -158,7 +164,8 @@ async function handleRequest(req, res) {
                 res.end(JSON.stringify({ error: 'Missing or invalid "text" field' }));
                 return;
             }
-            const embedding = await (0, embeddings_js_1.generateEmbedding)(body.text);
+            const role = resolveEmbeddingRole(body.role);
+            const embedding = await (0, embeddings_js_1.generateEmbedding)(body.text, role);
             modelLoaded = true;
             const latency = Date.now() - startTime;
             res.writeHead(200);
@@ -186,7 +193,8 @@ async function handleRequest(req, res) {
                 res.end(JSON.stringify({ error: 'Missing or invalid "texts" array' }));
                 return;
             }
-            const embeddings = await Promise.all(body.texts.map((text) => (0, embeddings_js_1.generateEmbedding)(text).then((e) => Array.from(e))));
+            const role = resolveEmbeddingRole(body.role);
+            const embeddings = await Promise.all(body.texts.map((text) => (0, embeddings_js_1.generateEmbedding)(text, role).then((e) => Array.from(e))));
             modelLoaded = true;
             const latency = Date.now() - startTime;
             res.writeHead(200);

package/dist/embeddings.d.ts

@@ -11,6 +11,11 @@
  */
 import { embeddingCache } from './embedding-cache.js';
 import { loadConfig, getModelName, getEmbeddingDim, getQuantized } from './config-loader.js';
+export declare const EMBEDDING_MODEL_MAX_LENGTH = 512;
+export declare const EMBEDDING_MAX_TOKENISH_SEGMENTS = 480;
+export type EmbeddingRole = 'passage' | 'query';
+export declare const EMBEDDING_PREFIX_SCHEME = "e5-prefixed-v1";
+export declare function prepareEmbeddingText(text: string): string;
 /**
  * Decision object for enhanced embedding generation
  */
@@ -35,7 +40,7 @@ export interface DecisionForEmbedding {
  * @returns Embedding vector (dimension from config)
  * @throws Error if text is empty or embedding fails
  */
-export declare function generateEmbedding(text: string): Promise<Float32Array>;
+export declare function generateEmbedding(text: string, role?: EmbeddingRole): Promise<Float32Array>;
 /**
  * Generate enhanced embedding with content + metadata
  *
@@ -45,7 +50,7 @@ export declare function generateEmbedding(text: string): Promise<Float32Array>;
  * @param decision - Decision object
  * @returns 1024-dim enhanced embedding
  */
-export declare function generateEnhancedEmbedding(decision: DecisionForEmbedding): Promise<Float32Array>;
+export declare function generateEnhancedEmbedding(decision: DecisionForEmbedding, role?: EmbeddingRole): Promise<Float32Array>;
 /**
  * Batch generate embeddings (optimized)
  *
@@ -57,7 +62,7 @@ export declare function generateEnhancedEmbedding(decision: DecisionForEmbedding
  * @param texts - Array of texts to embed (max 10 per batch)
  * @returns Array of embeddings
  */
-export declare function generateBatchEmbeddings(texts: string[]): Promise<Float32Array[]>;
+export declare function generateBatchEmbeddings(texts: string[], role?: EmbeddingRole): Promise<Float32Array[]>;
 /**
  * Calculate cosine similarity between two embeddings
  *

package/dist/embeddings.js

@@ -14,7 +14,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getQuantized = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = void 0;
+exports.getQuantized = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.EMBEDDING_PREFIX_SCHEME = exports.EMBEDDING_MAX_TOKENISH_SEGMENTS = exports.EMBEDDING_MODEL_MAX_LENGTH = void 0;
+exports.prepareEmbeddingText = prepareEmbeddingText;
 exports.generateEmbedding = generateEmbedding;
 exports.generateEnhancedEmbedding = generateEnhancedEmbedding;
 exports.generateBatchEmbeddings = generateBatchEmbeddings;
@@ -33,6 +34,13 @@ Object.defineProperty(exports, "getQuantized", { enumerable: true, get: function
 // Shared cache directory (not in node_modules)
 const DEFAULT_CACHE_DIR = path_1.default.join(os_1.default.homedir(), '.cache', 'huggingface', 'transformers');
 const TIER3_ENV_VALUES = new Set(['1', 'true', 'yes']);
+exports.EMBEDDING_MODEL_MAX_LENGTH = 512;
+exports.EMBEDDING_MAX_TOKENISH_SEGMENTS = 480;
+exports.EMBEDDING_PREFIX_SCHEME = 'e5-prefixed-v1';
+function applyRolePrefix(preparedText, role) {
+    return `${role}: ${preparedText}`;
+}
+const TOKENISH_SEGMENT_PATTERN = /[\p{Script=Hangul}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]|\S+/gu;
 // Singleton pattern for model loading
 let embeddingPipeline = null;
 let currentModelName = null;
@@ -46,6 +54,19 @@ function assertEmbeddingsEnabled() {
             'Tier 3 test mode must use lexical/no-vector fallback instead of loading the embedding model.');
     }
 }
+function prepareEmbeddingText(text) {
+    const trimmed = text.trim();
+    let count = 0;
+    let cutIndex = trimmed.length;
+    for (const match of trimmed.matchAll(TOKENISH_SEGMENT_PATTERN)) {
+        count++;
+        if (count > exports.EMBEDDING_MAX_TOKENISH_SEGMENTS) {
+            cutIndex = match.index ?? trimmed.length;
+            break;
+        }
+    }
+    return cutIndex === trimmed.length ? trimmed : trimmed.slice(0, cutIndex).trimEnd();
+}
 /**
  * Load embedding model (configurable)
  *
@@ -111,13 +132,15 @@ async function loadModel() {
  * @returns Embedding vector (dimension from config)
  * @throws Error if text is empty or embedding fails
  */
-async function generateEmbedding(text) {
-    if (!text || text.trim().length === 0) {
+async function generateEmbedding(text, role = 'passage') {
+    if (typeof text !== 'string' || text.trim().length === 0) {
         throw new Error('Text cannot be empty');
     }
     assertEmbeddingsEnabled();
-    // Task 2: Check cache first (AC #3)
-    const cached = embedding_cache_js_1.embeddingCache.get(text);
+    const preparedText = prepareEmbeddingText(text);
+    const modelInput = applyRolePrefix(preparedText, role); // e5 instruction prefix
+    // Cache key is the PREFIXED input: a passage vector can never be served for a query.
+    const cached = embedding_cache_js_1.embeddingCache.get(modelInput);
     if (cached) {
         return cached;
     }
@@ -126,9 +149,11 @@ async function generateEmbedding(text) {
         const model = await loadModel();
         const expectedDim = (0, config_loader_js_1.getEmbeddingDim)();
         // Generate embedding
-        const output = await model(text, {
+        const output = await model(modelInput, {
             pooling: 'mean', // Mean pooling over tokens
             normalize: true, // L2 normalization
+            truncation: true,
+            max_length: exports.EMBEDDING_MODEL_MAX_LENGTH,
         });
         // Extract Float32Array
         const embedding = output.data;
@@ -139,7 +164,7 @@ async function generateEmbedding(text) {
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const _latency = Date.now() - startTime;
         // Task 2: Store in cache (AC #3)
-        embedding_cache_js_1.embeddingCache.set(text, embedding);
+        embedding_cache_js_1.embeddingCache.set(modelInput, embedding);
         return embedding;
     }
     catch (error) {
@@ -156,7 +181,7 @@ async function generateEmbedding(text) {
  * @param decision - Decision object
  * @returns 1024-dim enhanced embedding
  */
-async function generateEnhancedEmbedding(decision) {
+async function generateEnhancedEmbedding(decision, role = 'passage') {
     // Construct enriched text representation with narrative fields (Story 2.2)
     const parts = [
         `Topic: ${decision.topic}`,
@@ -187,7 +212,7 @@ async function generateEnhancedEmbedding(decision) {
         parts.push(`Risks: ${decision.risks}`);
     }
     const enrichedText = parts.join('\n').trim();
-    return generateEmbedding(enrichedText);
+    return generateEmbedding(enrichedText, role);
 }
 /**
  * Batch generate embeddings (optimized)
@@ -200,26 +225,34 @@ async function generateEnhancedEmbedding(decision) {
  * @param texts - Array of texts to embed (max 10 per batch)
  * @returns Array of embeddings
  */
-async function generateBatchEmbeddings(texts) {
-    assertEmbeddingsEnabled();
+async function generateBatchEmbeddings(texts, role = 'passage') {
     if (!Array.isArray(texts) || texts.length === 0) {
         throw new Error('Texts must be a non-empty array');
     }
-    // Validate all texts
     for (const text of texts) {
-        if (!text || text.trim().length === 0) {
-            throw new Error('All texts must be non-empty');
+        if (typeof text !== 'string' || text.trim().length === 0) {
+            throw new Error('All texts must be non-empty strings');
+        }
+    }
+    assertEmbeddingsEnabled();
+    const preparedTexts = texts.map((text) => prepareEmbeddingText(text));
+    for (const text of preparedTexts) {
+        if (!text || text.length === 0) {
+            throw new Error('All texts must be non-empty strings');
         }
     }
+    const modelInputs = preparedTexts.map((t) => applyRolePrefix(t, role));
     const startTime = Date.now();
     try {
         const model = await loadModel();
         const expectedDim = (0, config_loader_js_1.getEmbeddingDim)();
         // Native batch processing - single model forward pass
         // This is significantly faster than sequential calls
-        const outputs = await model(texts, {
+        const outputs = await model(modelInputs, {
             pooling: 'mean',
             normalize: true,
+            truncation: true,
+            max_length: exports.EMBEDDING_MODEL_MAX_LENGTH,
         });
         // Extract embeddings from batch output
         const embeddings = [];

package/dist/entities/store.d.ts

@@ -13,9 +13,11 @@ export declare class EntityMergeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+declare const OBSERVATION_CONTEXT_KEY_COLUMNS: readonly ["workspace_context_key", "channel_context_key", "thread_context_key", "actor_context_key"];
 type CreateEntityNodeInput = Omit<EntityNode, 'created_at' | 'updated_at'>;
 type AttachEntityAliasInput = Omit<EntityAlias, 'created_at'>;
-type UpsertEntityObservationInput = Omit<EntityObservation, 'created_at'>;
+type ObservationContextKeyColumn = (typeof OBSERVATION_CONTEXT_KEY_COLUMNS)[number];
+type UpsertEntityObservationInput = Omit<EntityObservation, 'created_at'> & Partial<Record<ObservationContextKeyColumn, string | null>>;
 type AppendEntityTimelineEventInput = {
     event: Omit<EntityTimelineEvent, 'id' | 'created_at'> & {
         id?: string;
@@ -27,6 +29,7 @@ export interface UpsertEntityObservationResult {
     id: string;
     created: boolean;
 }
+export declare function clearEntityTableColumnCache(adapter: EntityStoreAdapter): void;
 export declare function parseObservationRow(row: Record<string, unknown>): EntityObservation;
 export declare function createEntityNode(input: CreateEntityNodeInput): Promise<EntityNode>;
 export declare function getEntityNode(id: string, adapter?: EntityStoreAdapter): EntityNode | null;