/**
 * Memory Engine — Exported Types
 *
 * All public types and interfaces for the memory subsystem.
 * Extracted from memory.ts Phase 1 of the v7.x memory split.
 *
 * Import cycle constraint: this file may only import from external modules
 * (memory-control-plane, etc.) — never from memory.ts or other memory/ siblings.
 */
import type { MemoryProvenance, MemoryReconciliationEntry } from '../memory-control-plane.js';
export type { MemoryProvenance, MemoryReconciliationEntry };
export interface MemoryItem {
    id: string;
    content: string;
    contentFingerprint?: string;
    priority: number;
    timestamp: number;
    tags: string[];
    tier: 'prefrontal' | 'hippocampus' | 'cortex';
    scope: 'session' | 'project' | 'user' | 'promoted' | 'shared';
    state: 'active' | 'quarantined' | 'scrap' | 'expired';
    source: 'operator' | 'runtime' | 'worker' | 'operative' | 'imported' | 'system' | 'rag';
    sessionId?: string;
    accessCount: number;
    links?: string[];
    parentId?: string;
    depth?: number;
    entropy: number;
    mass: number;
    trust: number;
    qmdRecency?: number;
    qmdFrequency?: number;
    qmdRelevance?: number;
    validFrom?: number;
    validTo?: number;
    expiresAt?: number;
    purgeAt?: number;
    supersedes?: string;
    supersededBy?: string;
    provenance: MemoryProvenance;
}
export interface MemoryLink {
    fromId: string;
    toId: string;
    weight: number;
    type: 'semantic' | 'temporal' | 'tagged';
}
export interface MemoryStats {
    schemaVersion: number;
    prefrontal: number;
    hippocampus: number;
    cortex: number;
    totalLinks: number;
    oldestEntry: number | null;
    purgeEligible: number;
    quarantineBacklog: number;
    lastHygieneAt: number | null;
    topTags: string[];
}
export interface MemoryStorageStatus {
    requestedDbPath: string;
    activeDbPath: string;
    stateRoot: string;
    graphDbPath: string;
    vaultDir: string;
    fallbackApplied: boolean;
    fallbackReason?: string;
}
export type MemoryContainerLane = 'profile' | 'workspace' | 'shared' | 'inbox';
export type MemoryLayerId = 'working' | 'session' | 'project' | 'pattern';
export interface MemoryLayerContractEntry {
    id: MemoryLayerId;
    description: string;
    scopes: MemoryItem['scope'][];
    preferredTiers: MemoryItem['tier'][];
    lanes: MemoryContainerLane[];
    rawEvidenceRetained: true;
    auditTrail: {
        snapshots: true;
        history: true;
        provenance: true;
    };
}
export declare const MEMORY_LAYER_CONTRACT: Record<MemoryLayerId, MemoryLayerContractEntry>;
export interface MemoryRecallFilters {
    sessionId?: string;
    runId?: string;
    userId?: string;
    agentId?: string;
    appId?: string;
    repoId?: string;
    workspaceId?: string;
    projectId?: string;
    lane?: MemoryContainerLane;
    includeShared?: boolean;
    includeProfile?: boolean;
    includeHidden?: boolean;
    minScore?: number;
    rerankerHint?: 'balanced' | 'trust' | 'freshness';
}
export type MemoryRetentionHint = NonNullable<MemoryProvenance['retentionHint']>;
export type MemoryHistoryEventType = 'created' | 'updated' | 'deleted' | 'feedback' | 'state-changed';
export interface MemoryHistoryEntry {
    id: string;
    memoryId: string;
    eventType: MemoryHistoryEventType;
    timestamp: number;
    summary: string;
    actorScope: {
        sessionId?: string;
        runId?: string;
        workerId?: string;
        userId?: string;
        agentId?: string;
        appId?: string;
    };
    details: Record<string, unknown>;
}
export interface MemoryUpdateResult {
    updated: boolean;
    historyEntry?: MemoryHistoryEntry;
    item?: MemoryDetail;
}
export interface MemoryDeleteResult {
    deleted: boolean;
    hardDelete: boolean;
    historyEntry?: MemoryHistoryEntry;
    item?: MemorySnapshot;
}
export interface MemoryFeedbackResult {
    accepted: boolean;
    historyEntry?: MemoryHistoryEntry;
    item?: MemorySnapshot;
    trust?: number;
    priority?: number;
    decay?: MemoryDecayProfile;
    reinforcement?: MemoryReinforcementProfile;
}
export interface MemoryRecallMatch {
    content: string;
    id: string;
    score: number;
    confidence: number;
    entropy: number;
    trust: number;
    tier: string;
    priority: number;
}
export interface MemorySearchHighlight {
    start: number;
    end: number;
}
export interface MemorySearchMatch {
    id: string;
    content: string;
    score: number;
    tags: string[];
    scope: MemoryItem['scope'];
    state: MemoryItem['state'];
    provenance: MemoryProvenance;
    highlights: MemorySearchHighlight[];
}
export interface MemoryContainerSummary {
    generatedAt: number;
    byLane: Record<MemoryContainerLane, number>;
    byRepoId: Record<string, number>;
    byProjectId: Record<string, number>;
    byWorkspaceId: Record<string, number>;
    hiddenCount: number;
}
export interface MemoryBackupSnapshot {
    timestamp: number;
    reason: string;
    path: string;
    itemCount: number;
}
export interface MemoryEntityReference {
    type: 'session' | 'run' | 'skill' | 'workflow';
    id: string;
}
export type MemoryDecayState = 'fresh' | 'fading' | 'stale' | 'retiring';
export type MemoryDecayNextAction = 'keep' | 'reinforce' | 'review' | 'archive';
export interface MemoryDecayProfile {
    score: number;
    state: MemoryDecayState;
    ageDays: number;
    halfLifeDays: number;
    retentionHint: MemoryRetentionHint | 'default';
    nextAction: MemoryDecayNextAction;
    reasons: string[];
}
export interface MemoryReinforcementProfile {
    score: number;
    accessCount: number;
    trust: number;
    feedbackCount: number;
    lastFeedbackAt?: number;
    qmd: {
        recency: number;
        frequency: number;
        relevance: number;
    };
    reasons: string[];
}
export interface MemorySnapshot {
    id: string;
    tier: MemoryItem['tier'];
    scope: MemoryItem['scope'];
    state: MemoryItem['state'];
    source: MemoryItem['source'];
    priority: number;
    timestamp: number;
    tags: string[];
    excerpt: string;
    parentId?: string;
    depth?: number;
    accessCount: number;
    linkCount: number;
    sessionId?: string;
    relevanceScore: number;
    importanceScore: number;
    freshnessScore: number;
    trustScore: number;
    entropyScore: number;
    decay: MemoryDecayProfile;
    reinforcement: MemoryReinforcementProfile;
    provenance: MemoryProvenance;
    expiresAt?: number;
    purgeAt?: number;
    supersedes?: string;
    supersededBy?: string;
    related: MemoryEntityReference[];
}
export interface MemoryDetail extends MemorySnapshot {
    content: string;
    lineage: MemorySnapshot[];
    linkedMemories: MemorySnapshot[];
    timeline: MemorySnapshot[];
}
export interface MemoryTraceDetail extends MemoryDetail {
    reconciliation?: MemoryReconciliationEntry;
}
export interface MemoryNetworkNode {
    id: string;
    label: string;
    entityType: 'memory' | 'session' | 'run' | 'skill' | 'workflow' | 'cluster';
    tier?: MemoryItem['tier'];
    priority?: number;
    timestamp?: number;
    count?: number;
}
export interface MemoryNetworkLink {
    source: string;
    target: string;
    type: 'semantic' | 'temporal' | 'tagged' | 'lineage' | 'artifact-derived';
    weight: number;
}
export interface MemoryNetworkSnapshot {
    focusId?: string;
    nodes: MemoryNetworkNode[];
    links: MemoryNetworkLink[];
    stats?: {
        limit: number;
        depth: number;
        visible: number;
        overflow: number;
        quarantinedHidden: number;
        hidden: number;
    };
}
export interface MemoryCheckFinding {
    id: string;
    severity: 'low' | 'medium' | 'high';
    category: 'duplicate' | 'contradiction' | 'secret' | 'claim' | 'entropy' | 'provenance';
    message: string;
    relatedIds: string[];
}
export interface MemoryCheckResult {
    contentPreview: string;
    action: 'allow' | 'warn' | 'quarantine' | 'block';
    findings: MemoryCheckFinding[];
    duplicateCluster: string[];
    canPromote: boolean;
}
export interface MemoryConfig {
    decayRate?: number;
    priorityRetention?: number;
    flushEntropyThreshold?: number;
    recallCandidateLimit?: number;
    vaultCompactionThreshold?: number;
    expiredPurgeBatchSize?: number;
    vacuumMinIntervalMs?: number;
    quarantineRetentionMs?: number;
    scrapRetentionMs?: number;
    expiredPurgeGraceMs?: number;
    networkVisibleLimit?: number;
    /** Reconciliation: minimum word overlap to trigger contradiction check */
    reconciliationContradictionThreshold?: number;
    /** Reconciliation: minimum word overlap to trigger merge */
    reconciliationMergeThreshold?: number;
    /** Reconciliation: minimum word overlap to treat as duplicate */
    reconciliationDuplicateThreshold?: number;
    /** Seed first-run onboarding memories in the default persistent store. */
    seedDemoMemories?: boolean;
}
export interface MemoryAuditResult {
    scanned: number;
    quarantined: MemorySnapshot[];
    findings: Array<MemoryCheckResult & {
        id: string;
    }>;
}
export interface MemoryHealthSummary {
    generatedAt: number;
    schemaVersion: number;
    total: number;
    active: number;
    quarantined: number;
    scrap: number;
    expired: number;
    promoted: number;
    shared: number;
    purgeEligible: number;
    quarantineBacklog: number;
    lastHygieneAt: number | null;
    topTags: string[];
    /** Tier distribution for the memory pyramid dashboard widget. */
    tierCounts?: {
        prefrontal: number;
        hippocampus: number;
        cortex: number;
    };
    /** Formation rate counts for the last hour and day. */
    formationRate?: {
        lastHour: number;
        lastDay: number;
    };
    /** Last 5 tier promotions for the promotion ticker. */
    recentPromotions?: Array<{
        memoryId: string;
        from: string;
        to: string;
        at: number;
    }>;
}
export interface MemoryHygieneResult {
    generatedAt: number;
    mode: 'report' | 'apply';
    batchSize: number;
    states: Array<MemoryItem['state']>;
    schemaVersion: number;
    lastHygieneAt: number | null;
    purgeEligible: number;
    quarantineBacklog: number;
    audit: MemoryAuditResult;
    health: MemoryHealthSummary;
    maintenance?: {
        activeTrimmed: number;
        quarantinedExpired: number;
        scrapExpired: number;
        purged: number;
    };
}
export interface MemoryExportItem {
    id: string;
    content: string;
    contentFingerprint?: string;
    priority: number;
    timestamp: number;
    tags: string[];
    tier: MemoryItem['tier'];
    scope: MemoryItem['scope'];
    state: MemoryItem['state'];
    source: MemoryItem['source'];
    sessionId?: string;
    accessCount: number;
    parentId?: string;
    depth?: number;
    entropy: number;
    mass: number;
    trust: number;
    expiresAt?: number;
    purgeAt?: number;
    supersedes?: string;
    supersededBy?: string;
    provenance: MemoryProvenance;
}
export interface MemoryExportOrigin {
    source: string;
    tool: string;
    repoId?: string;
    workspaceId?: string;
    projectId?: string;
    sessionId?: string;
}
export interface MemoryExportBundle {
    version: number;
    schemaVersion?: string;
    exportedAt: number;
    sessionId: string;
    origin?: MemoryExportOrigin;
    stats: MemoryStats;
    health: MemoryHealthSummary;
    items: MemoryExportItem[];
}
export interface MemoryImportResult {
    imported: number;
    duplicates: number;
    added: number;
    updated: number;
    skipped: number;
    quarantined: number;
    importedIds: string[];
}
export interface TokenTelemetryEntry {
    id: string;
    sessionId: string;
    timestamp: number;
    task: string;
    model: string;
    tokensOptimized: number;
    tokensSaved: number;
    tokensForwarded: number;
    compressionRatio: number;
    fileCount: number;
    usdValueSaved: number;
}
