@jungjaehoon/mama-core 1.6.0 → 1.7.0

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

@@ -0,0 +1,138 @@
+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;
+}
+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

@@ -0,0 +1,11 @@
+"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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,200 @@
+"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 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);
+}
+function assertSeedRefsAllowed(seedRefs, boundaryConnectors, hasConnectorBoundary) {
+    for (const ref of seedRefs) {
+        if (ref.kind === 'raw' && hasConnectorBoundary && !boundaryConnectors.has(ref.connector)) {
+            throw new Error(`Seed raw ref connector 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/db-adapter/node-sqlite-adapter.d.ts

@@ -55,11 +55,14 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     insertEmbedding(rowid: number, embedding: Float32Array | number[]): RunResult | null;
     getLastInsertRowid(): number;
     runMigrations(migrationsDir: string): void;
+    private repairSkippedFeatureMigrations;
+    private applyRepairMigration;
     private recoverMemoryProvenanceMigration032;
     private assertMigration032Complete;
     private recoverConnectorEventScopeMigration034;
     private assertMigration034Complete;
     private tableColumns;
+    private tableExists;
     private indexExists;
     private migrateFromVssMemories;
 }

package/dist/db-adapter/node-sqlite-adapter.js

@@ -350,12 +350,81 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
                 throw new Error(`Migration ${file} failed: ${message}`);
             }
         }
+        this.repairSkippedFeatureMigrations(migrationsDir);
         const embeddingsTables = this.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='embeddings'`).all();
         if (embeddingsTables.length === 0) {
             throw new Error('Embeddings table is missing after migrations. Add the required embeddings migration.');
         }
         this.migrateFromVssMemories();
     }
+    repairSkippedFeatureMigrations(migrationsDir) {
+        if (this.tableExists('decisions')) {
+            const decisionColumns = this.tableColumns('decisions');
+            const hasMissingMemoryProvenanceColumn = [
+                'agent_id',
+                'model_run_id',
+                'envelope_hash',
+                'gateway_call_id',
+                'source_refs_json',
+                'provenance_json',
+            ].some((column) => !decisionColumns.has(column));
+            const hasMissingMemoryProvenanceIndex = [
+                'idx_decisions_envelope_hash',
+                'idx_decisions_model_run_id',
+                'idx_decisions_gateway_call_id',
+                'idx_memory_events_memory_created',
+            ].some((indexName) => !this.indexExists(indexName));
+            if (hasMissingMemoryProvenanceColumn || hasMissingMemoryProvenanceIndex) {
+                this.recoverMemoryProvenanceMigration032();
+                (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped memory provenance migration');
+            }
+        }
+        if (!this.tableExists('model_runs') || !this.tableExists('tool_traces')) {
+            this.applyRepairMigration(migrationsDir, '033-create-model-runs-and-tool-traces.sql', 'model run provenance');
+        }
+        if (this.tableExists('connector_event_index')) {
+            const connectorColumns = this.tableColumns('connector_event_index');
+            const hasMissingConnectorScopeColumn = [
+                'source_cursor',
+                'tenant_id',
+                'project_id',
+                'memory_scope_kind',
+                'memory_scope_id',
+            ].some((column) => !connectorColumns.has(column));
+            if (hasMissingConnectorScopeColumn) {
+                this.recoverConnectorEventScopeMigration034();
+                (0, debug_logger_js_1.info)('[node-sqlite-adapter] Repaired skipped connector event scope migration');
+            }
+        }
+        if (!this.tableExists('twin_edges')) {
+            this.applyRepairMigration(migrationsDir, '035-create-twin-edges.sql', 'twin edge ledger');
+        }
+        if (!this.tableExists('agent_situation_packets') ||
+            !this.tableExists('agent_situation_refresh_leases')) {
+            this.applyRepairMigration(migrationsDir, '036-create-agent-situation-packets.sql', 'agent situation packet cache');
+        }
+        if (!this.tableExists('context_packets')) {
+            this.applyRepairMigration(migrationsDir, '037-create-context-packets.sql', 'context packet store');
+        }
+    }
+    applyRepairMigration(migrationsDir, fileName, label) {
+        const migrationPath = path_1.default.join(migrationsDir, fileName);
+        if (!fs_1.default.existsSync(migrationPath)) {
+            throw new Error(`Missing repair migration ${fileName} for ${label}`);
+        }
+        const migrationSQL = fs_1.default.readFileSync(migrationPath, 'utf8');
+        (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Repairing skipped ${label} migration: ${fileName}`);
+        try {
+            this.transaction(() => {
+                this.exec(migrationSQL);
+            });
+            (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Repair migration ${fileName} applied successfully`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Repair migration ${fileName} failed: ${message}`);
+        }
+    }
     recoverMemoryProvenanceMigration032() {
         this.transaction(() => {
             const expectedDecisionColumns = [
@@ -472,6 +541,13 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         const rows = this.prepare(`PRAGMA table_info(${tableName})`).all();
         return new Set(rows.map((row) => row.name));
     }
+    tableExists(tableName) {
+        if (!SQLITE_IDENTIFIER_PATTERN.test(tableName)) {
+            throw new Error('Invalid SQLite table identifier');
+        }
+        const row = this.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?").get(tableName);
+        return row?.name === tableName;
+    }
     indexExists(indexName) {
         const row = this.prepare("SELECT name FROM sqlite_master WHERE type='index' AND name = ?").get(indexName);
         return row?.name === indexName;

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/embeddings.d.ts

@@ -11,6 +11,9 @@
  */
 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 declare function prepareEmbeddingText(text: string): string;
 /**
  * Decision object for enhanced embedding generation
  */