cogmem 3.7.1 → 3.7.3

package/dist/episode/EpisodeBoundaryAuditService.d.ts

@@ -0,0 +1,70 @@
+import type { MemoryEvent } from '../types/index.js';
+import { type EpisodeBoundaryConfig } from './EpisodeBoundaryPolicy.js';
+import type { EpisodeStore } from './EpisodeStore.js';
+import type { EpisodeStatus } from './EpisodeTypes.js';
+export interface EpisodeBoundaryAuditItem {
+    episodeId: string;
+    projectId: string;
+    status: EpisodeStatus;
+    sessionId: string;
+    threadId?: string;
+    sourceAgent?: string;
+    storedEventCount: number;
+    actualLinkedEventCount: number;
+    startedAt: number;
+    firstEventAt?: number;
+    lastEventAt?: number;
+    durationMs: number;
+    maxEventGapMs: number;
+    maxUserTurnGapMs: number;
+    maxBoundaryIdleGapMs: number;
+    trustedLocalDates: string[];
+    localDateConfidence: 'trusted' | 'unknown';
+    crossesTrustedLocalDate: boolean;
+    storedRelationCounts: Record<string, number>;
+    strongShiftCount: number;
+    ambiguousShiftCount: number;
+    userEventCount: number;
+    assistantEventCount: number;
+    toolEventCount: number;
+    systemEventCount: number;
+    outOfOrderEventCount: number;
+    sourceFingerprint: string;
+    detectedBoundaryCount: number;
+    effectiveBoundaryCount: number;
+    unresolvedEventCount: number;
+    missingRawEventIds: string[];
+    evidenceIntegrityStatus: 'ok' | 'missing_raw_events';
+    requiresManualReview: boolean;
+    severity: 'info' | 'warning' | 'critical';
+    reasons: string[];
+    warnings: string[];
+    recommendedAction: 'none' | 'split-plan' | 'inspect';
+}
+export interface EpisodeBoundaryAuditResult {
+    items: EpisodeBoundaryAuditItem[];
+    nextCursor?: string;
+}
+export declare class EpisodeBoundaryAuditService {
+    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;
+    }>);
+    audit(options: {
+        projectId: string;
+        episodeId?: string;
+        status?: EpisodeStatus;
+        limit?: number;
+        cursor?: string;
+        maxEvents?: number;
+        maxDurationMs?: number;
+        maxIdleGapMs?: number;
+        timezone?: string;
+    }): EpisodeBoundaryAuditResult;
+    private requireProjectEpisode;
+    private auditEpisode;
+}
+//# sourceMappingURL=EpisodeBoundaryAuditService.d.ts.map

package/dist/episode/EpisodeBoundaryAuditService.js

