cogmem 3.7.1 → 3.7.3

package/dist/episode/EpisodeBoundaryReplayEngine.js

@@ -0,0 +1,272 @@
+import { EpisodeBoundaryPolicy, resolveTrustedLocalDate } from './EpisodeBoundaryPolicy.js';
+export function replayEpisodeBoundaries(input) {
+    const policy = new EpisodeBoundaryPolicy(input.config);
+    const state = input.initialState ? {
+        ...input.initialState,
+        trustedLocalDates: [...input.initialState.trustedLocalDates],
+    } : {
+        eventCount: 0,
+        startedAt: input.episode.startedAt,
+        trustedLocalDates: [],
+    };
+    const logicalTurns = logicalTurnsFromPairs(input.pairs);
+    const detectedBoundaries = [];
+    const warnings = new Set();
+    const anomalies = new Set();
+    let pendingClosureAfter;
+    const pushBoundary = (boundary) => {
+        const item = { ...boundary, boundaryIndex: detectedBoundaries.length, detected: true };
+        detectedBoundaries.push(item);
+        for (const warning of item.warnings)
+            warnings.add(warning);
+    };
+    for (const turn of logicalTurns) {
+        const user = primaryUser(turn);
+        const imported = input.imported ?? isImportedTurn(turn);
+        let startedAfterClosure = false;
+        let effectiveBoundaryBeforeTurn = false;
+        if (pendingClosureAfter) {
+            pushBoundary({
+                beforeEventId: lastPair(pendingClosureAfter)?.link.eventId,
+                afterEventId: firstPair(turn)?.link.eventId,
+                primaryUserEventId: user?.event?.eventId,
+                relation: user?.link.relation,
+                reason: 'explicit_closure_boundary',
+                guardCodes: [],
+                warnings: [],
+                effective: true,
+                disposition: 'explicit',
+            });
+            pendingClosureAfter = undefined;
+            startedAfterClosure = true;
+            effectiveBoundaryBeforeTurn = true;
+        }
+        if (!user?.event) {
+            if (turn.some((pair) => !pair.event))
+                anomalies.add('raw_event_missing');
+            acceptTurn(state, turn, input.config.timezone, warnings);
+            continue;
+        }
+        const relation = user.link.relation;
+        if (startedAfterClosure) {
+            // The closure-after boundary already started this segment.
+        }
+        else if (state.eventCount > 0 && isHardSwitch(relation)) {
+            pushBoundary({
+                beforeEventId: previousAcceptedEventId(input.pairs, turn),
+                afterEventId: firstPair(turn)?.link.eventId,
+                primaryUserEventId: user.event.eventId,
+                relation,
+                reason: 'hard_topic_switch_boundary',
+                guardCodes: [],
+                warnings: [],
+                effective: true,
+                disposition: 'explicit',
+            });
+            effectiveBoundaryBeforeTurn = true;
+        }
+        else if (state.eventCount > 0 && relation === 'ambiguous_shift') {
+            pushBoundary({
+                beforeEventId: previousAcceptedEventId(input.pairs, turn),
+                afterEventId: firstPair(turn)?.link.eventId,
+                primaryUserEventId: user.event.eventId,
+                relation,
+                reason: 'ambiguous_shift_boundary',
+                guardCodes: [],
+                warnings: [],
+                effective: true,
+                disposition: 'soft_review',
+            });
+            effectiveBoundaryBeforeTurn = true;
+        }
+        else if (relation !== 'closes_episode') {
+            const result = policy.evaluate({
+                active: {
+                    eventCount: state.eventCount,
+                    startedAt: state.startedAt,
+                    updatedAt: state.lastEventAt,
+                    localDates: state.trustedLocalDates,
+                    lastTrustedLocalDate: state.lastTrustedUserLocalDate,
+                },
+                primaryEvent: user.event,
+                imported,
+            });
+            for (const warning of result.warnings)
+                warnings.add(warning.code);
+            if (result.guardCodes.length) {
+                const effective = result.guardAction === 'enforce_new_episode';
+                pushBoundary({
+                    beforeEventId: previousAcceptedEventId(input.pairs, turn),
+                    afterEventId: firstPair(turn)?.link.eventId,
+                    primaryUserEventId: user.event.eventId,
+                    relation,
+                    reason: guardReason(result.guardCodes),
+                    guardCodes: result.guardCodes,
+                    warnings: result.warnings.map((warning) => warning.code),
+                    effective,
+                    disposition: effective ? 'enforced' : 'shadow',
+                    guardResult: result,
+                });
+                effectiveBoundaryBeforeTurn = effective;
+            }
+        }
+        if (effectiveBoundaryBeforeTurn)
+            resetSegmentState(state, turn);
+        acceptTurn(state, turn, input.config.timezone, warnings);
+        if (relation === 'closes_episode')
+            pendingClosureAfter = turn;
+    }
+    return {
+        logicalTurns,
+        detectedBoundaries,
+        effectiveBoundaries: detectedBoundaries.filter((boundary) => boundary.effective),
+        warnings: [...warnings].sort(),
+        structuralAnomalies: [...anomalies].sort(),
+        runningState: state,
+        policyDisposition: !input.config.enabled || input.config.mode === 'off' ? 'disabled' : input.config.mode,
+    };
+}
+/** Reduces accepted evidence without evaluating a new boundary. */
+export function replayEpisodeBoundaryState(input) {
+    const state = {
+        eventCount: 0,
+        startedAt: input.episode.startedAt,
+        trustedLocalDates: [],
+    };
+    const warnings = new Set();
+    for (const turn of logicalTurnsFromPairs(input.pairs))
+        acceptTurn(state, turn, input.timezone, warnings);
+    return state;
+}
+export function replayPendingTurnBoundary(input) {
+    const active = input.active;
+    const replay = replayEpisodeBoundaries({
+        episode: { startedAt: active?.startedAt },
+        pairs: input.pendingPairs,
+        config: input.config,
+        imported: input.imported,
+        initialState: active,
+    });
+    const guarded = replay.detectedBoundaries.find((boundary) => boundary.guardResult)?.guardResult;
+    if (guarded)
+        return guarded;
+    return new EpisodeBoundaryPolicy(input.config).evaluate({
+        active: active ? {
+            eventCount: active.eventCount,
+            startedAt: active.startedAt,
+            updatedAt: active.lastEventAt,
+            localDates: active.trustedLocalDates,
+            lastTrustedLocalDate: active.lastTrustedUserLocalDate,
+        } : undefined,
+        primaryEvent: input.primaryEvent,
+        imported: input.imported,
+    });
+}
+export function logicalTurnsFromPairs(pairs) {
+    const groups = [];
+    let current = [];
+    let currentTurnKey;
+    let currentHasUser = false;
+    for (const pair of pairs) {
+        const turnKey = pair.event ? turnKeyFor(pair.event) : undefined;
+        const explicitTurnChange = Boolean(currentTurnKey && turnKey && currentTurnKey !== turnKey);
+        const roleBoundary = pair.event?.role === 'user' && currentHasUser && !explicitTurnChange;
+        if (current.length && (explicitTurnChange || roleBoundary)) {
+            groups.push(current);
+            current = [];
+            currentTurnKey = undefined;
+            currentHasUser = false;
+        }
+        current.push(pair);
+        if (turnKey && !currentTurnKey)
+            currentTurnKey = turnKey;
+        if (pair.event?.role === 'user')
+            currentHasUser = true;
+    }
+    if (current.length)
+        groups.push(current);
+    return groups;
+}
+function acceptTurn(state, turn, timezone, warnings) {
+    for (const pair of turn) {
+        const event = pair.event;
+        const occurredAt = event?.occurredAt;
+        const hasOccurredAt = typeof occurredAt === 'number' && Number.isFinite(occurredAt);
+        const outOfOrder = hasOccurredAt && state.lastEventAt !== undefined && occurredAt < state.lastEventAt;
+        if (event?.role === 'user') {
+            const resolved = resolveTrustedLocalDate(event, timezone);
+            if (resolved.date && !outOfOrder) {
+                state.lastTrustedUserLocalDate = resolved.date;
+                if (!state.trustedLocalDates.includes(resolved.date))
+                    state.trustedLocalDates.push(resolved.date);
+            }
+            else if (resolved.warning && resolved.warning.code !== 'trusted_local_date_unavailable') {
+                warnings.add(resolved.warning.code);
+            }
+        }
+        if (hasOccurredAt) {
+            if (outOfOrder) {
+                warnings.add('out_of_order_timestamp');
+            }
+            else {
+                state.lastEventAt = Math.max(state.lastEventAt ?? occurredAt, occurredAt);
+            }
+        }
+        if (state.startedAt === undefined && hasOccurredAt)
+            state.startedAt = occurredAt;
+        state.eventCount += 1;
+    }
+}
+function resetSegmentState(state, turn) {
+    const firstTimestamp = turn
+        .map((pair) => pair.event?.occurredAt)
+        .find((value) => typeof value === 'number' && Number.isFinite(value));
+    state.eventCount = 0;
+    state.startedAt = firstTimestamp;
+    state.lastEventAt = undefined;
+    state.lastTrustedUserLocalDate = undefined;
+    state.trustedLocalDates = [];
+}
+function primaryUser(turn) {
+    return turn.find((pair) => pair.event?.role === 'user');
+}
+function firstPair(turn) {
+    return turn[0];
+}
+function lastPair(turn) {
+    return turn.at(-1);
+}
+function previousAcceptedEventId(allPairs, turn) {
+    const first = firstPair(turn);
+    if (!first)
+        return undefined;
+    const index = allPairs.indexOf(first);
+    return index > 0 ? allPairs[index - 1]?.link.eventId : undefined;
+}
+function turnKeyFor(event) {
+    if (event.turnId)
+        return `id:${event.turnId}`;
+    if (typeof event.turnSeq === 'number')
+        return `seq:${event.turnSeq}`;
+    return undefined;
+}
+function isHardSwitch(relation) {
+    return relation === 'hard_topic_switch' || relation === 'starts_new_topic' || relation === 'switches_topic';
+}
+function isImportedTurn(turn) {
+    return turn.some((pair) => {
+        const payload = pair.event?.payload;
+        return payload?.metadata?.imported === true || payload?.metadata?.sourceRef !== undefined;
+    });
+}
+function guardReason(codes) {
+    if (codes.includes('max_events_exceeded'))
+        return 'max_events_boundary';
+    if (codes.includes('trusted_local_date_changed'))
+        return 'trusted_local_date_boundary';
+    if (codes.includes('max_duration_exceeded'))
+        return 'max_duration_boundary';
+    if (codes.includes('max_idle_gap_exceeded'))
+        return 'max_idle_gap_boundary';
+    return codes[0] ?? 'policy_boundary';
+}

