ai-memory-layer 2.0.1 → 3.0.0

package/dist/core/associations.js

@@ -0,0 +1,185 @@
+import { UniqueConstraintError } from '../contracts/storage.js';
+export async function traverseAssociations(adapter, scope, startKind, startId, options = {}) {
+    if (!Number.isInteger(startId) || startId <= 0) {
+        throw new Error(`traverseAssociations: startId must be a positive integer, got ${startId}`);
+    }
+    const maxDepth = normalizeTraversalBound(options.maxDepth, 2, 'maxDepth');
+    const maxNodes = normalizeTraversalBound(options.maxNodes, 20, 'maxNodes');
+    const visitedKey = (kind, id) => `${kind}:${id}`;
+    const visited = new Set();
+    const nodes = [];
+    const edges = [];
+    const edgeIds = new Set();
+    // Cap includes the start node. If maxNodes is 0 (or effectively unusable),
+    // return an empty graph rather than silently allowing a single-node result.
+    if (maxNodes < 1) {
+        return { nodes, edges };
+    }
+    const queue = [
+        { kind: startKind, id: startId, depth: 0 },
+    ];
+    visited.add(visitedKey(startKind, startId));
+    nodes.push({ kind: startKind, id: startId });
+    while (queue.length > 0 && nodes.length < maxNodes) {
+        const current = queue.shift();
+        if (current.depth >= maxDepth)
+            continue;
+        const [fromEdges, toEdges] = await Promise.all([
+            adapter.getAssociationsFrom(current.kind, current.id, scope),
+            adapter.getAssociationsTo(current.kind, current.id, scope),
+        ]);
+        for (const edge of [...fromEdges, ...toEdges]) {
+            if (edgeIds.has(edge.id))
+                continue;
+            // Determine the neighbor from the edge
+            const neighborKind = edge.source_kind === current.kind && edge.source_id === current.id
+                ? edge.target_kind
+                : edge.source_kind;
+            const neighborId = edge.source_kind === current.kind && edge.source_id === current.id
+                ? edge.target_id
+                : edge.source_id;
+            const key = visitedKey(neighborKind, neighborId);
+            const neighborAlreadyVisited = visited.has(key);
+            if (!neighborAlreadyVisited && nodes.length < maxNodes) {
+                visited.add(key);
+                nodes.push({ kind: neighborKind, id: neighborId });
+                queue.push({ kind: neighborKind, id: neighborId, depth: current.depth + 1 });
+            }
+            const neighborInNodeSet = neighborAlreadyVisited ||
+                nodes.some((node) => node.kind === neighborKind && node.id === neighborId);
+            if (neighborInNodeSet) {
+                edgeIds.add(edge.id);
+                edges.push(edge);
+            }
+        }
+    }
+    return { nodes, edges };
+}
+function normalizeTraversalBound(value, defaultValue, name) {
+    if (value === undefined)
+        return defaultValue;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`traverseAssociations: ${name} must be a non-negative integer, got ${value}`);
+    }
+    return value;
+}
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 2));
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union > 0 ? intersection / union : 0;
+}
+function detectRelationType(source, target, similarity) {
+    const sameSlot = Boolean(source.slot_key) &&
+        Boolean(target.slot_key) &&
+        source.slot_key === target.slot_key;
+    // Contradiction: same slot key with either negation mismatch OR
+    // divergent fact text (different values asserted for the same slot).
+    // Slot facts are assertions like "deploy:region = us-east-1" vs
+    // "deploy:region = eu-west-1" — they must not be collapsed into supports.
+    if (sameSlot) {
+        const negationMismatch = source.is_negated !== target.is_negated;
+        const divergentValues = !negationMismatch && similarity < 0.9;
+        if (negationMismatch || divergentValues) {
+            return 'contradicts';
+        }
+    }
+    // Supersedes: same slot key, same polarity, target is newer, facts align
+    if (sameSlot &&
+        source.is_negated === target.is_negated &&
+        target.created_at > source.created_at &&
+        similarity >= 0.9) {
+        return 'supersedes';
+    }
+    // Supports: high similarity + same polarity (and not same-slot-divergent)
+    if (similarity >= 0.4 && source.is_negated === target.is_negated) {
+        return 'supports';
+    }
+    // Related: moderate similarity
+    if (similarity >= 0.25) {
+        return 'related_to';
+    }
+    return null;
+}
+export async function autoDetectAssociations(adapter, scope, newKnowledge, existingKnowledge) {
+    const created = [];
+    const newTokens = tokenize(newKnowledge.fact);
+    for (const existing of existingKnowledge) {
+        if (existing.id === newKnowledge.id)
+            continue;
+        const similarity = jaccardSimilarity(newTokens, tokenize(existing.fact));
+        const relationType = detectRelationType(existing, newKnowledge, similarity);
+        if (!relationType)
+            continue;
+        // For supersedes, new knowledge is the source (it supersedes the old)
+        const sourceId = relationType === 'supersedes' ? newKnowledge.id : existing.id;
+        const targetId = relationType === 'supersedes' ? existing.id : newKnowledge.id;
+        try {
+            const association = await adapter.insertAssociation({
+                tenant_id: newKnowledge.tenant_id,
+                system_id: newKnowledge.system_id,
+                workspace_id: newKnowledge.workspace_id,
+                collaboration_id: newKnowledge.collaboration_id,
+                scope_id: newKnowledge.scope_id,
+                source_kind: 'knowledge',
+                source_id: sourceId,
+                target_kind: 'knowledge',
+                target_id: targetId,
+                association_type: relationType,
+                confidence: similarity,
+                auto_generated: true,
+            });
+            created.push(association);
+        }
+        catch (err) {
+            if (!isUniqueConstraintError(err)) {
+                throw err;
+            }
+            // Unique constraint violation — association already exists, skip
+        }
+    }
+    return created;
+}
+/**
+ * Detect whether an adapter error represents a duplicate-edge unique
+ * constraint violation.
+ *
+ * All bundled adapters throw the structured `UniqueConstraintError` class.
+ * The code/message fallbacks below exist only for defence-in-depth against
+ * third-party or older adapter implementations that have not adopted the
+ * typed error yet.
+ */
+function isUniqueConstraintError(err) {
+    if (err instanceof UniqueConstraintError)
+        return true;
+    if (!err || typeof err !== 'object')
+        return false;
+    const anyErr = err;
+    if (anyErr.kind === 'UniqueConstraintError')
+        return true;
+    // Postgres: 23505 unique_violation
+    if (anyErr.code === '23505')
+        return true;
+    // better-sqlite3: SQLITE_CONSTRAINT_UNIQUE
+    if (anyErr.code === 'SQLITE_CONSTRAINT_UNIQUE')
+        return true;
+    const message = typeof anyErr.message === 'string' ? anyErr.message : '';
+    if (message.includes('Association already exists'))
+        return true;
+    if (message.toLowerCase().includes('unique constraint'))
+        return true;
+    return false;
+}
+//# sourceMappingURL=associations.js.map

