Cache Index Maintenance Utility

Build a utility to manually seed and tidy a cache index when content already exists on disk. The cache directory already contains content files addressed by integrity digests. Operations must avoid rewriting content and should rely on the package's index-level maintenance facilities rather than normal read/write helpers.

Capabilities

Seed existing content

• Registering a new key with provided integrity, size, and metadata updates the index so that looking up the key returns that integrity, metadata, and size without touching the content file. @test
• If the declared size does not match the stored content size for the digest, the operation fails with a size or integrity error and leaves the index untouched. @test

Compact key history

• Given multiple historical records for the same key, run a compaction that keeps only entries whose metadata satisfy a caller-supplied matcher comparing existing vs incoming entries, and ensure the latest pointer targets the newest kept entry. Afterward, listing the key shows only the kept entries. @test
• If a validation hook rejects a kept entry during compaction, the process aborts and the index remains unchanged. @test

Summarize current state

• Provide a summary function that returns the key's latest integrity, associated metadata, and the number of history entries after seeding and compaction. @test

Implementation

@generates

API

export interface SeedEntry {
  key: string;
  integrity: string;
  size: number;
  metadata?: Record<string, any>;
}

export async function seedIndex(cachePath: string, entries: SeedEntry[]): Promise<void>;

export type HistoryMatch = (existing: { key: string; metadata?: any; integrity: string; size?: number; time?: number }, incoming: { key: string; metadata?: any; integrity: string; size?: number; time?: number }) => boolean;
export type EntryValidator = (entry: { integrity: string; metadata?: any; size: number }) => boolean | Promise<boolean>;

export async function compactHistory(cachePath: string, key: string, match: HistoryMatch, validate?: EntryValidator): Promise<void>;

export async function summarize(cachePath: string, key: string): Promise<{ integrity: string | null; metadata?: any; historySize: number }>;

Dependencies { .dependencies }

cacache { .dependency }

Manual index maintenance support for the cache.