cogmem 3.6.2

package/dist/retrieval/PolicySideEffectExecutor.js

@@ -0,0 +1,202 @@
+import { createHash, randomUUID } from 'crypto';
+export class NoopPolicySideEffectExecutor {
+    execute(effect) {
+        return {
+            policy: effect.policy,
+            action: effect.action,
+            target: effect.target,
+            status: 'executed',
+            detail: 'noop'
+        };
+    }
+}
+export class ReliablePolicySideEffectExecutor {
+    delegate;
+    store;
+    maxRetries;
+    backoffMs;
+    strategy;
+    jitterRatio;
+    maxBackoffMs;
+    constructor(delegate, store, maxRetries = 2, backoffMs = 1000, options) {
+        this.delegate = delegate;
+        this.store = store;
+        this.maxRetries = maxRetries;
+        this.backoffMs = backoffMs;
+        this.strategy = options?.strategy || 'linear';
+        this.jitterRatio = Math.max(0, Math.min(options?.jitterRatio ?? 0, 1));
+        this.maxBackoffMs = Math.max(backoffMs, options?.maxBackoffMs ?? backoffMs * 16);
+    }
+    async execute(effect) {
+        const now = Date.now();
+        const idempotencyKey = effect.idempotencyKey || this.computeIdempotencyKey(effect);
+        const existing = this.store.getByIdempotencyKey(idempotencyKey);
+        if (existing?.status === 'executed') {
+            return {
+                policy: existing.policy,
+                action: existing.action,
+                target: existing.target,
+                status: 'skipped',
+                detail: 'idempotent_replay'
+            };
+        }
+        let record = existing || this.buildRecord(effect, idempotencyKey, now, 0);
+        let lastError;
+        const attemptBase = existing?.attemptCount || 0;
+        for (let localAttempt = 1; localAttempt <= this.maxRetries + 1; localAttempt++) {
+            const totalAttempt = attemptBase + localAttempt;
+            try {
+                const result = await this.delegate.execute({ ...effect, idempotencyKey });
+                record = {
+                    ...record,
+                    runtimeId: effect.runtimeId,
+                    policy: effect.policy,
+                    action: effect.action,
+                    target: effect.target,
+                    actorId: effect.actorId,
+                    causationId: effect.causationId,
+                    correlationId: effect.correlationId,
+                    policyGroup: effect.policyGroup,
+                    streamType: 'system',
+                    eventType: 'POLICY_EXECUTION_UPDATED',
+                    status: result.status === 'failed' ? 'failed' : 'executed',
+                    attemptCount: totalAttempt,
+                    nextRetryAt: undefined,
+                    deadLetteredAt: undefined,
+                    replayPolicy: effect.replayPolicy || record.replayPolicy || 'manual',
+                    detail: result.detail,
+                    metadata: effect.metadata,
+                    updatedAt: Date.now()
+                };
+                this.store.upsert(record);
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                const replayPolicy = effect.replayPolicy || record.replayPolicy || 'manual';
+                const isLastAttempt = localAttempt >= this.maxRetries + 1;
+                const shouldRetryLater = !isLastAttempt || replayPolicy !== 'manual';
+                const deadLetter = isLastAttempt && (replayPolicy === 'manual');
+                record = {
+                    ...record,
+                    runtimeId: effect.runtimeId,
+                    policy: effect.policy,
+                    action: effect.action,
+                    target: effect.target,
+                    actorId: effect.actorId,
+                    causationId: effect.causationId,
+                    correlationId: effect.correlationId,
+                    policyGroup: effect.policyGroup,
+                    streamType: 'system',
+                    eventType: 'POLICY_EXECUTION_UPDATED',
+                    status: 'failed',
+                    attemptCount: totalAttempt,
+                    nextRetryAt: shouldRetryLater ? Date.now() + this.computeBackoff(totalAttempt, idempotencyKey) : undefined,
+                    deadLetteredAt: deadLetter ? Date.now() : undefined,
+                    replayPolicy,
+                    detail: error instanceof Error ? error.message : String(error),
+                    metadata: effect.metadata,
+                    updatedAt: Date.now()
+                };
+                this.store.upsert(record);
+            }
+        }
+        return {
+            policy: effect.policy,
+            action: effect.action,
+            target: effect.target,
+            status: 'failed',
+            detail: lastError instanceof Error ? lastError.message : String(lastError)
+        };
+    }
+    replay(runtimeId) {
+        return this.store.listByRuntime(runtimeId).map((record) => ({
+            policy: record.policy,
+            action: record.action,
+            target: record.target,
+            status: record.status === 'executed' ? 'executed' : record.status === 'failed' ? 'failed' : 'skipped',
+            detail: record.detail
+        }));
+    }
+    async replayPending(now = Date.now()) {
+        const pending = this.store.listPendingRetries(now)
+            .filter((record) => record.replayPolicy !== 'manual');
+        const results = [];
+        for (const record of pending) {
+            if (record.replayPolicy === 'on_bootstrap' && now > (record.nextRetryAt || 0) + 365 * 24 * 60 * 60 * 1000) {
+                continue;
+            }
+            results.push(await this.execute({
+                runtimeId: record.runtimeId,
+                policy: record.policy,
+                action: record.action,
+                target: record.target,
+                metadata: record.metadata,
+                idempotencyKey: record.idempotencyKey,
+                replayPolicy: record.replayPolicy,
+                actorId: record.actorId,
+                causationId: record.causationId,
+                correlationId: record.correlationId,
+                policyGroup: record.policyGroup
+            }));
+        }
+        return results;
+    }
+    getDeadLetters(runtimeId) {
+        return this.store.listDeadLetters(runtimeId).map((record) => ({
+            policy: record.policy,
+            action: record.action,
+            target: record.target,
+            status: 'failed',
+            detail: record.detail
+        }));
+    }
+    buildRecord(effect, idempotencyKey, now, attemptCount) {
+        return {
+            executionId: `pex-${randomUUID()}`,
+            idempotencyKey,
+            runtimeId: effect.runtimeId,
+            policy: effect.policy,
+            action: effect.action,
+            target: effect.target,
+            status: 'failed',
+            attemptCount,
+            replayPolicy: effect.replayPolicy || 'manual',
+            actorId: effect.actorId,
+            causationId: effect.causationId,
+            correlationId: effect.correlationId,
+            policyGroup: effect.policyGroup,
+            streamType: 'system',
+            eventType: 'POLICY_EXECUTION_UPDATED',
+            metadata: effect.metadata,
+            createdAt: now,
+            updatedAt: now
+        };
+    }
+    computeIdempotencyKey(effect) {
+        const raw = JSON.stringify({
+            runtimeId: effect.runtimeId,
+            policy: effect.policy,
+            action: effect.action,
+            target: effect.target,
+            metadata: effect.metadata || {},
+            actorId: effect.actorId,
+            causationId: effect.causationId,
+            correlationId: effect.correlationId,
+            policyGroup: effect.policyGroup
+        });
+        return createHash('sha256').update(raw).digest('hex');
+    }
+    computeBackoff(attempt, idempotencyKey) {
+        const base = this.strategy === 'exponential'
+            ? this.backoffMs * Math.pow(2, Math.max(0, attempt - 1))
+            : this.backoffMs * Math.max(1, attempt);
+        const bounded = Math.min(base, this.maxBackoffMs);
+        if (this.jitterRatio === 0)
+            return bounded;
+        const hash = createHash('sha256').update(`${idempotencyKey}:${attempt}`).digest();
+        const normalized = hash[0] / 255;
+        const jitter = (normalized * 2 - 1) * this.jitterRatio * bounded;
+        return Math.max(0, Math.round(bounded + jitter));
+    }
+}