package/dist/core/associations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"associations.js","sourceRoot":"","sources":["../../src/core/associations.ts"],"names":[],"mappings":"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"}

package/dist/core/circuit-breaker.d.ts

@@ -3,9 +3,18 @@ export interface CircuitBreakerOptions {
     failureThreshold?: number;
     resetTimeoutMs?: number;
 }
+export interface CircuitBreakerSnapshot {
+    state: CircuitState;
+    failures: number;
+    failureThreshold: number;
+    resetTimeoutMs: number;
+    openedAt: number | null;
+    nextProbeAt: number | null;
+}
 export interface CircuitBreaker {
     readonly state: CircuitState;
     execute<T>(run: () => Promise<T>): Promise<T>;
+    getSnapshot(): CircuitBreakerSnapshot;
 }
 export declare function createCircuitBreaker(options?: CircuitBreakerOptions): CircuitBreaker;
 //# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/core/circuit-breaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAuCxF"}
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9C,WAAW,IAAI,sBAAsB,CAAC;CACvC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAmDxF"}

package/dist/core/circuit-breaker.js

@@ -1,3 +1,4 @@
+import { ProviderUnavailableError } from '../contracts/errors.js';
 export function createCircuitBreaker(options = {}) {
     const failureThreshold = options.failureThreshold ?? 3;
     const resetTimeoutMs = options.resetTimeoutMs ?? 30_000;
@@ -13,7 +14,7 @@ export function createCircuitBreaker(options = {}) {
         },
         async execute(run) {
             if (state === 'open' && !canProbe()) {
-                throw new Error('Circuit breaker is open');
+                throw new ProviderUnavailableError('Circuit breaker is open');
             }
             if (canProbe()) {
                 state = 'half_open';
@@ -33,6 +34,17 @@ export function createCircuitBreaker(options = {}) {
                 throw error;
             }
         },
+        getSnapshot() {
+            const effectiveState = canProbe() ? 'half_open' : state;
+            return {
+                state: effectiveState,
+                failures,
+                failureThreshold,
+                resetTimeoutMs,
+                openedAt: openedAt > 0 ? openedAt : null,
+                nextProbeAt: state === 'open' ? openedAt + resetTimeoutMs : null,
+            };
+        },
     };
 }
 //# sourceMappingURL=circuit-breaker.js.map

