@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/prompt-budget.cjs

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * prompt-budget.cts
+ *
+ * Pure functions for assembling and trimming review prompts to fit within
+ * a token budget (ADR-457 build-at-publish: the hand-written
+ * bin/lib/prompt-budget.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * Used by the review pipeline to support small-context models.
+ *
+ * Trim priority (in order — never violate):
+ *   1. Instructions:   ALWAYS kept verbatim
+ *   2. Reserve note tokens FIRST when any trim is anticipated
+ *   3. Roadmap:        ALWAYS kept verbatim
+ *   4. PROJECT.md:     head-shrink to projectMdHeadLines (default 40) if over budget
+ *   5. Plans:          tail-truncate proportionally; never drop a whole plan
+ *   6. Context:        DROP first if still over
+ *   7. Research:       DROP second if still over
+ *   8. Requirements:   DROP last (last-resort)
+ *   9. Hard-fail:      if minimum-set exceeds effectiveBudget
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokens = estimateTokens;
+exports.applyBudget = applyBudget;
+const NOTE_RESERVE_TOKENS = 80;
+const DEFAULT_NOTE_TEMPLATE = [
+    '<note>',
+    'Prompt automatically trimmed to fit a {budget}-token budget.',
+    'Omitted sections: {omittedList}.',
+    'Plan content truncated by approximately {planTruncationPct}%.',
+    'Treat any missing context as out-of-scope rather than a review concern.',
+    '</note>',
+].join('\n');
+/**
+ * Estimate tokens for a string. Chars / 4, rounded up.
+ */
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Render the trim-disclosure note.
+ */
+function renderNote(template, budget, omitted, planTruncationPct) {
+    const omittedList = omitted.length > 0 ? omitted.join(', ') : 'none';
+    return template
+        .replace('{budget}', String(budget))
+        .replace('{omittedList}', omittedList)
+        .replace('{planTruncationPct}', String(Math.round(planTruncationPct)));
+}
+/**
+ * Head-shrink a string to at most `maxLines` lines.
+ */
+function headShrink(text, maxLines) {
+    if (maxLines <= 0)
+        return '';
+    let idx = -1;
+    let seen = 0;
+    while (seen < maxLines) {
+        idx = text.indexOf('\n', idx + 1);
+        if (idx === -1)
+            return text;
+        seen += 1;
+    }
+    return text.slice(0, idx);
+}
+/**
+ * Tail-truncate a string to at most `maxChars` characters.
+ */
+function tailTruncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars);
+}
+/**
+ * Assemble the final prompt string from its sections.
+ */
+function assemblePrompt(parts) {
+    const { instructions, note, roadmap, projectMd, plans, context, research, requirements, } = parts;
+    const blocks = [];
+    blocks.push(instructions);
+    if (note)
+        blocks.push(note);
+    blocks.push('## Roadmap\n\n' + roadmap);
+    if (projectMd)
+        blocks.push('## Project\n\n' + projectMd);
+    const planBlocks = plans
+        .map((p) => '### ' + p.file + '\n\n' + p.content)
+        .join('\n\n');
+    blocks.push('## Plans\n\n' + planBlocks);
+    if (context)
+        blocks.push('## Context\n\n' + context);
+    if (research)
+        blocks.push('## Research\n\n' + research);
+    if (requirements)
+        blocks.push('## Requirements\n\n' + requirements);
+    return blocks.join('\n\n');
+}
+/**
+ * Apply a token budget to a set of review prompt sections.
+ * Returns the trimmed prompt and structured metadata.
+ */
+function applyBudget({ sections, budget, options = {} }) {
+    const { safetyMarginPct = 10, noteTemplate = DEFAULT_NOTE_TEMPLATE, projectMdHeadLines = 40, } = options;
+    const effectiveBudget = Math.floor(budget * (1 - safetyMarginPct / 100));
+    const { instructions, roadmap, plans, projectMd: projectMdRaw = null, context: contextRaw = null, research: researchRaw = null, requirements: requirementsRaw = null, } = sections;
+    // Working mutable state
+    let projectMd = projectMdRaw;
+    let context = contextRaw;
+    let research = researchRaw;
+    let requirements = requirementsRaw;
+    let workingPlans = plans.map((p) => ({ file: p.file, content: p.content }));
+    const omitted = [];
+    let projectMdShrunk = false;
+    let planTruncationPct = 0;
+    let noteInjected = false;
+    let hardFailed = false;
+    // Minimum-set check: instructions + roadmap + 1KB per plan.
+    // NOTE_RESERVE_TOKENS is intentionally excluded here: a note is only injected
+    // when trimming actually occurs, and a prompt that fits without any trim needs
+    // no note at all. Including NOTE_RESERVE_TOKENS here would cause false hard-fails
+    // for prompts that genuinely fit the effective budget untrimmed.
+    const MIN_PLAN_BYTES = 1024;
+    const minPlanTokens = plans.reduce((sum, p) => {
+        return sum + estimateTokens(p.content.slice(0, MIN_PLAN_BYTES));
+    }, 0);
+    const minSet = estimateTokens(instructions) +
+        estimateTokens(roadmap) +
+        minPlanTokens;
+    if (minSet > effectiveBudget) {
+        return {
+            prompt: '',
+            metadata: {
+                budget,
+                effectiveBudget,
+                estimatedTokens: 0,
+                omitted: [],
+                projectMdShrunk: false,
+                planTruncationPct: 0,
+                hardFailed: true,
+                noteInjected: false,
+            },
+        };
+    }
+    // ── Budget accounting ──────────────────────────────────────────────────────
+    const TOKENS_ROADMAP_HEADER = estimateTokens('## Roadmap\n\n');
+    const TOKENS_PROJECT_HEADER = estimateTokens('## Project\n\n');
+    const TOKENS_PLANS_HEADER = estimateTokens('## Plans\n\n');
+    const TOKENS_CONTEXT_HEADER = estimateTokens('## Context\n\n');
+    const TOKENS_RESEARCH_HEADER = estimateTokens('## Research\n\n');
+    const TOKENS_REQUIREMENTS_HEADER = estimateTokens('## Requirements\n\n');
+    const TOKENS_PLAN_ITEM_HEADERS = workingPlans.reduce((sum, p) => sum + estimateTokens('### ' + p.file + '\n\n'), 0);
+    const staticBaseTokens = estimateTokens(instructions) +
+        TOKENS_ROADMAP_HEADER +
+        estimateTokens(roadmap) +
+        TOKENS_PLANS_HEADER +
+        TOKENS_PLAN_ITEM_HEADERS;
+    let projectTokens = projectMd
+        ? TOKENS_PROJECT_HEADER + estimateTokens(projectMd)
+        : 0;
+    let contextTokens = context
+        ? TOKENS_CONTEXT_HEADER + estimateTokens(context)
+        : 0;
+    let researchTokens = research
+        ? TOKENS_RESEARCH_HEADER + estimateTokens(research)
+        : 0;
+    let requirementsTokens = requirements
+        ? TOKENS_REQUIREMENTS_HEADER + estimateTokens(requirements)
+        : 0;
+    let planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
+    const getCurrentBaseTokens = () => staticBaseTokens +
+        projectTokens +
+        planContentTokens +
+        contextTokens +
+        researchTokens +
+        requirementsTokens;
+    let currentBaseTokens = getCurrentBaseTokens();
+    // Detect budget pressure: is ANY trim needed?
+    // Pressure exists when the current base tokens already exceed the effective
+    // budget. Only when pressure is real do we reserve NOTE_RESERVE_TOKENS so
+    // the note itself fits after trimming. Checking against
+    // effectiveBudget - NOTE_RESERVE_TOKENS (the old threshold) would cause
+    // spurious pressure 80 tokens early, dropping sections that fit fine.
+    const baseTokens = currentBaseTokens;
+    const budgetUnderPressure = baseTokens > effectiveBudget;
+    // Available for content (reserve note slot when under pressure)
+    const contentBudget = budgetUnderPressure
+        ? effectiveBudget - NOTE_RESERVE_TOKENS
+        : effectiveBudget;
+    // ── Trim step 1: head-shrink PROJECT.md ───────────────────────────────────
+    if (currentBaseTokens > contentBudget && projectMd) {
+        const shrunk = headShrink(projectMd, projectMdHeadLines);
+        if (shrunk !== projectMd) {
+            projectMd = shrunk;
+            projectMdShrunk = true;
+            projectTokens = TOKENS_PROJECT_HEADER + estimateTokens(projectMd);
+            currentBaseTokens = getCurrentBaseTokens();
+        }
+    }
+    // ── Trim step 2: proportional plan truncation ─────────────────────────────
+    if (currentBaseTokens > contentBudget) {
+        // Compute tokens available for plan content only
+        const overhead = staticBaseTokens +
+            projectTokens +
+            contextTokens +
+            researchTokens +
+            requirementsTokens;
+        const planBudgetTokens = contentBudget - overhead;
+        const totalPlanTokens = planContentTokens;
+        if (planBudgetTokens > 0 && planBudgetTokens < totalPlanTokens) {
+            // Proportional share per plan (at least 1KB per plan)
+            const totalOriginalChars = plans.reduce((sum, p) => sum + p.content.length, 0);
+            const totalPlanCharsBudget = planBudgetTokens * 4;
+            workingPlans = workingPlans.map((p) => {
+                const proportionalShare = totalOriginalChars > 0
+                    ? Math.floor((p.content.length / totalOriginalChars) * totalPlanCharsBudget)
+                    : 0;
+                const maxChars = Math.max(proportionalShare, MIN_PLAN_BYTES);
+                return { file: p.file, content: tailTruncate(p.content, maxChars) };
+            });
+            const newTotalChars = workingPlans.reduce((sum, p) => sum + p.content.length, 0);
+            if (totalOriginalChars > 0) {
+                planTruncationPct =
+                    ((totalOriginalChars - newTotalChars) / totalOriginalChars) * 100;
+            }
+            planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
+            currentBaseTokens = getCurrentBaseTokens();
+        }
+    }
+    // ── Trim step 3: drop context ─────────────────────────────────────────────
+    if (currentBaseTokens > contentBudget && context) {
+        context = null;
+        omitted.push('context');
+        contextTokens = 0;
+        currentBaseTokens = getCurrentBaseTokens();
+    }
+    // ── Trim step 4: drop research ────────────────────────────────────────────
+    if (currentBaseTokens > contentBudget && research) {
+        research = null;
+        omitted.push('research');
+        researchTokens = 0;
+        currentBaseTokens = getCurrentBaseTokens();
+    }
+    // ── Trim step 5: drop requirements (last resort) ──────────────────────────
+    if (currentBaseTokens > contentBudget && requirements) {
+        requirements = null;
+        omitted.push('requirements');
+        requirementsTokens = 0;
+        currentBaseTokens = getCurrentBaseTokens();
+    }
+    // ── Decide whether note is actually needed ────────────────────────────────
+    const anyTrimOccurred = omitted.length > 0 || projectMdShrunk || planTruncationPct > 0;
+    let note = null;
+    if (anyTrimOccurred) {
+        note = renderNote(noteTemplate, budget, omitted, planTruncationPct);
+        noteInjected = true;
+    }
+    // Suppress unused variable warning — currentBaseTokens is used via the
+    // closure in getCurrentBaseTokens(); the final value is not used directly.
+    void currentBaseTokens;
+    // ── Assemble ──────────────────────────────────────────────────────────────
+    const prompt = assemblePrompt({
+        instructions,
+        note,
+        roadmap,
+        projectMd,
+        plans: workingPlans,
+        context,
+        research,
+        requirements,
+    });
+    const estimatedTokens = estimateTokens(prompt);
+    if (estimatedTokens > effectiveBudget) {
+        hardFailed = true;
+        return {
+            prompt: '',
+            metadata: {
+                budget,
+                effectiveBudget,
+                estimatedTokens,
+                omitted,
+                projectMdShrunk,
+                planTruncationPct,
+                hardFailed,
+                noteInjected,
+            },
+        };
+    }
+    return {
+        prompt,
+        metadata: {
+            budget,
+            effectiveBudget,
+            estimatedTokens,
+            omitted,
+            projectMdShrunk,
+            planTruncationPct,
+            hardFailed,
+            noteInjected,
+        },
+    };
+}