package/dist/retrieval/PulseRetrievalEngine.d.ts

@@ -0,0 +1,37 @@
+import type { RetrievalExecutionPlan } from './RetrievalPlanner.js';
+import type { QueryIR } from '../types/query-ir.js';
+import type { TemporalAdjacencyStore } from '../store/TemporalAdjacencyStore.js';
+import type { EntityActivationIndex } from './EntityActivationIndex.js';
+import { EvidenceFusionRanker } from './EvidenceFusionRanker.js';
+export interface PulseRetrievalResult {
+    pulse0Ids: string[];
+    pulse1Ids: string[];
+    pulse2Ids: string[];
+    fusedIds: string[];
+    reasonsByNeuronId: Map<string, string[]>;
+    trace: Array<{
+        pulse: 0 | 1 | 2 | 3;
+        stage: string;
+        candidateCount: number;
+        reason: string;
+    }>;
+}
+export declare class PulseRetrievalEngine {
+    private temporalAdjacencyStore;
+    private entityActivationIndex;
+    private fusionRanker;
+    constructor(temporalAdjacencyStore: TemporalAdjacencyStore, entityActivationIndex: EntityActivationIndex, fusionRanker?: EvidenceFusionRanker);
+    run(input: {
+        plan: RetrievalExecutionPlan;
+        ir: QueryIR;
+        entityIds: string[];
+        topologyIds: string[];
+        branchIds: string[];
+        temporalBucketIds: string[];
+        temporalNeuronIds: string[];
+        graphIds: string[];
+        cognitiveGraphIds: string[];
+        entityNeuronIds: string[];
+    }): PulseRetrievalResult;
+}
+//# sourceMappingURL=PulseRetrievalEngine.d.ts.map