package/dist/episode/EpisodeImportIdentity.d.ts

@@ -2,6 +2,7 @@ export interface StableImportIdentityInput {
     role: string;
     text: string;
     timestamp?: number;
+    sourcePosition?: string | number;
 }
 export declare function createStableImportIdentityFactory(sourceAgent: string, sourceSessionId: string): (input: StableImportIdentityInput) => string;
 //# sourceMappingURL=EpisodeImportIdentity.d.ts.map

package/dist/episode/EpisodeImportIdentity.js

@@ -8,6 +8,7 @@ export function createStableImportIdentityFactory(sourceAgent, sourceSessionId)
             sourceSessionId,
             input.role,
             input.timestamp ?? null,
+            input.sourcePosition ?? null,
             createHash('sha256').update(normalizedText).digest('hex'),
         ])).digest('hex');
         const occurrence = (occurrences.get(base) || 0) + 1;

package/dist/episode/EpisodeInvariantValidator.d.ts

@@ -0,0 +1,16 @@
+import { type EpisodeReplayPair } from './EpisodeBoundaryReplayEngine.js';
+import type { EpisodeClosureReceipt, MemoryEpisode } from './EpisodeTypes.js';
+export interface EpisodeInvariantViolation {
+    reason: string;
+    severity: 'info' | 'warning' | 'critical';
+    recommendedAction: 'none' | 'inspect' | 'split-plan';
+    requiresManualReview: boolean;
+}
+export declare function validateEpisodeInvariants(input: {
+    episode: MemoryEpisode;
+    pairs: EpisodeReplayPair[];
+    timezone?: string;
+    closureReceipts?: EpisodeClosureReceipt[];
+    dreamJobState?: string;
+}): EpisodeInvariantViolation[];
+//# sourceMappingURL=EpisodeInvariantValidator.d.ts.map