package/gsd-core/bin/lib/research-provider.cjs

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Research Provider Module
+ *
+ * Encodes the Balanced-set provider decision: PROVIDER_WATERFALL constant,
+ * classifyConfidence, providerAvailability, and planResearch (with injectable
+ * store for testability).
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+// ---------------------------------------------------------------------------
+// Cycle 1 / Cycle 6: PROVIDER_WATERFALL (Balanced-set decision)
+// firecrawl appears ONLY in scrape — demoted to known-URL scrape, NOT in docs/web
+// ---------------------------------------------------------------------------
+const PROVIDER_WATERFALL = {
+    docs: ['context7', 'ref', 'jina', 'websearch'],
+    web: ['exa', 'tavily', 'perplexity', 'brave', 'websearch'],
+    scrape: ['firecrawl', 'jina'],
+};
+function authorityOf(provider) {
+    switch (provider) {
+        case 'context7':
+        case 'ref':
+            return 'official';
+        case 'jina':
+        case 'firecrawl':
+            return 'scrape';
+        case 'exa':
+        case 'tavily':
+        case 'perplexity':
+        case 'brave':
+        case 'websearch':
+            return 'web';
+        default:
+            return 'none';
+    }
+}
+function normalizeLegitimacyVerdict(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const upper = raw.toUpperCase();
+    if (upper === 'OK' || upper === 'SUS' || upper === 'SLOP')
+        return upper;
+    return null;
+}
+function classifyConfidence(input) {
+    try {
+        const { provider, verifiedAgainstOfficial, legitimacyVerdict } = input;
+        const authority = authorityOf(provider);
+        const verdict = normalizeLegitimacyVerdict(legitimacyVerdict);
+        const groundTruth = verdict === 'OK';
+        // SLOP caps everything — checked first
+        if (verdict === 'SLOP')
+            return 'LOW';
+        // Ground-truth corroboration + known authority → HIGH
+        if (groundTruth && authority !== 'none')
+            return 'HIGH';
+        // Official or scrape provider (authority alone) → MEDIUM
+        if (authority === 'official' || authority === 'scrape')
+            return 'MEDIUM';
+        // Ground-truth but unknown provider → MEDIUM
+        if (groundTruth)
+            return 'MEDIUM';
+        // Web provider with self-reported verification → MEDIUM
+        if (authority === 'web' && verifiedAgainstOfficial === true)
+            return 'MEDIUM';
+        return 'LOW';
+    }
+    catch {
+        return 'LOW';
+    }
+}
+// ---------------------------------------------------------------------------
+// Cycle 5: providerAvailability
+// ---------------------------------------------------------------------------
+function providerAvailability(config) {
+    const cfg = config ?? {};
+    return {
+        context7: true,
+        jina: cfg.jina !== undefined ? Boolean(cfg.jina) : true,
+        websearch: true,
+        exa: Boolean(cfg.exa_search),
+        tavily: Boolean(cfg.tavily_search),
+        brave: Boolean(cfg.brave_search),
+        firecrawl: Boolean(cfg.firecrawl),
+        ref: Boolean(cfg.ref_search),
+        perplexity: Boolean(cfg.perplexity),
+    };
+}
+// ---------------------------------------------------------------------------
+// Lazy-load default store (avoids circular require at module eval time)
+// ---------------------------------------------------------------------------
+let _defaultStore;
+function getDefaultStore() {
+    if (!_defaultStore) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy default store; tests inject their own
+        _defaultStore = require('./research-store.cjs');
+    }
+    return _defaultStore;
+}
+// ---------------------------------------------------------------------------
+// Cycle 1–3, 5, 7: planResearch
+// ---------------------------------------------------------------------------
+function planResearch(options) {
+    const { questions, ecosystem = '', cwd, config, clock = Date, homeDir, store = getDefaultStore(), } = options;
+    const availability = providerAvailability(config);
+    const items = questions.flatMap((q) => {
+        const { text, kind, library, version } = q;
+        // Skip questions without a non-empty string text — emitting an item with
+        // question:undefined / fetch.query:undefined would produce corrupt output.
+        if (typeof text !== 'string' || text.length === 0) {
+            return [];
+        }
+        const key = store.researchKey({ ecosystem, library, version, query: text, kind });
+        const res = store.getResearch(cwd, key, { clock, homeDir, kind });
+        // Fresh cache hit — no fetch needed
+        if (res.hit && !res.stale) {
+            return { question: text, key, cache: { hit: true, stale: false } };
+        }
+        // Determine which waterfall to use
+        const waterfall = PROVIDER_WATERFALL[kind] ?? PROVIDER_WATERFALL.web;
+        // Pick first available provider
+        const provider = waterfall.find((p) => availability[p] === true) ?? 'websearch';
+        const item = {
+            question: text,
+            key,
+            fetch: { provider, query: text },
+        };
+        // Stale hit: include cache info
+        if (res.hit) {
+            item.cache = { hit: true, stale: true };
+        }
+        return item;
+    });
+    return { items };
+}
+module.exports = { PROVIDER_WATERFALL, classifyConfidence, providerAvailability, planResearch };