package/dist/retrieval/PulseRetrievalEngine.js

@@ -0,0 +1,51 @@
+import { EvidenceFusionRanker } from './EvidenceFusionRanker.js';
+export class PulseRetrievalEngine {
+    temporalAdjacencyStore;
+    entityActivationIndex;
+    fusionRanker;
+    constructor(temporalAdjacencyStore, entityActivationIndex, fusionRanker) {
+        this.temporalAdjacencyStore = temporalAdjacencyStore;
+        this.entityActivationIndex = entityActivationIndex;
+        this.fusionRanker = fusionRanker || new EvidenceFusionRanker();
+    }
+    run(input) {
+        const pulse0Ids = Array.from(new Set([
+            ...input.entityNeuronIds,
+            ...input.topologyIds,
+            ...input.branchIds,
+            ...input.temporalNeuronIds
+        ])).slice(0, 120);
+        const activation = this.entityActivationIndex.activate(input.entityIds, input.ir.semantics.predicateHint === 'fact' ? ['has_issue', 'owns', 'worked_on'] : undefined);
+        const pulse1Ids = Array.from(new Set([
+            ...activation.neuronIds,
+            ...input.entityNeuronIds,
+            ...input.graphIds.slice(0, input.plan.topK.graph),
+            ...input.cognitiveGraphIds.slice(0, input.plan.topK.graph)
+        ])).slice(0, 120);
+        const temporalAdjacentIds = this.temporalAdjacencyStore.collectAdjacentNeuronIds(input.temporalBucketIds, 48);
+        const pulse2Ids = Array.from(new Set([
+            ...temporalAdjacentIds,
+            ...input.branchIds,
+            ...input.graphIds,
+            ...input.cognitiveGraphIds
+        ])).slice(0, 120);
+        const scored = [];
+        pulse0Ids.forEach((id, index) => scored.push({ neuronId: id, score: 3.2 - index * 0.02, source: 'pulse0', reason: 'hard constraint narrowing' }));
+        pulse1Ids.forEach((id, index) => scored.push({ neuronId: id, score: 2.3 - index * 0.015, source: 'pulse1', reason: 'direct entity/fact activation' }));
+        pulse2Ids.forEach((id, index) => scored.push({ neuronId: id, score: 1.4 - index * 0.01, source: 'pulse2', reason: 'local temporal/graph expansion' }));
+        const fused = this.fusionRanker.rank(scored, 120);
+        return {
+            pulse0Ids,
+            pulse1Ids,
+            pulse2Ids,
+            fusedIds: fused.neuronIds,
+            reasonsByNeuronId: fused.reasonsByNeuronId,
+            trace: [
+                { pulse: 0, stage: 'hard_constraints', candidateCount: pulse0Ids.length, reason: 'time/entity/project constraints shrink the local universe' },
+                { pulse: 1, stage: 'direct_activation', candidateCount: pulse1Ids.length, reason: 'entity -> fact -> neuron direct activation' },
+                { pulse: 2, stage: 'local_expansion', candidateCount: pulse2Ids.length, reason: 'temporal adjacency and local graph expansion' },
+                { pulse: 3, stage: 'evidence_fusion', candidateCount: fused.neuronIds.length, reason: 'evidence fusion ranker combined pulse outputs' }
+            ]
+        };
+    }
+}

package/dist/retrieval/QueryCompiler.d.ts

@@ -0,0 +1,18 @@
+import type { QueryIR } from '../types/query-ir.js';
+import type { LocalSemanticCompiler, SemanticCompilation } from '../engine/LocalSemanticCompiler.js';
+import type { EntityResolutionEngine, EntityResolutionResult } from '../engine/EntityResolutionEngine.js';
+export interface CompiledQuery {
+    ir: QueryIR;
+    semanticCompilation: SemanticCompilation;
+    entityResolution: EntityResolutionResult;
+}
+export declare class QueryCompiler {
+    private semanticCompiler;
+    private entityResolutionEngine;
+    private nativeQueryParser;
+    constructor(semanticCompiler: LocalSemanticCompiler, entityResolutionEngine: EntityResolutionEngine);
+    compile(query: string, projectId?: string): CompiledQuery;
+    private mapNativeTime;
+    private parseNativeDate;
+}
+//# sourceMappingURL=QueryCompiler.d.ts.map