package/dist/episode/EpisodeInvariantValidator.js

@@ -0,0 +1,99 @@
+import { resolveTrustedLocalDate } from './EpisodeBoundaryPolicy.js';
+import { logicalTurnsFromPairs } from './EpisodeBoundaryReplayEngine.js';
+export function validateEpisodeInvariants(input) {
+    const violations = [];
+    const add = (reason, severity = 'warning') => {
+        violations.push({
+            reason,
+            severity,
+            recommendedAction: ['closure_receipt_status_mismatch', 'dream_job_status_mismatch'].includes(reason) ? 'inspect' : severity === 'critical' ? 'split-plan' : 'inspect',
+            requiresManualReview: severity !== 'info',
+        });
+    };
+    const { episode, pairs } = input;
+    if (episode.eventCount !== pairs.length)
+        add('stored_actual_event_count_mismatch', 'critical');
+    if (!positionsAreContiguous(pairs))
+        add('duplicate_or_gapped_positions', 'critical');
+    if (pairs.length) {
+        if (episode.startEventId !== pairs[0].link.eventId || episode.endEventId !== pairs.at(-1)?.link.eventId) {
+            add('start_end_pointer_mismatch', 'critical');
+        }
+        const firstEvent = pairs[0].event;
+        const lastEvent = pairs.at(-1)?.event;
+        if (firstEvent?.globalSeq !== undefined && episode.startSeq !== undefined && firstEvent.globalSeq !== episode.startSeq)
+            add('start_end_seq_mismatch', 'critical');
+        if (lastEvent?.globalSeq !== undefined && episode.endSeq !== undefined && lastEvent.globalSeq !== episode.endSeq)
+            add('start_end_seq_mismatch', 'critical');
+    }
+    else if (episode.startEventId || episode.endEventId) {
+        add('empty_episode_pointer_mismatch', 'critical');
+    }
+    if (pairs.some((pair) => !pair.event))
+        add('raw_event_missing', 'critical');
+    if (pairs.some((pair) => scopeMismatch(episode, pair.event)))
+        add('event_scope_mismatch', 'critical');
+    for (const pair of pairs) {
+        if (pair.event?.role === 'user') {
+            const resolved = resolveTrustedLocalDate(pair.event, input.timezone);
+            if (resolved.warning?.code === 'invalid_trusted_local_date')
+                add('invalid_local_date', 'warning');
+            if (resolved.warning?.code === 'legacy_unknown_local_date_source')
+                add('legacy_unknown_local_date_source', 'warning');
+        }
+    }
+    const turns = logicalTurnsFromPairs(pairs);
+    const userTurns = turns.filter((turn) => turn.some((pair) => pair.event?.role === 'user'));
+    userTurns.forEach((turn, index) => {
+        const user = turn.find((pair) => pair.event?.role === 'user');
+        if (!user)
+            return;
+        const relation = user.link.relation;
+        if (['hard_topic_switch', 'starts_new_topic', 'switches_topic'].includes(relation) && index !== 0)
+            add('invalid_hard_shift_position', 'critical');
+        if (relation === 'ambiguous_shift' && index !== 0)
+            add('invalid_ambiguous_shift_position', 'critical');
+        if (relation === 'closes_episode' && index !== userTurns.length - 1)
+            add('continuation_after_closure', 'critical');
+    });
+    const receipts = input.closureReceipts || [];
+    if ((episode.status === 'sealed' || episode.status === 'soft_sealed') && receipts.length === 0)
+        add('closure_receipt_status_mismatch', 'critical');
+    if (episode.status === 'open' && receipts.length > 0 && userTurns.some((turn) => turn.some((pair) => pair.link.relation === 'closes_episode')))
+        add('closure_receipt_status_mismatch', 'critical');
+    if (input.dreamJobState && episode.status !== 'sealed' && ['pending', 'processing', 'retry_scheduled', 'failed_retryable'].includes(input.dreamJobState))
+        add('dream_job_status_mismatch', 'critical');
+    if (input.dreamJobState === 'processed' && episode.dreamStatus !== 'processed')
+        add('dream_job_status_mismatch', 'critical');
+    return stableViolations(violations);
+}
+function positionsAreContiguous(pairs) {
+    const seen = new Set();
+    for (let index = 0; index < pairs.length; index += 1) {
+        const position = pairs[index].link.position;
+        if (seen.has(position) || position !== index + 1)
+            return false;
+        seen.add(position);
+    }
+    return true;
+}
+function scopeMismatch(episode, event) {
+    if (!event)
+        return false;
+    if (event.projectId !== episode.projectId)
+        return true;
+    if (event.sessionId !== episode.sessionId)
+        return true;
+    if ((episode.conversationThreadId || '') !== (event.threadId || ''))
+        return true;
+    const metadata = event.payload?.metadata;
+    if (episode.sourceAgent && metadata?.sourceAgent !== undefined && metadata.sourceAgent !== episode.sourceAgent)
+        return true;
+    return false;
+}
+function stableViolations(violations) {
+    const byReason = new Map();
+    for (const violation of violations)
+        byReason.set(violation.reason, violation);
+    return [...byReason.values()].sort((left, right) => left.reason.localeCompare(right.reason));
+}