@@ -0,0 +1,276 @@
+import { createHash } from 'node:crypto';
+import { DEFAULT_EPISODE_BOUNDARY_CONFIG } from './EpisodeBoundaryPolicy.js';
+import { normalizeEpisodeBoundaryConfig, resolveTrustedLocalDate } from './EpisodeBoundaryPolicy.js';
+import { replayEpisodeBoundaries } from './EpisodeBoundaryReplayEngine.js';
+import { validateEpisodeInvariants } from './EpisodeInvariantValidator.js';
+export class EpisodeBoundaryAuditService {
+    store;
+    resolveEvent;
+    liveBoundaryConfig;
+    liveConfigDiagnostics;
+    constructor(store, resolveEvent, liveBoundaryConfig = {}, liveConfigDiagnostics = []) {
+        this.store = store;
+        this.resolveEvent = resolveEvent;
+        this.liveBoundaryConfig = liveBoundaryConfig;
+        this.liveConfigDiagnostics = liveConfigDiagnostics;
+    }
+    audit(options) {
+        if (!options.projectId)
+            throw new Error('projectId is required');
+        const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? 100), 1000));
+        const page = options.episodeId ? { episodes: [this.requireProjectEpisode(options.projectId, options.episodeId)], nextCursor: undefined } : this.store.listEpisodesForBoundaryAudit({
+            projectId: options.projectId,
+            statuses: options.status ? [options.status] : undefined,
+            limit,
+            cursor: options.cursor,
+        });
+        const overrideWarnings = boundaryOverrideWarnings(options);
+        const normalized = normalizeEpisodeBoundaryConfig(configWithDefinedOverrides(this.liveBoundaryConfig, options));
+        const aggregateCountCheck = options.maxEvents !== undefined || this.liveBoundaryConfig.maxEvents !== undefined || normalized.config.maxEvents !== DEFAULT_EPISODE_BOUNDARY_CONFIG.maxEvents;
+        const boundaryDiagnostics = this.liveConfigDiagnostics
+            .map((item) => item.code)
+            .filter((code) => code.startsWith('invalid_episode_boundary_'));
+        const items = page.episodes.map((episode) => this.auditEpisode(episode, normalized.config, [...boundaryDiagnostics, ...overrideWarnings, ...normalized.diagnostics.map((item) => item.code)], aggregateCountCheck));
+        return { items, nextCursor: page.nextCursor };
+    }
+    requireProjectEpisode(projectId, episodeId) {
+        const episode = this.store.getEpisode(episodeId);
+        if (!episode || episode.projectId !== projectId)
+            throw new Error(`episode_project_mismatch:${episodeId}`);
+        return episode;
+    }
+    auditEpisode(episode, config, configWarnings = [], aggregateCountCheck = true) {
+        const links = this.store.listEventLinks(episode.episodeId);
+        const pairs = links.map((link) => ({ link, event: this.resolveEvent?.(link.eventId) || undefined }));
+        const events = pairs.map((item) => item.event).filter((event) => Boolean(event));
+        const missingRawEventIds = pairs.filter((item) => !item.event).map((item) => item.link.eventId);
+        const times = events.map((event) => event.occurredAt).filter((value) => typeof value === 'number');
+        const dates = [...new Set(events.filter((event) => event.role === 'user').map((event) => trustedLocalDate(event, config.timezone)).filter((value) => Boolean(value)))];
+        const relationCounts = {};
+        for (const link of links)
+            relationCounts[link.relation] = (relationCounts[link.relation] || 0) + 1;
+        const userTimes = events.filter((event) => event.role === 'user' && Number.isFinite(event.occurredAt)).map((event) => event.occurredAt);
+        const reasons = [];
+        const warnings = [...configWarnings];
+        warnings.push(...dateWarningCodes(pairs, config.timezone));
+        const range = timeRange(times);
+        const durationMs = range ? range.max - range.min : 0;
+        const maxEventGapMs = maxGap(times);
+        const maxUserTurnGapMs = maxGap(userTimes);
+        const maxBoundaryIdleGapMs = maxBoundaryIdleGap(pairs);
+        const outOfOrderEventCount = outOfOrderCount(events);
+        const replay = replayEpisodeBoundaries({ episode, pairs, config });
+        const violations = validateEpisodeInvariants({
+            episode, pairs, timezone: config.timezone,
+            closureReceipts: this.store.listClosureReceipts({ episodeId: episode.episodeId, limit: 1 }),
+            dreamJobState: this.store.getDreamJobState(episode.episodeId),
+        });
+        warnings.push(...replay.warnings, ...replay.structuralAnomalies);
+        warnings.push(...replay.detectedBoundaries.filter((boundary) => !boundary.effective).map((boundary) => `detected_boundary:${boundary.reason}`));
+        for (const boundary of replay.effectiveBoundaries)
+            reasons.push(...auditReasonsForBoundary(boundary));
+        reasons.push(...violations.map((violation) => violation.reason));
+        if (episode.eventCount !== links.length)
+            reasons.push('stored_actual_event_count_mismatch');
+        if (missingRawEventIds.length > 0)
+            reasons.push('unresolved_raw_events');
+        if (outOfOrderEventCount > 0)
+            reasons.push('out_of_order_events');
+        if ((relationCounts.ambiguous_shift || 0) > 1)
+            reasons.push('repeated_ambiguous_shifts');
+        if (hardShiftCount(relationCounts) > 1)
+            reasons.push('multiple_hard_topic_switch_relations');
+        const hasClosureTurn = replay.logicalTurns.some((turn) => turn.some((pair) => pair.event?.role === 'user' && pair.link.relation === 'closes_episode'));
+        const importedEpisode = replay.logicalTurns.some(isImportedTurn);
+        if (aggregateCountCheck && config.maxEvents !== undefined && links.length > config.maxEvents && !hasClosureTurn && !(importedEpisode && config.applyToImports === false)) {
+            reasons.push('event_count_exceeds_max');
+        }
+        if (config.splitOnTrustedLocalDateChange && dates.length > 1)
+            reasons.push('multiple_trusted_local_dates');
+        if (!events.some((event) => event.role === 'user'))
+            reasons.push('zero_user_event_episode');
+        if (!dates.length)
+            warnings.push('trusted_local_date_unavailable');
+        const stableReasons = [...new Set(reasons)].sort();
+        const stableWarnings = [...new Set(warnings)].sort();
+        const critical = stableReasons.some((reason) => [
+            'stored_actual_event_count_mismatch', 'event_count_exceeds_max', 'duration_exceeds_max',
+            'boundary_idle_gap_exceeds_max', 'multiple_trusted_local_dates', 'unresolved_raw_events',
+        ].includes(reason)) || violations.some((violation) => violation.severity === 'critical');
+        return {
+            episodeId: episode.episodeId,
+            projectId: episode.projectId,
+            status: episode.status,
+            sessionId: episode.sessionId,
+            threadId: episode.conversationThreadId,
+            sourceAgent: episode.sourceAgent,
+            storedEventCount: episode.eventCount,
+            actualLinkedEventCount: links.length,
+            startedAt: episode.startedAt,
+            firstEventAt: range?.min,
+            lastEventAt: range?.max,
+            durationMs,
+            maxEventGapMs,
+            maxUserTurnGapMs,
+            maxBoundaryIdleGapMs,
+            trustedLocalDates: dates,
+            localDateConfidence: dates.length ? 'trusted' : 'unknown',
+            crossesTrustedLocalDate: dates.length > 1,
+            storedRelationCounts: relationCounts,
+            strongShiftCount: hardShiftCount(relationCounts),
+            ambiguousShiftCount: relationCounts.ambiguous_shift || 0,
+            userEventCount: events.filter((event) => event.role === 'user').length,
+            assistantEventCount: events.filter((event) => event.role === 'assistant' || event.role === 'agent').length,
+            toolEventCount: events.filter((event) => event.role === 'tool').length,
+            systemEventCount: events.filter((event) => event.role === 'system').length,
+            outOfOrderEventCount,
+            sourceFingerprint: sourceFingerprint(pairs.map((item) => ({ ...item.link, event: item.event }))),
+            detectedBoundaryCount: replay.detectedBoundaries.length,
+            effectiveBoundaryCount: replay.effectiveBoundaries.length,
+            unresolvedEventCount: missingRawEventIds.length,
+            missingRawEventIds: missingRawEventIds.slice(0, 50),
+            evidenceIntegrityStatus: missingRawEventIds.length ? 'missing_raw_events' : 'ok',
+            requiresManualReview: critical || missingRawEventIds.length > 0 || replay.structuralAnomalies.length > 0 || violations.some((violation) => violation.requiresManualReview),
+            severity: critical ? 'critical' : reasons.length ? 'warning' : 'info',
+            reasons: stableReasons,
+            warnings: stableWarnings,
+            recommendedAction: critical && !stableReasons.some((reason) => /raw_event|scope_mismatch|pointer_mismatch|dream.*mismatch|receipt.*mismatch|duplicate_or_gapped_positions|duplicate_active|empty_episode/u.test(reason))
+                ? 'split-plan' : stableReasons.length ? 'inspect' : 'none',
+        };
+    }
+}
+function maxGap(values) {
+    const ordered = values.filter(Number.isFinite).sort((a, b) => a - b);
+    let max = 0;
+    for (let index = 1; index < ordered.length; index += 1)
+        max = Math.max(max, ordered[index] - ordered[index - 1]);
+    return max;
+}
+function timeRange(values) {
+    let min;
+    let max;
+    for (const value of values) {
+        if (!Number.isFinite(value))
+            continue;
+        min = min === undefined ? value : Math.min(min, value);
+        max = max === undefined ? value : Math.max(max, value);
+    }
+    return min === undefined || max === undefined ? undefined : { min, max };
+}
+function maxBoundaryIdleGap(pairs) {
+    let max = 0;
+    let runningMax;
+    for (const pair of pairs) {
+        const event = pair.event;
+        if (event?.role === 'user' && typeof event.occurredAt === 'number' && Number.isFinite(event.occurredAt) && runningMax !== undefined) {
+            max = Math.max(max, Math.max(0, event.occurredAt - runningMax));
+        }
+        if (typeof event?.occurredAt === 'number' && Number.isFinite(event.occurredAt)) {
+            runningMax = Math.max(runningMax ?? event.occurredAt, event.occurredAt);
+        }
+    }
+    return max;
+}
+function auditReasonsForBoundary(boundary) {
+    if (boundary.guardCodes.length)
+        return boundary.guardCodes.map(auditReasonForGuard);
+    return [auditReasonForBoundary(boundary.reason)];
+}
+function auditReasonForGuard(code) {
+    if (code === 'max_events_exceeded')
+        return 'event_count_exceeds_max';
+    if (code === 'max_duration_exceeded')
+        return 'duration_exceeds_max';
+    if (code === 'max_idle_gap_exceeded')
+        return 'boundary_idle_gap_exceeds_max';
+    if (code === 'trusted_local_date_changed')
+        return 'multiple_trusted_local_dates';
+    return code;
+}
+function auditReasonForBoundary(reason) {
+    if (reason === 'max_events_boundary')
+        return 'event_count_exceeds_max';
+    if (reason === 'max_duration_boundary')
+        return 'duration_exceeds_max';
+    if (reason === 'max_idle_gap_boundary')
+        return 'boundary_idle_gap_exceeds_max';
+    if (reason === 'trusted_local_date_boundary')
+        return 'multiple_trusted_local_dates';
+    return reason;
+}
+function outOfOrderCount(events) {
+    let runningMax;
+    let count = 0;
+    for (const event of events) {
+        if (typeof event.occurredAt !== 'number')
+            continue;
+        if (runningMax !== undefined && event.occurredAt < runningMax)
+            count += 1;
+        runningMax = Math.max(runningMax ?? event.occurredAt, event.occurredAt);
+    }
+    return count;
+}
+function hardShiftCount(counts) {
+    return (counts.hard_topic_switch || 0) + (counts.starts_new_topic || 0) + (counts.switches_topic || 0);
+}
+function sourceFingerprint(items) {
+    const hash = createHash('sha256');
+    for (const item of items) {
+        hash.update(JSON.stringify([
+            item.eventId,
+            item.position,
+            item.relation,
+            item.event?.role,
+            item.event?.turnId,
+            item.event?.turnSeq,
+            item.event?.eventOrdinal,
+            item.event?.occurredAt,
+            item.event?.localDate,
+            item.event?.localDateSource,
+            item.event?.contentHash,
+        ]));
+    }
+    return hash.digest('hex');
+}
+function trustedLocalDate(event, timezone) {
+    return resolveTrustedLocalDate(event, timezone).date;
+}
+function dateWarningCodes(pairs, timezone) {
+    return [...new Set(pairs
+            .filter((item) => item.event?.role === 'user')
+            .map((item) => resolveTrustedLocalDate(item.event, timezone).warning?.code)
+            .filter((code) => code === 'invalid_trusted_local_date'))];
+}
+function isImportedTurn(group) {
+    return group.some((item) => {
+        const payload = item.event?.payload;
+        return payload?.metadata?.imported === true || payload?.metadata?.sourceRef !== undefined;
+    });
+}
+function configWithDefinedOverrides(base, overrides) {
+    const config = { ...base };
+    if (overrides.maxEvents !== undefined && validThreshold(overrides.maxEvents, 20, 500))
+        config.maxEvents = overrides.maxEvents;
+    if (overrides.maxDurationMs !== undefined && validThreshold(overrides.maxDurationMs, 300_000, 86_400_000))
+        config.maxDurationMs = overrides.maxDurationMs;
+    if (overrides.maxIdleGapMs !== undefined && validThreshold(overrides.maxIdleGapMs, 300_000, 86_400_000))
+        config.maxIdleGapMs = overrides.maxIdleGapMs;
+    if (typeof overrides.timezone === 'string' && overrides.timezone.trim())
+        config.timezone = overrides.timezone;
+    return config;
+}
+function validThreshold(value, min, max) {
+    return value !== undefined && Number.isFinite(value) && value >= min && value <= max;
+}
+function boundaryOverrideWarnings(overrides) {
+    const warnings = [];
+    if (overrides.maxEvents !== undefined && !validThreshold(overrides.maxEvents, 20, 500))
+        warnings.push('invalid_episode_boundary_max_events');
+    if (overrides.maxDurationMs !== undefined && !validThreshold(overrides.maxDurationMs, 300_000, 86_400_000))
+        warnings.push('invalid_episode_boundary_max_duration_ms');
+    if (overrides.maxIdleGapMs !== undefined && !validThreshold(overrides.maxIdleGapMs, 300_000, 86_400_000))
+        warnings.push('invalid_episode_boundary_max_idle_gap_ms');
+    if (overrides.timezone !== undefined && !overrides.timezone.trim())
+        warnings.push('invalid_episode_boundary_timezone');
+    return warnings;
+}

