import { type ProjectMemoryEntry, type MemoryPromotionPolicy, type MemoryScope } from '../types/sparkContracts';
import { type KnowledgeScope } from '../services/scopedKnowledgeStore';
/** One audit-log row recording a cross-scope promotion. */
export interface PromotionAuditEntry {
    entryId: string;
    policy: MemoryPromotionPolicy;
    /** Wall-clock when the audit row was written (epoch ms). */
    auditedAt: number;
}
export interface ListOptions {
    scope?: Exclude<MemoryScope, 'session'>;
    projectKey?: string;
    /** Restrict to entries whose `tags` overlap with at least one of these. */
    anyOfTags?: string[];
}
export interface RecallOptions {
    /** Restrict to a scope. Defaults to all (project + world). */
    scope?: Exclude<MemoryScope, 'session'>;
    /** Restrict to a project key prefix (exact match). */
    projectKey?: string;
    /** Tag tokens to score against — entries with overlap rank higher. */
    tags?: string[];
    /** Maximum hits returned. Defaults to 5. */
    topK?: number;
}
/** One recall hit with the score that ranked it. The hit object is a
 * shallow copy of the stored entry — recall never mutates the store
 * even via reference sharing. */
export interface RecallHit {
    entry: ProjectMemoryEntry;
    score: number;
}
/**
 * ProjectMemory — local file-backed store for project + world entries.
 * Session entries stay in `analysisPatternMemory.ts` and are not
 * touched by this class.
 */
export declare class ProjectMemory {
    private readonly storagePath;
    private readonly entries;
    private readonly auditLog;
    private loaded;
    constructor(storagePath: string);
    /** Idempotently load on-disk state into memory. */
    load(): void;
    /**
     * Save (insert or replace) an entry. Throws when:
     *   - scope is 'session' (those belong in analysisPatternMemory.ts)
     *   - scope is 'world' but promotionPolicy is missing
     *   - promotionPolicy carries a trigger outside the canonical enum
     */
    saveProjectMemoryEntry(entry: ProjectMemoryEntry, storageScope?: KnowledgeScope): void;
    /** Get an entry by id. */
    getProjectMemoryEntry(entryId: string, storageScope?: KnowledgeScope): ProjectMemoryEntry | undefined;
    /** Remove an entry. Returns whether it was present. The promotion
     * audit log is NOT redacted — past promotions stay traceable. */
    removeProjectMemoryEntry(entryId: string, storageScope?: KnowledgeScope): boolean;
    /** Filtered list, deterministically ordered by entryId. */
    listProjectMemoryEntries(opts?: ListOptions, storageScope?: KnowledgeScope): ProjectMemoryEntry[];
    /**
     * Pure-read recall. Scores entries by tag overlap with the query
     * tags. Never writes — `lastSeenAt` and any other mutable counters
     * remain frozen even after thousands of recall calls.
     */
    recallProjectMemory(opts?: RecallOptions, storageScope?: KnowledgeScope): RecallHit[];
    /**
     * Promote an entry across scopes per the supplied policy. Throws on
     * any trigger outside the enum; appends a row to the promotion
     * audit log; sets `entry.promotionPolicy` to the supplied policy.
     */
    promoteEntry(entryId: string, policy: MemoryPromotionPolicy, storageScope?: KnowledgeScope): void;
    /** Read-only view of the audit log, sorted by audit time ascending. */
    getPromotionAudit(): PromotionAuditEntry[];
    /** Count entries currently in storage by scope. */
    getStats(storageScope?: KnowledgeScope): Record<'project' | 'world', number>;
    private assertSaveInvariants;
    /** Atomic temp+rename. Same contract as ragStore / baselineStore. */
    private persist;
}
//# sourceMappingURL=projectMemory.d.ts.map