package/dist/core/circuit-breaker.js.map

@@ -1 +1 @@
-{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,oBAAoB,CAAC,UAAiC,EAAE;IACtE,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC;IACvD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC;IACxD,IAAI,KAAK,GAAiB,QAAQ,CAAC;IACnC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,SAAS,QAAQ;QACf,OAAO,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,IAAI,cAAc,CAAC;IACrE,CAAC;IAED,OAAO;QACL,IAAI,KAAK;YACP,OAAO,QAAQ,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,OAAO,CAAI,GAAqB;YACpC,IAAI,KAAK,KAAK,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC;YACD,IAAI,QAAQ,EAAE,EAAE,CAAC;gBACf,KAAK,GAAG,WAAW,CAAC;YACtB,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;gBAC3B,QAAQ,GAAG,CAAC,CAAC;gBACb,KAAK,GAAG,QAAQ,CAAC;gBACjB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,IAAI,CAAC,CAAC;gBACd,IAAI,QAAQ,IAAI,gBAAgB,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;oBAC1D,KAAK,GAAG,MAAM,CAAC;oBACf,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACxB,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/core/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAwBlE,MAAM,UAAU,oBAAoB,CAAC,UAAiC,EAAE;IACtE,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC;IACvD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC;IACxD,IAAI,KAAK,GAAiB,QAAQ,CAAC;IACnC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,SAAS,QAAQ;QACf,OAAO,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,IAAI,cAAc,CAAC;IACrE,CAAC;IAED,OAAO;QACL,IAAI,KAAK;YACP,OAAO,QAAQ,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,OAAO,CAAI,GAAqB;YACpC,IAAI,KAAK,KAAK,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACpC,MAAM,IAAI,wBAAwB,CAAC,yBAAyB,CAAC,CAAC;YAChE,CAAC;YACD,IAAI,QAAQ,EAAE,EAAE,CAAC;gBACf,KAAK,GAAG,WAAW,CAAC;YACtB,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC;gBAC3B,QAAQ,GAAG,CAAC,CAAC;gBACb,KAAK,GAAG,QAAQ,CAAC;gBACjB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,IAAI,CAAC,CAAC;gBACd,IAAI,QAAQ,IAAI,gBAAgB,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;oBAC1D,KAAK,GAAG,MAAM,CAAC;oBACf,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACxB,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,WAAW;YACT,MAAM,cAAc,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;YACxD,OAAO;gBACL,KAAK,EAAE,cAAc;gBACrB,QAAQ;gBACR,gBAAgB;gBAChB,cAAc;gBACd,QAAQ,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;gBACxC,WAAW,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI;aACjE,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/cognitive.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryScope } from '../contracts/identity.js';
+import type { AsyncStorageAdapter } from '../contracts/async-storage.js';
+import type { CognitiveSearchOptions, CognitiveSearchResult } from '../contracts/cognitive.js';
+export declare function searchCognitive(adapter: AsyncStorageAdapter, scope: MemoryScope, options: CognitiveSearchOptions): Promise<CognitiveSearchResult>;
+//# sourceMappingURL=cognitive.d.ts.map