package/dist/episode/EpisodeBoundaryPolicy.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryEvent } from '../types/index.js';
+export type EpisodeBoundaryMode = 'off' | 'shadow' | 'enforce';
+export type EpisodeBoundaryGuardCode = 'max_events_exceeded' | 'max_duration_exceeded' | 'max_idle_gap_exceeded' | 'trusted_local_date_changed';
+export interface EpisodeBoundaryWarning {
+    code: string;
+    message: string;
+}
+export interface EpisodeBoundaryConfig {
+    enabled: boolean;
+    mode: EpisodeBoundaryMode;
+    maxEvents: number;
+    maxDurationMs: number;
+    maxIdleGapMs: number;
+    splitOnTrustedLocalDateChange: boolean;
+    auditDecisions: boolean;
+    applyToLive: boolean;
+    applyToImports: boolean;
+    policyVersion: string;
+    timezone?: string;
+}
+export interface EpisodeBoundaryMetrics {
+    activeEventCount: number;
+    activeStartedAt?: number;
+    activeUpdatedAt?: number;
+    elapsedMs?: number;
+    idleGapMs?: number;
+    trustedLocalDates: string[];
+    lastTrustedLocalDate?: string;
+    currentTrustedLocalDate?: string;
+    outOfOrderTimestamp?: boolean;
+}
+export interface EpisodeBoundaryGuardResult {
+    mode: EpisodeBoundaryMode;
+    guardAction: 'none' | 'shadow_new_episode' | 'enforce_new_episode';
+    guardCodes: EpisodeBoundaryGuardCode[];
+    metrics: EpisodeBoundaryMetrics;
+    warnings: EpisodeBoundaryWarning[];
+    policyVersion: string;
+}
+export declare const DEFAULT_EPISODE_BOUNDARY_CONFIG: EpisodeBoundaryConfig;
+export interface EpisodeBoundaryConfigDiagnostic {
+    severity: 'warning' | 'error';
+    code: string;
+    message: string;
+}
+export declare function normalizeEpisodeBoundaryConfig(input?: Partial<EpisodeBoundaryConfig>): {
+    config: EpisodeBoundaryConfig;
+    diagnostics: EpisodeBoundaryConfigDiagnostic[];
+};
+export declare class EpisodeBoundaryPolicy {
+    readonly config: EpisodeBoundaryConfig;
+    constructor(config?: Partial<EpisodeBoundaryConfig>);
+    evaluate(input: {
+        active?: {
+            eventCount: number;
+            startedAt?: number;
+            updatedAt?: number;
+            localDates?: string[];
+            lastTrustedLocalDate?: string;
+        };
+        primaryEvent: Pick<MemoryEvent, 'role' | 'occurredAt' | 'localDate' | 'payload'>;
+        imported?: boolean;
+    }): EpisodeBoundaryGuardResult;
+}
+export declare function isTrustedLocalDate(value: string | undefined): value is string;
+export declare function resolveTrustedLocalDate(event: {
+    occurredAt?: number;
+    localDate?: string;
+    localDateSource?: 'explicit' | 'generated_utc' | 'legacy_unknown';
+    payload?: unknown;
+} | undefined, timezone?: string): {
+    date?: string;
+    warning?: EpisodeBoundaryWarning;
+};
+//# sourceMappingURL=EpisodeBoundaryPolicy.d.ts.map