package/dist/episode/EpisodeSplitPlanner.d.ts

@@ -0,0 +1,89 @@
+import type { MemoryEvent } from '../types/index.js';
+import type { EpisodeStore } from './EpisodeStore.js';
+import type { TurnRelation } from './EpisodeTypes.js';
+import type { EpisodeBoundaryConfig } from './EpisodeBoundaryPolicy.js';
+export declare const EPISODE_SPLIT_PLANNER_VERSION = "episode_split_preview.v1";
+export interface EpisodeSplitPlanSegment {
+    segmentIndex: number;
+    eventIds?: string[];
+    eventIdsHash: string;
+    eventIdsOmitted: number;
+    startEventId?: string;
+    endEventId?: string;
+    eventCount: number;
+    reason: string;
+    startedAt?: number;
+    endedAt?: number;
+    userEventCount: number;
+    assistantEventCount: number;
+    toolEventCount: number;
+    systemEventCount: number;
+}
+export interface EpisodeSplitProposedBoundary {
+    boundaryIndex: number;
+    beforeEventId?: string;
+    afterEventId?: string;
+    primaryUserEventId?: string;
+    reason: string;
+    relation?: TurnRelation;
+    effective?: boolean;
+    disposition?: 'explicit' | 'soft_review' | 'shadow' | 'enforced';
+}
+export interface EpisodeSplitImpactInventory {
+    eventCount: number;
+    userEventCount: number;
+    assistantEventCount: number;
+    toolEventCount: number;
+    systemEventCount: number;
+    hardShiftCount: number;
+    trustedLocalDates: string[];
+}
+export interface EpisodeSplitPlan {
+    planId: string;
+    plannerVersion: string;
+    projectId: string;
+    episodeId: string;
+    sourceFingerprint: string;
+    policyFingerprint: string;
+    normalizedPolicy: {
+        enabled: boolean;
+        maxEvents: number;
+        maxDurationMs: number;
+        maxIdleGapMs: number;
+        splitOnTrustedLocalDateChange: boolean;
+        mode: string;
+        applyToLive: boolean;
+        applyToImports: boolean;
+        policyVersion: string;
+        timezone?: string;
+    };
+    proposedBoundaries: EpisodeSplitProposedBoundary[];
+    impactInventory: EpisodeSplitImpactInventory;
+    segments: EpisodeSplitPlanSegment[];
+    warnings: string[];
+    unresolvedEventCount: number;
+    missingRawEventIds: string[];
+    evidenceIntegrityStatus: 'ok' | 'missing_raw_events';
+    requiresManualReview: boolean;
+    applyableInCurrentVersion: false;
+    applyCommand: null;
+}
+export declare class EpisodeSplitPlanner {
+    private readonly store;
+    private readonly resolveEvent?;
+    private readonly liveBoundaryConfig;
+    private readonly liveConfigDiagnostics;
+    constructor(store: EpisodeStore, resolveEvent?: ((eventId: string) => MemoryEvent | null | undefined) | undefined, liveBoundaryConfig?: Partial<EpisodeBoundaryConfig>, liveConfigDiagnostics?: Array<{
+        code: string;
+    }>);
+    plan(options: {
+        projectId: string;
+        episodeId: string;
+        maxEvents?: number;
+        maxDurationMs?: number;
+        maxIdleGapMs?: number;
+        timezone?: string;
+        includeEventIds?: boolean;
+    }): EpisodeSplitPlan;
+}
+//# sourceMappingURL=EpisodeSplitPlanner.d.ts.map