package/dist/core/cognitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive.d.ts","sourceRoot":"","sources":["../../src/core/cognitive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAIV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,2BAA2B,CAAC;AAkEnC,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAyEhC"}

package/dist/core/cognitive.js

@@ -0,0 +1,120 @@
+import { mapKnowledgeClassToCognitive, mapCognitiveToKnowledgeClasses, } from '../contracts/cognitive.js';
+function knowledgeToCognitiveItem(km) {
+    return {
+        id: km.id,
+        type: mapKnowledgeClassToCognitive(km.knowledge_class),
+        fact: km.fact,
+        createdAt: km.created_at,
+        lastAccessedAt: km.last_accessed_at,
+        metadata: {
+            trustScore: km.trust_score,
+            knowledgeClass: km.knowledge_class,
+            knowledgeState: km.knowledge_state,
+        },
+    };
+}
+function workingMemoryToCognitiveItem(wm) {
+    return {
+        id: wm.id,
+        type: 'working',
+        fact: wm.summary,
+        createdAt: wm.created_at,
+        lastAccessedAt: wm.created_at,
+        metadata: {
+            trustScore: 1,
+            knowledgeClass: 'project_fact',
+        },
+    };
+}
+function groupByType(results) {
+    const grouped = {
+        episodic: [],
+        semantic: [],
+        procedural: [],
+        working: [],
+    };
+    for (const r of results) {
+        grouped[r.item.type].push(r);
+    }
+    return grouped;
+}
+function computeWorkingMemoryRank(wm, query) {
+    const queryLower = query.toLowerCase();
+    let score = 0;
+    const summaryLower = wm.summary.toLowerCase();
+    if (summaryLower.includes(queryLower))
+        score += 1.0;
+    const tagMatches = wm.topic_tags.filter((t) => t.toLowerCase().includes(queryLower)).length;
+    score += tagMatches * 0.3;
+    const entityMatches = wm.key_entities.filter((e) => e.toLowerCase().includes(queryLower)).length;
+    score += entityMatches * 0.3;
+    return score;
+}
+export async function searchCognitive(adapter, scope, options) {
+    const limit = options.limit ?? 20;
+    const activeOnly = options.activeOnly ?? true;
+    const requestedTypes = options.types ?? ['episodic', 'semantic', 'procedural', 'working'];
+    const all = [];
+    // Semantic and procedural: search knowledge memory
+    const knowledgeTypes = requestedTypes.filter((t) => t === 'semantic' || t === 'procedural');
+    if (knowledgeTypes.length > 0) {
+        const knowledgeClasses = knowledgeTypes.flatMap(mapCognitiveToKnowledgeClasses);
+        const searchOpts = {
+            limit,
+            activeOnly,
+            minimumTrustScore: options.minimumTrustScore,
+            knowledgeClasses: knowledgeClasses.length > 0 ? knowledgeClasses : undefined,
+        };
+        const hits = await adapter.searchKnowledge(scope, options.query, searchOpts);
+        for (const hit of hits) {
+            all.push({
+                item: knowledgeToCognitiveItem(hit.item),
+                rank: hit.rank ?? 0,
+            });
+        }
+    }
+    // Working: search working memory with computed relevance scores
+    if (requestedTypes.includes('working')) {
+        const wmList = activeOnly
+            ? await adapter.getActiveWorkingMemory(scope)
+            : await adapter.getWorkingMemoryByTimeRange(scope, { start_at: 0, end_at: Math.floor(Date.now() / 1000) });
+        for (const wm of wmList) {
+            const score = computeWorkingMemoryRank(wm, options.query);
+            if (score > 0) {
+                all.push({
+                    item: workingMemoryToCognitiveItem(wm),
+                    rank: score,
+                });
+            }
+        }
+    }
+    // Episodic: search turns and map to cognitive items
+    if (requestedTypes.includes('episodic')) {
+        const turnHits = await adapter.searchTurns(scope, options.query, { limit, activeOnly });
+        for (const hit of turnHits) {
+            const turn = hit.item;
+            all.push({
+                item: {
+                    id: turn.id,
+                    type: 'episodic',
+                    fact: turn.content,
+                    createdAt: turn.created_at,
+                    lastAccessedAt: turn.created_at,
+                    metadata: {
+                        trustScore: 1,
+                        knowledgeClass: 'episodic_fact',
+                    },
+                },
+                rank: hit.rank ?? 0,
+            });
+        }
+    }
+    // Sort descending by rank (higher = more relevant), then trim to limit
+    all.sort((a, b) => b.rank - a.rank);
+    const trimmed = all.slice(0, limit);
+    return {
+        byType: groupByType(trimmed),
+        all: trimmed,
+    };
+}
+//# sourceMappingURL=cognitive.js.map