package/dist/retrieval/QueryCompiler.js

@@ -0,0 +1,97 @@
+import { IntentParser } from '../core/IntentParser.js';
+import { NativeQueryParser } from './NativeQueryParser.js';
+export class QueryCompiler {
+    semanticCompiler;
+    entityResolutionEngine;
+    nativeQueryParser = new NativeQueryParser();
+    constructor(semanticCompiler, entityResolutionEngine) {
+        this.semanticCompiler = semanticCompiler;
+        this.entityResolutionEngine = entityResolutionEngine;
+    }
+    compile(query, projectId) {
+        const nativeQuery = this.nativeQueryParser.parse(query);
+        const effectiveQuery = nativeQuery.residualQuery || query;
+        const baseIr = IntentParser.parse(effectiveQuery);
+        const semanticCompilation = this.semanticCompiler.compileQuery({ text: effectiveQuery, projectId });
+        const nativeDirectives = nativeQuery.directives;
+        const ir = {
+            ...baseIr,
+            semantics: this.semanticCompiler.mergeIntoSemantics(baseIr.semantics, semanticCompilation),
+            nativeDirectives,
+            nativeQueryDebug: {
+                parseMode: nativeQuery.parseMode,
+                residualQuery: nativeQuery.residualQuery,
+                clauses: nativeQuery.clauses.map((clause) => ({ key: clause.key, value: clause.value }))
+            }
+        };
+        if (!ir.spatial.projectId && nativeDirectives?.project) {
+            ir.spatial.projectId = nativeDirectives.project;
+        }
+        if (nativeDirectives?.entity) {
+            ir.entities = Array.from(new Set([nativeDirectives.entity, ...ir.entities]));
+            ir.semantics.entityHints = Array.from(new Set([nativeDirectives.entity, ...ir.semantics.entityHints]));
+        }
+        if (nativeDirectives?.entityType) {
+            ir.semantics.valueHints = Array.from(new Set([nativeDirectives.entityType, ...ir.semantics.valueHints]));
+        }
+        if (nativeDirectives?.branch) {
+            ir.shouldMatch = Array.from(new Set([nativeDirectives.branch, ...ir.shouldMatch]));
+            ir.semantics.valueHints = Array.from(new Set([nativeDirectives.branch, ...ir.semantics.valueHints]));
+        }
+        if (nativeDirectives?.task) {
+            ir.shouldMatch = Array.from(new Set([nativeDirectives.task, ...ir.shouldMatch]));
+            ir.semantics.valueHints = Array.from(new Set([nativeDirectives.task, ...ir.semantics.valueHints]));
+        }
+        if (nativeDirectives?.cluster) {
+            ir.shouldMatch = Array.from(new Set([nativeDirectives.cluster, ...ir.shouldMatch]));
+            ir.semantics.valueHints = Array.from(new Set([nativeDirectives.cluster, ...ir.semantics.valueHints]));
+        }
+        if (!ir.temporal.relative && semanticCompilation.temporalHints.length > 0) {
+            ir.temporal.relative = semanticCompilation.temporalHints[0];
+        }
+        if (!ir.temporal.relative && nativeDirectives?.time) {
+            ir.temporal.relative = this.mapNativeTime(nativeDirectives.time);
+        }
+        if (!ir.temporal.start && nativeDirectives?.from) {
+            const start = this.parseNativeDate(nativeDirectives.from);
+            if (start !== undefined)
+                ir.temporal.start = start;
+        }
+        if (!ir.temporal.end && nativeDirectives?.to) {
+            const end = this.parseNativeDate(nativeDirectives.to, true);
+            if (end !== undefined)
+                ir.temporal.end = end;
+        }
+        if (!ir.temporal.relative && !ir.temporal.start && !ir.temporal.end && nativeDirectives?.around) {
+            const center = this.parseNativeDate(nativeDirectives.around);
+            if (center !== undefined) {
+                ir.temporal.start = center - 7 * 86400000;
+                ir.temporal.end = center + 7 * 86400000;
+            }
+        }
+        const entityResolution = this.entityResolutionEngine.resolve({ query: effectiveQuery, ir, projectId });
+        return { ir, semanticCompilation, entityResolution };
+    }
+    mapNativeTime(value) {
+        const lowered = value.toLowerCase();
+        if (/halfyear|half-year|6m|six-months/.test(lowered))
+            return 'around_half_year_ago';
+        if (/year|1y|12m/.test(lowered))
+            return 'past_year';
+        if (/month|1m/.test(lowered))
+            return 'this_month';
+        if (/week|1w/.test(lowered))
+            return 'this_week';
+        if (/today|day|1d/.test(lowered))
+            return 'today';
+        return undefined;
+    }
+    parseNativeDate(value, endOfDay = false) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+            return undefined;
+        const ts = new Date(value).getTime();
+        if (Number.isNaN(ts))
+            return undefined;
+        return endOfDay ? ts + 86400000 - 1 : ts;
+    }
+}