package/gsd-core/bin/lib/research-store.cjs

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Research Store Module
+ *
+ * Provides deterministic cache key generation, TTL policy, path resolution,
+ * and JSON-backed put/get operations for research entries.
+ *
+ * ADR-457 build-at-publish: authored as TypeScript .cts → emits .cjs via tsc.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DAY_MS = 86_400_000;
+// ---------------------------------------------------------------------------
+// researchKey
+// ---------------------------------------------------------------------------
+function normalize(x) {
+    if (x === null || x === undefined)
+        return '';
+    if (typeof x === 'object')
+        return JSON.stringify(x).trim().toLowerCase();
+    // After excluding null, undefined, and object, x can only be a primitive —
+    // cast through number | string | boolean to avoid no-base-to-string on unknown.
+    return `${x}`.trim().toLowerCase();
+}
+function researchKey(input) {
+    const parts = {
+        ecosystem: normalize(input.ecosystem),
+        library: normalize(input.library),
+        version: normalize(input.version),
+        query: normalize(input.query),
+        kind: normalize(input.kind),
+    };
+    const serialized = JSON.stringify(parts);
+    return node_crypto_1.default.createHash('sha256').update(serialized).digest('hex');
+}
+// ---------------------------------------------------------------------------
+// ttlForSource
+// ---------------------------------------------------------------------------
+function ttlForSource(source, confidence) {
+    if (source === 'curated' && confidence === 'HIGH')
+        return 30 * DAY_MS;
+    if (source === 'curated' && confidence === 'MEDIUM')
+        return 7 * DAY_MS;
+    return DAY_MS;
+}
+// ---------------------------------------------------------------------------
+// tierForSource / resolveStorePath
+// ---------------------------------------------------------------------------
+const CURATED_SOURCES = new Set(['curated']);
+function tierForSource(source) {
+    return CURATED_SOURCES.has(source) ? 'user' : 'project';
+}
+function resolveStorePath(cwd, source, { homeDir = node_os_1.default.homedir() } = {}) {
+    if (tierForSource(source) === 'user') {
+        return node_path_1.default.join(homeDir, '.gsd', 'research-cache');
+    }
+    return node_path_1.default.join(cwd, '.planning', 'research', '.cache');
+}
+// ---------------------------------------------------------------------------
+// isValidResearchKey
+// ---------------------------------------------------------------------------
+/**
+ * Returns true iff key is a valid 64-character lowercase hexadecimal SHA-256
+ * string (the exact shape produced by researchKey).  Any other shape —
+ * including path-traversal sequences — is rejected.
+ */
+function isValidResearchKey(key) {
+    return typeof key === 'string' && /^[0-9a-f]{64}$/.test(key);
+}
+// ---------------------------------------------------------------------------
+// putResearch
+// ---------------------------------------------------------------------------
+function putResearch(cwd, key, payload, { clock = Date, homeDir = node_os_1.default.homedir() } = {}) {
+    // Defense-in-depth: reject any key that is not a 64-char sha256 hex string.
+    if (!isValidResearchKey(key)) {
+        throw new Error('invalid research key');
+    }
+    const { content, source, provider, confidence, kind, version } = payload;
+    let ttl = ttlForSource(source, confidence);
+    // Cap TTL when version is blank/missing — a versionless curated entry must not
+    // get the long 30-day window since we can't know if it's still current.
+    if (!version) {
+        ttl = Math.min(ttl, DAY_MS);
+    }
+    const fetched_at = new Date(clock.now()).toISOString();
+    const entry = { content, source, provider, confidence, fetched_at, ttl, kind };
+    const dir = resolveStorePath(cwd, source, { homeDir });
+    // Belt-and-suspenders: ensure the resolved file path stays inside the store dir.
+    const resolvedDir = node_path_1.default.resolve(dir);
+    const filePath = node_path_1.default.join(dir, `${key}.json`);
+    const resolvedFile = node_path_1.default.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedDir + node_path_1.default.sep)) {
+        throw new Error('invalid research key');
+    }
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, JSON.stringify(entry));
+    return entry;
+}
+// ---------------------------------------------------------------------------
+// getResearch
+// ---------------------------------------------------------------------------
+function getResearch(cwd, key, { clock = Date, homeDir = node_os_1.default.homedir() } = {}) {
+    // Defense-in-depth: reject any key that is not a 64-char sha256 hex string.
+    if (!isValidResearchKey(key)) {
+        return { hit: false, stale: false, entry: null };
+    }
+    try {
+        // Search both physical tiers: user (curated) and project (web/etc.)
+        const userDir = node_path_1.default.join(homeDir, '.gsd', 'research-cache');
+        const projectDir = node_path_1.default.join(cwd, '.planning', 'research', '.cache');
+        const tierDirs = [userDir, projectDir];
+        const candidates = [];
+        for (const dir of tierDirs) {
+            const resolvedDir = node_path_1.default.resolve(dir);
+            const filePath = node_path_1.default.join(dir, `${key}.json`);
+            // Belt-and-suspenders: ensure path stays inside tier dir
+            if (!node_path_1.default.resolve(filePath).startsWith(resolvedDir + node_path_1.default.sep))
+                continue;
+            if (!node_fs_1.default.existsSync(filePath))
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf8'));
+            }
+            catch {
+                // Corrupt file in this tier — skip it
+                continue;
+            }
+            // Finding 3: validate entry metadata shape before accepting as a candidate.
+            // An entry with missing/invalid fetched_at or ttl must be treated as a miss.
+            const parsedFetchedAt = Date.parse(entry.fetched_at);
+            if (!Number.isFinite(parsedFetchedAt))
+                continue;
+            if (typeof entry.ttl !== 'number' ||
+                !Number.isFinite(entry.ttl) ||
+                entry.ttl <= 0)
+                continue;
+            const age = clock.now() - parsedFetchedAt;
+            const stale = age > entry.ttl;
+            candidates.push({ entry, stale, age });
+        }
+        if (candidates.length === 0) {
+            return { hit: false, stale: false, entry: null };
+        }
+        // Prefer: non-stale over stale; among same-staleness, lowest age (most recent)
+        candidates.sort((a, b) => {
+            if (a.stale !== b.stale)
+                return a.stale ? 1 : -1; // non-stale first
+            return a.age - b.age; // lower age (more recent) first
+        });
+        const best = candidates[0];
+        return { hit: true, stale: best.stale, entry: best.entry };
+    }
+    catch {
+        return { hit: false, stale: false, entry: null };
+    }
+}
+module.exports = { isValidResearchKey, researchKey, ttlForSource, tierForSource, resolveStorePath, putResearch, getResearch };