package/dist/core/cognitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive.js","sourceRoot":"","sources":["../../src/core/cognitive.ts"],"names":[],"mappings":"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"}

package/dist/core/context.d.ts

@@ -1,8 +1,10 @@
 import type { EmbeddingAdapter, EmbeddingVector } from '../contracts/embedding.js';
 import { type MemoryScope, type ScopeLevel } from '../contracts/identity.js';
+import type { ActorRef, ContextViewPolicy, CoordinationState, HandoffRecord, WorkClaim } from '../contracts/coordination.js';
 import type { EventHook, Logger } from '../contracts/observability.js';
 import type { ContextMode, ContextPolicy } from '../contracts/policy.js';
-import type { KnowledgeMemory, Turn, WorkItem, WorkingMemory } from '../contracts/types.js';
+import type { SessionState } from '../contracts/session-state.js';
+import type { KnowledgeMemory, Playbook, Turn, WorkItem, WorkingMemory } from '../contracts/types.js';
 import type { AsyncStorageAdapter } from '../contracts/async-storage.js';
 import { type TokenEstimator } from './tokens.js';
 export interface ContextAssemblyOptions {
@@ -11,6 +13,8 @@ export interface ContextAssemblyOptions {
     mode?: ContextMode;
     maxKnowledgeItems?: number;
     maxRecentSummaries?: number;
+    maxAssociationSeedItems?: number;
+    maxAssociatedKnowledgeItems?: number;
     relevanceQuery?: string;
     tokenBudget?: number;
     queryVector?: EmbeddingVector;
@@ -20,6 +24,10 @@ export interface ContextAssemblyOptions {
     onEvent?: EventHook;
     tokenEstimator?: TokenEstimator;
     asOf?: number;
+    associationMinConfidence?: number;
+    view?: ContextViewPolicy;
+    viewer?: ActorRef;
+    includeCoordinationState?: boolean;
 }
 export interface KnowledgeSelectionReason {
     knowledgeMemoryId: number;
@@ -34,6 +42,41 @@ export interface KnowledgeSelectionReason {
     finalScore: number;
     explanation: string;
 }
+export interface ExcludedKnowledgeReason {
+    knowledgeMemoryId: number;
+    reason: 'not_selected' | 'token_budget';
+    detail: string;
+}
+export interface AssociationExpansionTrace {
+    seedKnowledgeIds: number[];
+    candidateKnowledgeIds: number[];
+    includedKnowledgeIds: number[];
+    truncatedKnowledgeIds: number[];
+    maxSeedKnowledgeItems: number;
+    maxAssociatedKnowledgeItems: number;
+}
+export interface TokenTrimTrace {
+    initialTokenEstimate: number;
+    finalTokenEstimate: number;
+    droppedTurnIds: number[];
+    droppedSummaryIds: number[];
+    droppedPlaybookIds: number[];
+    droppedAssociatedKnowledgeIds: number[];
+    droppedKnowledgeIds: number[];
+}
+export interface ContextScopeTrace {
+    normalizedScope: MemoryScope;
+    scopeSource: 'local' | 'cross_scope';
+    scopeLevel: ScopeLevel;
+    asOf: number | null;
+}
+export interface ContextDebugTrace {
+    scope: ContextScopeTrace;
+    selectedKnowledge: KnowledgeSelectionReason[];
+    excludedKnowledge: ExcludedKnowledgeReason[];
+    associationExpansion: AssociationExpansionTrace;
+    tokenTrimming: TokenTrimTrace;
+}
 export interface MemoryContext {
     mode: ContextMode;
     activeTurns: Turn[];
@@ -46,11 +89,39 @@ export interface MemoryContext {
     durableKnowledge: KnowledgeMemory[];
     recentSummaries: WorkingMemory[];
     currentObjective: string | null;
+    sessionState: SessionState;
     activeObjectives: WorkItem[];
     activeState: string[];
     unresolvedWork: string[];
+    coordinationState: CoordinationState | null;
+    relevantPlaybooks?: Playbook[];
+    associatedKnowledge: KnowledgeMemory[];
     knowledgeSelectionReasons: KnowledgeSelectionReason[];
+    debugTrace: ContextDebugTrace;
     tokenEstimate: number;
 }
+export declare function resolveVisibleKnowledge(items: KnowledgeMemory[], scope: MemoryScope, view: ContextViewPolicy): KnowledgeMemory[];
+export declare function resolveVisibleWorkItems(items: WorkItem[], scope: MemoryScope, view: ContextViewPolicy): WorkItem[];
+export declare function resolveVisiblePlaybooks(items: Playbook[], scope: MemoryScope, view: ContextViewPolicy): Playbook[];
+export declare function resolveVisibleWorkClaims(items: WorkClaim[], scope: MemoryScope, view: ContextViewPolicy): WorkClaim[];
+export declare function resolveVisibleHandoffs(items: HandoffRecord[], scope: MemoryScope, view: ContextViewPolicy): HandoffRecord[];
+export interface DerivedShortTermState {
+    workingMemory: WorkingMemory | null;
+    recentSummaries: WorkingMemory[];
+    activeObjectives: WorkItem[];
+    currentObjective: string | null;
+    activeState: string[];
+    unresolvedWork: string[];
+    sessionState: SessionState;
+}
+export declare function buildDerivedShortTermState(input: {
+    activeTurns: Turn[];
+    workingMemoryCandidates: WorkingMemory[];
+    contextWorkItems: WorkItem[];
+    relevantKnowledge?: KnowledgeMemory[];
+    maxRecentSummaries?: number;
+}): DerivedShortTermState;
+export declare function getContextWorkItems(adapter: AsyncStorageAdapter, scope: MemoryScope, asOf?: number, level?: ScopeLevel): Promise<WorkItem[]>;
+export declare function resolveContextScopeLevel(crossScopeLevel: ScopeLevel | undefined, view: ContextViewPolicy | undefined): ScopeLevel | undefined;
 export declare function buildMemoryContext(adapter: AsyncStorageAdapter, scope: MemoryScope, options?: ContextAssemblyOptions): Promise<MemoryContext>;
 //# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEzE,OAAO,KAAK,EACV,eAAe,EAEf,IAAI,EACJ,QAAQ,EACR,aAAa,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,cAAc,GAAG,eAAe,GAAG,aAAa,GAAG,UAAU,CAAC;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,qBAAqB,EAAE,eAAe,EAAE,CAAC;IACzC,oBAAoB,EAAE,eAAe,EAAE,CAAC;IACxC,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,yBAAyB,EAAE,wBAAwB,EAAE,CAAC;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAkRD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAuQxB"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"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"}