import type { InspirationDesignSignals } from './inspirationDesignContext';
/**
 * Runtime user cache for inspiration-link design context. Persists generated
 * designmd markdown plus safe metadata so future MCP
 * `create_zero_to_one_project` requests with the same web link can reuse
 * prior extraction by default. Treated as runtime user data — never mutates
 * the bundled `src/services/templates/designmd` catalog.
 *
 * Path layout (local filesystem implementation):
 *   <directory>/<sha256(normalizedUrl)>.json
 *
 * The default <directory> is `~/.rivet/design-context-cache/`. The store
 * abstraction is interface-first so future hosted/server deployments can
 * provide a durable backend (HTTPS, KV, SQL) without changing the
 * extraction or MCP orchestration logic.
 */
/**
 * Output/extractor schema version. Bump when the cache entry shape or the
 * generated markdown structure changes incompatibly. Cached entries with a
 * different schema version are not silently reused — they regenerate.
 */
export declare const DESIGN_CONTEXT_SCHEMA_VERSION = "2";
/**
 * Default freshness window for a cached entry. Entries older than this are
 * marked `stale` and trigger regeneration by default. Tunable per call so
 * tests can exercise the stale branch without sleeping.
 */
export declare const DEFAULT_FRESHNESS_MS: number;
/**
 * Default confidence threshold below which cached entries are considered
 * low-confidence and trigger regeneration. Mirrors the in-extractor
 * `LOW_SIGNAL_THRESHOLD` so cached and live signals stay aligned.
 */
export declare const DEFAULT_CONFIDENCE_THRESHOLD = 18;
export type FreshnessState = 'fresh' | 'stale';
export interface DesignContextCacheMetadata {
    /** Stable cache key (sha256 hex of normalized URL). */
    cacheKey: string;
    /** Extractor/output schema version used to produce this entry. */
    schemaVersion: string;
    /** Wall-clock creation time (ms since epoch). */
    createdAtMs: number;
    /** Wall-clock last-used time (ms since epoch). */
    lastUsedAtMs: number;
    /** Signal density / confidence score (0-100). */
    confidence: number;
    /**
     * Safe outcome metadata only — short non-sensitive warning codes such as
     * `low_signal` or `partial_meta`. MUST NOT include fetched page content,
     * full URLs, or extracted text snippets.
     */
    warningCodes: string[];
}
export interface DesignContextCacheEntry {
    metadata: DesignContextCacheMetadata;
    /** Generated single-source designmd markdown (separate-flavor). */
    markdown: string;
    /** Short user-visible label (already truncated to fit downstream cap). */
    label: string;
    /**
     * Structured design signals for the source URL. Storing the same derived
     * design observations the markdown already encodes (palette, families,
     * sections, components) so merge-strategy callers can re-summarise across
     * multiple cached entries without re-fetching. Raw HTML, screenshots,
     * DOM dumps, and full source text MUST NOT be persisted here.
     */
    signals: InspirationDesignSignals;
}
export interface DesignContextStore {
    get(cacheKey: string): Promise<DesignContextCacheEntry | undefined>;
    put(entry: DesignContextCacheEntry): Promise<void>;
}
/**
 * Normalize an HTTP/HTTPS URL for cache keying. Lowercases scheme and host,
 * strips default ports and fragments, and preserves meaningful path/query
 * so two pages with the same host but different paths or query strings
 * keep separate cache entries. Returns `undefined` for inputs that are not
 * parseable HTTP/HTTPS URLs.
 */
export declare const normalizeCacheUrl: (rawUrl: string) => string | undefined;
/**
 * Compute a stable cache key from a normalized URL. SHA-256 hashed to hex
 * so the resulting key is filesystem-safe and does not embed proprietary
 * URL content in the filename layer.
 */
export declare const cacheKeyForUrl: (rawUrl: string) => string | undefined;
/**
 * Coarse age bucket for safe telemetry. Maps a wall-clock age in
 * milliseconds onto a small fixed bucket name so analytics never receive
 * exact timestamps.
 */
export declare const ageBucketFor: (ageMs: number) => "lt_1h" | "1h_24h" | "1d_7d" | "7d_30d" | "gt_30d";
/**
 * Coarse confidence bucket for safe telemetry. Three buckets keyed off the
 * extractor signal density score so reuse outcomes can be aggregated
 * without leaking specific confidence values.
 */
export declare const confidenceBucketFor: (confidence: number) => "low" | "medium" | "high";
/**
 * Return true when the user prompt explicitly asks for fresh/latest/
 * current design context. Used by the MCP flow to bypass cache reuse even
 * when a compatible entry exists.
 */
export declare const promptRequestsFreshExtraction: (prompt: string) => boolean;
export type CacheReuseDecision = {
    reuse: true;
    freshness: FreshnessState;
    ageMs: number;
} | {
    reuse: false;
    reason: 'version_mismatch' | 'stale' | 'low_confidence' | 'forced_refresh' | 'corrupt';
    freshness: FreshnessState;
    ageMs: number;
};
interface CanReuseOptions {
    forceRefresh: boolean;
    schemaVersion?: string;
    confidenceThreshold?: number;
    freshnessMs?: number;
    now?: number;
}
/**
 * Decide whether a cached entry is reusable for a request, factoring in
 * extractor/schema version, freshness window, confidence threshold, and
 * any explicit user request for fresh extraction. Callers MUST honour the
 * decision — the store itself never silently reuses incompatible entries.
 */
export declare const canReuseCacheEntry: (entry: DesignContextCacheEntry, options: CanReuseOptions) => CacheReuseDecision;
interface FileDesignContextStoreOptions {
    /**
     * Override the cache directory. Defaults to `~/.rivet/design-context-cache`
     * via `os.homedir()`. Tests use a tmpdir override so the suite never
     * touches the real user cache.
     */
    directory?: string;
}
/**
 * Filesystem-backed `DesignContextStore`. One JSON file per cache key under
 * a per-user cache directory. Safe to delete the entire directory without
 * affecting bundled catalog data or compiled application code.
 *
 * Read/write failures degrade gracefully — get returns undefined on any
 * parse/IO error so the MCP flow falls through to a fresh extraction
 * instead of crashing the user request.
 */
export declare class FileDesignContextStore implements DesignContextStore {
    private readonly directory;
    private dirReady;
    constructor(options?: FileDesignContextStoreOptions);
    /**
     * Resolve a cache key to its on-disk file path. Rejects keys that do not
     * match the expected sha256 hex shape so a malformed key cannot escape
     * the cache directory.
     */
    resolvePath(cacheKey: string): string | undefined;
    get(cacheKey: string): Promise<DesignContextCacheEntry | undefined>;
    put(entry: DesignContextCacheEntry): Promise<void>;
}
export {};
//# sourceMappingURL=designContextStore.d.ts.map