package/dist/episode/EpisodeBoundaryPolicy.js

@@ -0,0 +1,189 @@
+export const DEFAULT_EPISODE_BOUNDARY_CONFIG = {
+    enabled: true,
+    mode: 'enforce',
+    maxEvents: 100,
+    maxDurationMs: 7_200_000,
+    maxIdleGapMs: 1_800_000,
+    splitOnTrustedLocalDateChange: true,
+    auditDecisions: true,
+    applyToLive: true,
+    applyToImports: true,
+    policyVersion: 'episode_boundary.v1',
+};
+export function normalizeEpisodeBoundaryConfig(input = {}) {
+    const diagnostics = [];
+    const config = { ...DEFAULT_EPISODE_BOUNDARY_CONFIG, ...input };
+    config.enabled = boundedBoolean(input.enabled, DEFAULT_EPISODE_BOUNDARY_CONFIG.enabled, 'enabled', diagnostics);
+    config.auditDecisions = boundedBoolean(input.auditDecisions, DEFAULT_EPISODE_BOUNDARY_CONFIG.auditDecisions, 'audit_decisions', diagnostics);
+    config.applyToLive = boundedBoolean(input.applyToLive, DEFAULT_EPISODE_BOUNDARY_CONFIG.applyToLive, 'apply_to_live', diagnostics);
+    config.applyToImports = boundedBoolean(input.applyToImports, DEFAULT_EPISODE_BOUNDARY_CONFIG.applyToImports, 'apply_to_imports', diagnostics);
+    config.splitOnTrustedLocalDateChange = boundedBoolean(input.splitOnTrustedLocalDateChange, DEFAULT_EPISODE_BOUNDARY_CONFIG.splitOnTrustedLocalDateChange, 'split_on_trusted_local_date_change', diagnostics);
+    if (input.mode === 'off' || input.mode === 'shadow' || input.mode === 'enforce' || input.mode === undefined) {
+        config.mode = input.mode ?? DEFAULT_EPISODE_BOUNDARY_CONFIG.mode;
+    }
+    else {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'invalid_episode_boundary_mode',
+            message: 'episode_boundary.mode must be off, shadow, or enforce. Falling back to shadow.',
+        });
+        config.mode = 'shadow';
+    }
+    config.maxEvents = boundedInt(input.maxEvents, 20, 500, DEFAULT_EPISODE_BOUNDARY_CONFIG.maxEvents, 'max_events', diagnostics);
+    config.maxDurationMs = boundedInt(input.maxDurationMs, 300_000, 86_400_000, DEFAULT_EPISODE_BOUNDARY_CONFIG.maxDurationMs, 'max_duration_ms', diagnostics);
+    config.maxIdleGapMs = boundedInt(input.maxIdleGapMs, 300_000, 86_400_000, DEFAULT_EPISODE_BOUNDARY_CONFIG.maxIdleGapMs, 'max_idle_gap_ms', diagnostics);
+    if (input.policyVersion !== undefined && (typeof input.policyVersion !== 'string' || input.policyVersion.trim() === '')) {
+        diagnostics.push({ severity: 'warning', code: 'invalid_episode_boundary_policy_version', message: 'episode_boundary.policy_version must be a non-empty string.' });
+        config.policyVersion = DEFAULT_EPISODE_BOUNDARY_CONFIG.policyVersion;
+    }
+    else {
+        config.policyVersion = input.policyVersion ?? DEFAULT_EPISODE_BOUNDARY_CONFIG.policyVersion;
+    }
+    if (input.timezone !== undefined && (typeof input.timezone !== 'string' || input.timezone.trim() === '')) {
+        diagnostics.push({ severity: 'warning', code: 'invalid_episode_boundary_timezone', message: 'episode_boundary.timezone must be a non-empty valid IANA timezone.' });
+        config.timezone = undefined;
+    }
+    else if (input.timezone !== undefined) {
+        try {
+            new Intl.DateTimeFormat('en-US', { timeZone: input.timezone }).format(0);
+            config.timezone = input.timezone;
+        }
+        catch {
+            diagnostics.push({ severity: 'warning', code: 'invalid_episode_boundary_timezone', message: 'episode_boundary.timezone must be a valid IANA timezone.' });
+            config.timezone = undefined;
+        }
+    }
+    return { config, diagnostics };
+}
+export class EpisodeBoundaryPolicy {
+    config;
+    constructor(config = {}) {
+        this.config = normalizeEpisodeBoundaryConfig(config).config;
+    }
+    evaluate(input) {
+        const warnings = [];
+        const localDates = [...new Set(input.active?.localDates || [])];
+        const shouldEvaluate = Boolean(input.active
+            && input.primaryEvent.role === 'user'
+            && this.config.enabled
+            && this.config.mode !== 'off'
+            && (input.imported ? this.config.applyToImports : this.config.applyToLive));
+        const localDate = shouldEvaluate && this.config.splitOnTrustedLocalDateChange
+            ? trustedLocalDate(input.primaryEvent, this.config.timezone, warnings)
+            : undefined;
+        const currentTime = input.primaryEvent.occurredAt;
+        const outOfOrderTimestamp = shouldEvaluate && input.active?.updatedAt !== undefined
+            && currentTime !== undefined && currentTime < input.active.updatedAt;
+        if (outOfOrderTimestamp)
+            warnings.push({ code: 'out_of_order_timestamp', message: 'Event timestamp is earlier than the active episode update time.' });
+        const metrics = {
+            activeEventCount: input.active?.eventCount ?? 0,
+            activeStartedAt: input.active?.startedAt,
+            activeUpdatedAt: input.active?.updatedAt,
+            elapsedMs: input.active?.startedAt !== undefined && input.primaryEvent.occurredAt !== undefined
+                ? input.primaryEvent.occurredAt - input.active.startedAt : undefined,
+            idleGapMs: input.active?.updatedAt !== undefined && input.primaryEvent.occurredAt !== undefined
+                ? input.primaryEvent.occurredAt - input.active.updatedAt : undefined,
+            trustedLocalDates: localDates,
+            lastTrustedLocalDate: input.active?.lastTrustedLocalDate,
+            currentTrustedLocalDate: localDate,
+            outOfOrderTimestamp,
+        };
+        const guardCodes = [];
+        if (shouldEvaluate && input.active) {
+            if (input.active.eventCount >= this.config.maxEvents)
+                guardCodes.push('max_events_exceeded');
+            // A late arrival belongs to historical/review handling. It must not
+            // retroactively seal the current segment through clock/date guards.
+            if (!outOfOrderTimestamp) {
+                if ((metrics.elapsedMs ?? 0) > this.config.maxDurationMs)
+                    guardCodes.push('max_duration_exceeded');
+                if ((metrics.idleGapMs ?? 0) > this.config.maxIdleGapMs)
+                    guardCodes.push('max_idle_gap_exceeded');
+                if (this.config.splitOnTrustedLocalDateChange && localDate && input.active.lastTrustedLocalDate && input.active.lastTrustedLocalDate !== localDate) {
+                    guardCodes.push('trusted_local_date_changed');
+                }
+            }
+        }
+        return {
+            mode: this.config.mode,
+            guardAction: guardCodes.length ? (this.config.mode === 'shadow' ? 'shadow_new_episode' : 'enforce_new_episode') : 'none',
+            guardCodes,
+            metrics,
+            warnings,
+            policyVersion: this.config.policyVersion,
+        };
+    }
+}
+function boundedInt(value, min, max, fallback, name, diagnostics) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+        if (value !== undefined)
+            diagnostics.push({
+                severity: 'warning',
+                code: `invalid_episode_boundary_${name}`,
+                message: `episode_boundary.${name} must be between ${min} and ${max}.`,
+            });
+        return fallback;
+    }
+    return Math.trunc(value);
+}
+function boundedBoolean(value, fallback, name, diagnostics) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    diagnostics.push({
+        severity: 'warning',
+        code: `invalid_episode_boundary_${name}`,
+        message: `episode_boundary.${name} must be a boolean.`,
+    });
+    return fallback;
+}
+export function isTrustedLocalDate(value) {
+    if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export function resolveTrustedLocalDate(event, timezone) {
+    if (!event)
+        return { warning: { code: 'trusted_local_date_unavailable', message: 'No trusted local date source was available.' } };
+    if (event.localDate && !isTrustedLocalDate(event.localDate)) {
+        return { warning: { code: 'invalid_trusted_local_date', message: 'Trusted local date must use YYYY-MM-DD.' } };
+    }
+    const metadata = event.payload?.metadata;
+    const legacyMetadataSource = metadata?.localDateSource === 'event_store_utc_default' ? 'generated_utc' : metadata?.localDateSource;
+    const localDateSource = event.localDateSource ?? legacyMetadataSource ?? (event.localDate ? 'explicit' : undefined);
+    if (event.localDate && localDateSource === 'explicit')
+        return { date: event.localDate };
+    if (event.localDate && localDateSource === 'legacy_unknown') {
+        return { warning: { code: 'legacy_unknown_local_date_source', message: 'Legacy local date source is not trusted for boundary decisions.' } };
+    }
+    if (timezone && typeof event.occurredAt === 'number' && Number.isFinite(event.occurredAt)) {
+        const utcDate = new Date(event.occurredAt).toISOString().slice(0, 10);
+        if (!event.localDate || (localDateSource === 'generated_utc' && event.localDate === utcDate))
+            return { date: localDateInTimezone(event.occurredAt, timezone) };
+    }
+    if (event.localDate && localDateSource === 'generated_utc' && isTrustedLocalDate(event.localDate))
+        return { date: event.localDate };
+    return { warning: { code: 'trusted_local_date_unavailable', message: 'No trusted local date source was available.' } };
+}
+function localDateInTimezone(occurredAt, timezone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(occurredAt);
+    const year = parts.find((part) => part.type === 'year')?.value;
+    const month = parts.find((part) => part.type === 'month')?.value;
+    const day = parts.find((part) => part.type === 'day')?.value;
+    return year && month && day ? `${year}-${month}-${day}` : new Date(occurredAt).toISOString().slice(0, 10);
+}
+function trustedLocalDate(event, timezone, warnings) {
+    const resolved = resolveTrustedLocalDate(event, timezone);
+    if (resolved.warning)
+        warnings.push(resolved.warning);
+    return resolved.date;
+}

package/dist/episode/EpisodeBoundaryReplayEngine.d.ts

@@ -0,0 +1,65 @@
+import type { MemoryEvent } from '../types/index.js';
+import type { EpisodeBoundaryConfig, EpisodeBoundaryGuardCode, EpisodeBoundaryGuardResult } from './EpisodeBoundaryPolicy.js';
+import type { EpisodeEventLink, EpisodeStatus, TurnRelation } from './EpisodeTypes.js';
+export type EpisodeReplayPair = {
+    link: EpisodeEventLink;
+    event?: MemoryEvent;
+};
+export interface EpisodeBoundaryReplayState {
+    eventCount: number;
+    startedAt?: number;
+    lastEventAt?: number;
+    lastTrustedUserLocalDate?: string;
+    trustedLocalDates: string[];
+}
+export interface EpisodeBoundaryReplayBoundary {
+    boundaryIndex: number;
+    beforeEventId?: string;
+    afterEventId?: string;
+    primaryUserEventId?: string;
+    relation?: TurnRelation;
+    reason: string;
+    guardCodes: EpisodeBoundaryGuardCode[];
+    warnings: string[];
+    detected: boolean;
+    effective: boolean;
+    disposition: 'explicit' | 'soft_review' | 'shadow' | 'enforced';
+    guardResult?: EpisodeBoundaryGuardResult;
+}
+export interface EpisodeBoundaryReplayResult {
+    logicalTurns: EpisodeReplayPair[][];
+    detectedBoundaries: EpisodeBoundaryReplayBoundary[];
+    effectiveBoundaries: EpisodeBoundaryReplayBoundary[];
+    warnings: string[];
+    structuralAnomalies: string[];
+    runningState: EpisodeBoundaryReplayState;
+    policyDisposition: 'disabled' | 'shadow' | 'enforce';
+}
+export declare function replayEpisodeBoundaries(input: {
+    episode: {
+        startedAt?: number;
+        status?: EpisodeStatus;
+    };
+    pairs: EpisodeReplayPair[];
+    config: EpisodeBoundaryConfig;
+    imported?: boolean;
+    live?: boolean;
+    initialState?: EpisodeBoundaryReplayState;
+}): EpisodeBoundaryReplayResult;
+/** Reduces accepted evidence without evaluating a new boundary. */
+export declare function replayEpisodeBoundaryState(input: {
+    episode: {
+        startedAt?: number;
+    };
+    pairs: EpisodeReplayPair[];
+    timezone?: string;
+}): EpisodeBoundaryReplayState;
+export declare function replayPendingTurnBoundary(input: {
+    config: EpisodeBoundaryConfig;
+    active?: EpisodeBoundaryReplayState;
+    pendingPairs: EpisodeReplayPair[];
+    primaryEvent: MemoryEvent;
+    imported?: boolean;
+}): EpisodeBoundaryGuardResult;
+export declare function logicalTurnsFromPairs(pairs: EpisodeReplayPair[]): EpisodeReplayPair[][];
+//# sourceMappingURL=EpisodeBoundaryReplayEngine.d.ts.map