package/dist/retrieval/QueryTimePendingEntityResolver.d.ts

@@ -0,0 +1,67 @@
+import type { SemanticCompilation } from '../engine/LocalSemanticCompiler.js';
+import type { EntityResolutionResult } from '../engine/EntityResolutionEngine.js';
+import type { EntityStore } from '../store/EntityStore.js';
+import type { QueryIR } from '../types/query-ir.js';
+import type { Neuron } from '../types/index.js';
+export type QueryTimePendingResolutionStatus = 'not_applicable' | 'not_needed' | 'narrowed_but_still_ambiguous' | 'resolved_narrowly' | 'unresolved_explicit';
+export type QueryTimePendingResolutionReason = 'no_relative_pending_reference_in_query' | 'no_matching_pending_reference' | 'write_time_resolution_already_sufficient' | 'pending_capture_missing_or_too_weak' | 'pending_relative_reference_narrowed' | 'pending_relative_reference_ambiguous_after_narrowing' | 'pending_reference_still_unresolved';
+export interface QueryTimePendingResolutionCandidate {
+    entityId: string;
+    score: number;
+    reasons: string[];
+}
+export interface QueryTimePendingEntityResolutionResult {
+    reference: string;
+    queryTimeResolutionStatus: QueryTimePendingResolutionStatus;
+    queryTimeResolutionReason: QueryTimePendingResolutionReason;
+    resolutionConfidence: number;
+    candidateEntityIds: string[];
+    narrowedCandidates: QueryTimePendingResolutionCandidate[];
+    matchedPendingIds: string[];
+    contextNeuronIds: string[];
+    resolvedInstanceId?: string;
+}
+export interface QueryTimePendingEntityResolverInput {
+    query: string;
+    ir: QueryIR;
+    semanticCompilation: SemanticCompilation;
+    baseEntityResolution: EntityResolutionResult;
+    projectId?: string;
+}
+export interface QueryTimePendingEntityResolverOutput {
+    overallStatus: QueryTimePendingResolutionStatus;
+    overallReason: QueryTimePendingResolutionReason;
+    resolvedEntityIds: string[];
+    candidateEntityIds: string[];
+    candidateNeuronIds: string[];
+    results: QueryTimePendingEntityResolutionResult[];
+    pendingCaptureMetrics: WriteTimePendingCaptureMetrics;
+}
+export interface WriteTimePendingCaptureMetrics {
+    pending_record_emitted_count: number;
+    pending_record_expected_but_missing_count: number;
+    pending_candidate_set_nonempty_count: number;
+    pending_candidate_set_empty_count: number;
+    referential_signal_preserved_count: number;
+    referential_signal_lost_count: number;
+    query_time_not_needed_due_to_write_time_sufficient_count: number;
+    query_time_not_needed_due_to_missing_pending_capture_count: number;
+}
+export declare class QueryTimePendingEntityResolver {
+    private entityStore;
+    private getNeuronById;
+    private resolveBeforeTime;
+    constructor(entityStore: EntityStore, getNeuronById: (neuronId: string) => Neuron | null, resolveBeforeTime: (ir: QueryIR) => number | undefined);
+    resolve(input: QueryTimePendingEntityResolverInput): QueryTimePendingEntityResolverOutput;
+    private collectRelativeReferences;
+    private findMatchingPendingRecords;
+    private canResolveNarrowly;
+    private inferOverallStatus;
+    private inferOverallReason;
+    private inferNoPendingReason;
+    private hasWriteTimeSufficientEntityResolution;
+    private computePendingCaptureMetrics;
+    private inferPendingScopedProjectId;
+    private findSameTypePendingFallback;
+}
+//# sourceMappingURL=QueryTimePendingEntityResolver.d.ts.map