scientify 1.10.3 → 1.12.0

package/dist/src/knowledge-state/store.js

@@ -0,0 +1,978 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { dayKeyFromTimestamp, renderDailyChangesMarkdown, renderExplorationLogMarkdown, renderHypothesisMarkdown, renderIngestLogMarkdown, renderKnowledgeIndexMarkdown, renderPaperNoteHeaderMarkdown, renderPaperNoteRunMarkdown, renderTopicUpdateMarkdown, slugifyTopic, } from "./render.js";
+import { resolveProjectContext } from "./project.js";
+const STATE_VERSION = 1;
+const MAX_RECENT_RUN_IDS = 200;
+const MAX_RECENT_HYPOTHESES = 50;
+const MAX_RECENT_CHANGE_STATS = 30;
+const MAX_LAST_TRACE = 20;
+const MAX_RECENT_PAPERS = 50;
+const MAX_PAPER_NOTES = 800;
+const MIN_CORE_FULLTEXT_COVERAGE = 0.8;
+const MIN_EVIDENCE_BINDING_RATE = 0.9;
+const MAX_CITATION_ERROR_RATE = 0.02;
+function defaultQualityGateState() {
+    return {
+        passed: false,
+        fullTextCoveragePct: 0,
+        evidenceBindingRatePct: 0,
+        citationErrorRatePct: 0,
+        reasons: ["quality gate not evaluated"],
+    };
+}
+function normalizeText(raw) {
+    return raw.trim().replace(/\s+/g, " ");
+}
+function sanitizeId(raw) {
+    return normalizeText(raw)
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+function normalizeScope(raw) {
+    const trimmed = normalizeText(raw).toLowerCase();
+    if (!trimmed)
+        return "global";
+    const parts = trimmed.split(":");
+    if (parts.length === 1)
+        return sanitizeId(parts[0]) || "global";
+    return `${sanitizeId(parts[0])}:${sanitizeId(parts.slice(1).join(":"))}`;
+}
+function buildRunFingerprint(args) {
+    const digest = createHash("sha1")
+        .update(args.scope)
+        .update("\n")
+        .update(args.topic)
+        .update("\n")
+        .update(args.status)
+        .update("\n")
+        .update(args.day)
+        .update("\n")
+        .update(args.paperIds.sort().join("|"))
+        .update("\n")
+        .update(args.note ?? "")
+        .digest("hex");
+    return `fp-${digest.slice(0, 20)}`;
+}
+function getKnowledgeStateRoot(projectPath) {
+    return path.join(projectPath, "knowledge_state");
+}
+function getStatePath(projectPath) {
+    return path.join(getKnowledgeStateRoot(projectPath), "state.json");
+}
+function getEventsPath(projectPath) {
+    return path.join(getKnowledgeStateRoot(projectPath), "events.jsonl");
+}
+function getLockPath(projectPath) {
+    return path.join(getKnowledgeStateRoot(projectPath), ".lock");
+}
+function buildDefaultState() {
+    return {
+        version: STATE_VERSION,
+        updatedAtMs: Date.now(),
+        streams: {},
+    };
+}
+async function ensureLayout(projectPath) {
+    const root = getKnowledgeStateRoot(projectPath);
+    await mkdir(root, { recursive: true });
+    await mkdir(path.join(root, "knowledge"), { recursive: true });
+    await mkdir(path.join(root, "paper_notes"), { recursive: true });
+    await mkdir(path.join(root, "daily_changes"), { recursive: true });
+    await mkdir(path.join(root, "hypotheses"), { recursive: true });
+    await mkdir(path.join(root, "logs"), { recursive: true });
+}
+async function loadState(projectPath) {
+    const file = getStatePath(projectPath);
+    if (!existsSync(file))
+        return buildDefaultState();
+    try {
+        const raw = await readFile(file, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== STATE_VERSION || !parsed.streams || typeof parsed.streams !== "object") {
+            return buildDefaultState();
+        }
+        const streams = {};
+        for (const [key, rawStream] of Object.entries(parsed.streams)) {
+            if (!rawStream || typeof rawStream !== "object")
+                continue;
+            const topicKey = rawStream.topicKey && normalizeText(rawStream.topicKey) ? normalizeText(rawStream.topicKey) : key;
+            streams[key] = {
+                scope: normalizeScope(rawStream.scope ?? "global"),
+                topic: normalizeText(rawStream.topic ?? "topic"),
+                topicKey,
+                projectId: sanitizeId(rawStream.projectId ?? "auto-topic-global-000000") || "auto-topic-global-000000",
+                totalRuns: typeof rawStream.totalRuns === "number" ? Math.max(0, Math.floor(rawStream.totalRuns)) : 0,
+                totalHypotheses: typeof rawStream.totalHypotheses === "number" ? Math.max(0, Math.floor(rawStream.totalHypotheses)) : 0,
+                knowledgeTopics: Array.isArray(rawStream.knowledgeTopics)
+                    ? rawStream.knowledgeTopics.filter((item) => typeof item === "string").map((item) => normalizeText(item))
+                    : [],
+                paperNotes: Array.isArray(rawStream.paperNotes)
+                    ? rawStream.paperNotes.filter((item) => typeof item === "string").map((item) => normalizeText(item))
+                    : [],
+                recentFullTextReadCount: typeof rawStream.recentFullTextReadCount === "number"
+                    ? Math.max(0, Math.floor(rawStream.recentFullTextReadCount))
+                    : 0,
+                recentNotFullTextReadCount: typeof rawStream.recentNotFullTextReadCount === "number"
+                    ? Math.max(0, Math.floor(rawStream.recentNotFullTextReadCount))
+                    : 0,
+                lastQualityGate: rawStream.lastQualityGate &&
+                    typeof rawStream.lastQualityGate === "object" &&
+                    !Array.isArray(rawStream.lastQualityGate)
+                    ? {
+                        passed: rawStream.lastQualityGate.passed === true,
+                        fullTextCoveragePct: typeof rawStream.lastQualityGate.fullTextCoveragePct === "number" &&
+                            Number.isFinite(rawStream.lastQualityGate.fullTextCoveragePct)
+                            ? Number(rawStream.lastQualityGate.fullTextCoveragePct.toFixed(2))
+                            : 0,
+                        evidenceBindingRatePct: typeof rawStream.lastQualityGate.evidenceBindingRatePct === "number" &&
+                            Number.isFinite(rawStream.lastQualityGate.evidenceBindingRatePct)
+                            ? Number(rawStream.lastQualityGate.evidenceBindingRatePct.toFixed(2))
+                            : 0,
+                        citationErrorRatePct: typeof rawStream.lastQualityGate.citationErrorRatePct === "number" &&
+                            Number.isFinite(rawStream.lastQualityGate.citationErrorRatePct)
+                            ? Number(rawStream.lastQualityGate.citationErrorRatePct.toFixed(2))
+                            : 0,
+                        reasons: Array.isArray(rawStream.lastQualityGate.reasons)
+                            ? rawStream.lastQualityGate.reasons
+                                .filter((item) => typeof item === "string")
+                                .map((item) => normalizeText(item))
+                                .filter((item) => item.length > 0)
+                            : [],
+                    }
+                    : defaultQualityGateState(),
+                lastUnreadCorePaperIds: Array.isArray(rawStream.lastUnreadCorePaperIds)
+                    ? rawStream.lastUnreadCorePaperIds
+                        .filter((item) => typeof item === "string")
+                        .map((item) => normalizeText(item))
+                        .filter((item) => item.length > 0)
+                    : [],
+                recentPapers: Array.isArray(rawStream.recentPapers)
+                    ? rawStream.recentPapers
+                        .filter((item) => !!item && typeof item === "object")
+                        .map(normalizePaper)
+                    : [],
+                ...(typeof rawStream.lastRunAtMs === "number" ? { lastRunAtMs: rawStream.lastRunAtMs } : {}),
+                ...(rawStream.lastStatus ? { lastStatus: normalizeText(rawStream.lastStatus) } : {}),
+                recentRunIds: Array.isArray(rawStream.recentRunIds)
+                    ? rawStream.recentRunIds.filter((item) => typeof item === "string").map((item) => normalizeText(item))
+                    : [],
+                recentHypothesisIds: Array.isArray(rawStream.recentHypothesisIds)
+                    ? rawStream.recentHypothesisIds
+                        .filter((item) => typeof item === "string")
+                        .map((item) => normalizeText(item))
+                    : [],
+                recentHypotheses: Array.isArray(rawStream.recentHypotheses)
+                    ? rawStream.recentHypotheses.filter((item) => !!item && typeof item === "object")
+                    : [],
+                recentChangeStats: Array.isArray(rawStream.recentChangeStats)
+                    ? rawStream.recentChangeStats.filter((item) => !!item && typeof item === "object")
+                    : [],
+                lastExplorationTrace: Array.isArray(rawStream.lastExplorationTrace)
+                    ? rawStream.lastExplorationTrace
+                        .filter((item) => !!item && typeof item === "object")
+                        .map(normalizeTrace)
+                        .filter((item) => Boolean(item))
+                    : [],
+            };
+        }
+        return {
+            version: STATE_VERSION,
+            updatedAtMs: typeof parsed.updatedAtMs === "number" ? parsed.updatedAtMs : Date.now(),
+            streams,
+        };
+    }
+    catch {
+        return buildDefaultState();
+    }
+}
+async function saveStateAtomic(projectPath, state) {
+    const file = getStatePath(projectPath);
+    const tmp = `${file}.tmp`;
+    state.updatedAtMs = Date.now();
+    await writeFile(tmp, JSON.stringify(state, null, 2), "utf-8");
+    await rename(tmp, file);
+}
+async function appendEvent(projectPath, event) {
+    await appendFile(getEventsPath(projectPath), `${JSON.stringify(event)}\n`, "utf-8");
+}
+async function appendMarkdown(filePath, block) {
+    await appendFile(filePath, `${block}\n`, "utf-8");
+}
+function normalizeStringArray(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const values = raw
+        .filter((item) => typeof item === "string")
+        .map((item) => normalizeText(item))
+        .filter((item) => item.length > 0);
+    return values.length > 0 ? values : undefined;
+}
+function normalizeEvidenceAnchors(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const anchors = raw
+        .filter((item) => !!item && typeof item === "object")
+        .map((item) => {
+        const claim = normalizeText(item.claim ?? "");
+        if (!claim)
+            return undefined;
+        return {
+            ...(item.section ? { section: normalizeText(item.section) } : {}),
+            ...(item.locator ? { locator: normalizeText(item.locator) } : {}),
+            claim,
+            ...(item.quote ? { quote: normalizeText(item.quote) } : {}),
+        };
+    })
+        .filter((item) => Boolean(item));
+    return anchors.length > 0 ? anchors : undefined;
+}
+function toPaperNoteSlug(paper) {
+    const primary = paper.id ?? paper.url ?? paper.title ?? "";
+    const raw = normalizeText(primary);
+    const base = sanitizeId(raw.replace(/[:/.]+/g, "-")).slice(0, 72);
+    const digest = createHash("sha1")
+        .update([paper.id ?? "", paper.url ?? "", paper.title ?? ""].join("\n"))
+        .digest("hex")
+        .slice(0, 8);
+    return `${base || "paper"}-${digest}`;
+}
+function normalizePaper(input) {
+    const evidenceIds = Array.isArray(input.evidenceIds)
+        ? input.evidenceIds.map((id) => normalizeText(id)).filter((id) => id.length > 0)
+        : undefined;
+    const keyEvidenceSpans = normalizeStringArray(input.keyEvidenceSpans);
+    const subdomains = normalizeStringArray(input.subdomains);
+    const crossDomainLinks = normalizeStringArray(input.crossDomainLinks);
+    const keyContributions = normalizeStringArray(input.keyContributions);
+    const practicalInsights = normalizeStringArray(input.practicalInsights);
+    const mustUnderstandPoints = normalizeStringArray(input.mustUnderstandPoints);
+    const limitations = normalizeStringArray(input.limitations);
+    const evidenceAnchors = normalizeEvidenceAnchors(input.evidenceAnchors);
+    const readStatusRaw = input.readStatus?.trim().toLowerCase();
+    const readStatus = readStatusRaw && ["fulltext", "partial", "metadata", "unread"].includes(readStatusRaw)
+        ? readStatusRaw
+        : undefined;
+    const fullTextRead = typeof input.fullTextRead === "boolean"
+        ? input.fullTextRead
+        : readStatus === "fulltext"
+            ? true
+            : readStatus
+                ? false
+                : undefined;
+    const unreadReason = input.unreadReason ? normalizeText(input.unreadReason) : undefined;
+    return {
+        ...(input.id ? { id: normalizeText(input.id) } : {}),
+        ...(input.title ? { title: normalizeText(input.title) } : {}),
+        ...(input.url ? { url: normalizeText(input.url) } : {}),
+        ...(input.source ? { source: normalizeText(input.source) } : {}),
+        ...(input.publishedAt ? { publishedAt: normalizeText(input.publishedAt) } : {}),
+        ...(typeof input.score === "number" && Number.isFinite(input.score)
+            ? { score: Number(input.score.toFixed(2)) }
+            : {}),
+        ...(input.reason ? { reason: normalizeText(input.reason) } : {}),
+        ...(input.summary ? { summary: normalizeText(input.summary) } : {}),
+        ...(evidenceIds && evidenceIds.length > 0 ? { evidenceIds } : {}),
+        ...(typeof fullTextRead === "boolean" ? { fullTextRead } : {}),
+        ...(readStatus ? { readStatus } : {}),
+        ...(input.fullTextSource ? { fullTextSource: normalizeText(input.fullTextSource) } : {}),
+        ...(input.fullTextRef ? { fullTextRef: normalizeText(input.fullTextRef) } : {}),
+        ...(unreadReason ? { unreadReason } : {}),
+        ...(keyEvidenceSpans && keyEvidenceSpans.length > 0 ? { keyEvidenceSpans } : {}),
+        ...(input.domain ? { domain: normalizeText(input.domain) } : {}),
+        ...(subdomains ? { subdomains } : {}),
+        ...(crossDomainLinks ? { crossDomainLinks } : {}),
+        ...(input.researchGoal ? { researchGoal: normalizeText(input.researchGoal) } : {}),
+        ...(input.approach ? { approach: normalizeText(input.approach) } : {}),
+        ...(input.methodologyDesign ? { methodologyDesign: normalizeText(input.methodologyDesign) } : {}),
+        ...(keyContributions ? { keyContributions } : {}),
+        ...(practicalInsights ? { practicalInsights } : {}),
+        ...(mustUnderstandPoints ? { mustUnderstandPoints } : {}),
+        ...(limitations ? { limitations } : {}),
+        ...(evidenceAnchors ? { evidenceAnchors } : {}),
+    };
+}
+function normalizeTrace(input) {
+    const query = normalizeText(input.query ?? "");
+    if (!query)
+        return undefined;
+    const filteredOutReasons = Array.isArray(input.filteredOutReasons)
+        ? input.filteredOutReasons.map((item) => normalizeText(item)).filter((item) => item.length > 0)
+        : undefined;
+    return {
+        query,
+        ...(input.reason ? { reason: normalizeText(input.reason) } : {}),
+        ...(input.source ? { source: normalizeText(input.source) } : {}),
+        ...(typeof input.candidates === "number" && Number.isFinite(input.candidates)
+            ? { candidates: Math.max(0, Math.floor(input.candidates)) }
+            : {}),
+        ...(typeof input.filteredTo === "number" && Number.isFinite(input.filteredTo)
+            ? { filteredTo: Math.max(0, Math.floor(input.filteredTo)) }
+            : {}),
+        ...(filteredOutReasons && filteredOutReasons.length > 0 ? { filteredOutReasons } : {}),
+        ...(typeof input.resultCount === "number" && Number.isFinite(input.resultCount)
+            ? { resultCount: Math.max(0, Math.floor(input.resultCount)) }
+            : {}),
+    };
+}
+function paperIdentity(input) {
+    const id = input.id ? normalizeText(input.id).toLowerCase() : "";
+    if (id)
+        return `id:${id}`;
+    const url = input.url ? normalizeText(input.url).toLowerCase() : "";
+    if (url)
+        return `url:${url}`;
+    const title = input.title ? normalizeText(input.title).toLowerCase() : "";
+    if (title)
+        return `title:${title}`;
+    return "";
+}
+function mergePapers(primary, secondary) {
+    const byId = new Map();
+    const upsert = (paper) => {
+        const normalized = normalizePaper(paper);
+        const key = paperIdentity(normalized);
+        if (!key)
+            return;
+        const existing = byId.get(key);
+        if (!existing) {
+            byId.set(key, normalized);
+            return;
+        }
+        byId.set(key, {
+            ...existing,
+            ...normalized,
+            evidenceIds: normalized.evidenceIds && normalized.evidenceIds.length > 0
+                ? [...new Set([...(existing.evidenceIds ?? []), ...normalized.evidenceIds])]
+                : existing.evidenceIds,
+            keyEvidenceSpans: normalized.keyEvidenceSpans && normalized.keyEvidenceSpans.length > 0
+                ? [...new Set([...(existing.keyEvidenceSpans ?? []), ...normalized.keyEvidenceSpans])]
+                : existing.keyEvidenceSpans,
+        });
+    };
+    for (const item of primary)
+        upsert(item);
+    for (const item of secondary)
+        upsert(item);
+    return [...byId.values()];
+}
+function withReadMark(paper, unreadFallback) {
+    const normalized = normalizePaper(paper);
+    const { unreadReason: existingUnreadReason, ...rest } = normalized;
+    const readStatus = normalized.readStatus ?? (normalized.fullTextRead ? "fulltext" : "metadata");
+    const fullTextRead = typeof normalized.fullTextRead === "boolean" ? normalized.fullTextRead : readStatus === "fulltext";
+    const unreadReason = fullTextRead || readStatus === "fulltext"
+        ? undefined
+        : existingUnreadReason?.trim()
+            ? existingUnreadReason.trim()
+            : unreadFallback;
+    return {
+        ...rest,
+        readStatus,
+        fullTextRead,
+        ...(unreadReason ? { unreadReason } : {}),
+    };
+}
+function countFullTextStats(papers) {
+    let fullTextReadCount = 0;
+    let notFullTextReadCount = 0;
+    for (const paper of papers) {
+        if (paper.fullTextRead === true || paper.readStatus === "fulltext")
+            fullTextReadCount += 1;
+        else
+            notFullTextReadCount += 1;
+    }
+    return { fullTextReadCount, notFullTextReadCount };
+}
+function hasStructuredProfile(paper) {
+    return Boolean((paper.domain && paper.domain.trim()) ||
+        (paper.subdomains && paper.subdomains.length > 0) ||
+        (paper.crossDomainLinks && paper.crossDomainLinks.length > 0) ||
+        (paper.researchGoal && paper.researchGoal.trim()) ||
+        (paper.approach && paper.approach.trim()) ||
+        (paper.methodologyDesign && paper.methodologyDesign.trim()) ||
+        (paper.keyContributions && paper.keyContributions.length > 0) ||
+        (paper.practicalInsights && paper.practicalInsights.length > 0) ||
+        (paper.mustUnderstandPoints && paper.mustUnderstandPoints.length > 0) ||
+        (paper.limitations && paper.limitations.length > 0) ||
+        (paper.evidenceAnchors && paper.evidenceAnchors.length > 0));
+}
+function isFullTextRead(paper) {
+    return paper.fullTextRead === true || paper.readStatus === "fulltext";
+}
+function normalizedCitationToken(raw) {
+    return normalizeText(raw).toLowerCase();
+}
+function isStrictEvidenceAnchor(anchor) {
+    return Boolean(anchor.section?.trim() && anchor.locator?.trim() && anchor.quote?.trim());
+}
+function hasStrictEvidenceAnchor(paper) {
+    const anchors = paper.evidenceAnchors ?? [];
+    return anchors.some((anchor) => isStrictEvidenceAnchor(anchor));
+}
+function buildPaperLookup(papers) {
+    const lookup = new Map();
+    for (const paper of papers) {
+        const candidates = [paper.id, paper.url, paper.title]
+            .filter((item) => typeof item === "string")
+            .map((item) => normalizedCitationToken(item));
+        for (const key of candidates) {
+            if (!key)
+                continue;
+            if (!lookup.has(key))
+                lookup.set(key, paper);
+        }
+    }
+    return lookup;
+}
+function dedupeText(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = normalizedCitationToken(item);
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+function applyQualityGates(args) {
+    const corePapers = args.corePapers;
+    const coreCount = corePapers.length;
+    const fullTextCoreCount = corePapers.filter((paper) => isFullTextRead(paper)).length;
+    const fullTextCoverage = coreCount > 0 ? fullTextCoreCount / coreCount : 0;
+    const fullTextCoveragePct = Number((fullTextCoverage * 100).toFixed(2));
+    const unreadCorePaperIds = dedupeText(corePapers
+        .filter((paper) => !isFullTextRead(paper))
+        .map((paper) => paper.id?.trim() || paper.url?.trim() || paper.title?.trim() || "unknown-paper")).slice(0, 50);
+    const paperLookup = buildPaperLookup(args.allRunPapers);
+    const strictAnchorByKey = new Map();
+    for (const [key, paper] of paperLookup.entries()) {
+        strictAnchorByKey.set(key, hasStrictEvidenceAnchor(paper));
+    }
+    const conclusionEvidenceLists = [];
+    for (const change of args.knowledgeChanges) {
+        conclusionEvidenceLists.push(change.evidenceIds ?? []);
+    }
+    for (const update of args.knowledgeUpdates) {
+        conclusionEvidenceLists.push(update.evidenceIds ?? []);
+    }
+    let boundConclusions = 0;
+    for (const evidenceIds of conclusionEvidenceLists) {
+        const normalizedIds = evidenceIds.map((id) => normalizedCitationToken(id)).filter((id) => id.length > 0);
+        if (normalizedIds.length === 0)
+            continue;
+        let allResolvable = true;
+        let hasStrictAnchor = false;
+        for (const id of normalizedIds) {
+            const resolved = paperLookup.get(id);
+            if (!resolved) {
+                allResolvable = false;
+                continue;
+            }
+            if (strictAnchorByKey.get(id))
+                hasStrictAnchor = true;
+            else if (hasStrictEvidenceAnchor(resolved))
+                hasStrictAnchor = true;
+        }
+        if (allResolvable && hasStrictAnchor)
+            boundConclusions += 1;
+    }
+    const conclusionCount = conclusionEvidenceLists.length;
+    const evidenceBindingRate = conclusionCount > 0 ? boundConclusions / conclusionCount : 1;
+    const evidenceBindingRatePct = Number((evidenceBindingRate * 100).toFixed(2));
+    const citationIds = [];
+    for (const change of args.knowledgeChanges)
+        citationIds.push(...(change.evidenceIds ?? []));
+    for (const update of args.knowledgeUpdates)
+        citationIds.push(...(update.evidenceIds ?? []));
+    for (const hypothesis of args.hypotheses)
+        citationIds.push(...(hypothesis.evidenceIds ?? []));
+    const normalizedCitationIds = citationIds.map((id) => normalizedCitationToken(id)).filter((id) => id.length > 0);
+    let citationErrors = 0;
+    for (const id of normalizedCitationIds) {
+        if (!paperLookup.has(id))
+            citationErrors += 1;
+    }
+    const citationErrorRate = normalizedCitationIds.length > 0 ? citationErrors / normalizedCitationIds.length : 0;
+    const citationErrorRatePct = Number((citationErrorRate * 100).toFixed(2));
+    let downgradedHighConfidenceCount = 0;
+    for (const update of args.knowledgeUpdates) {
+        if (update.confidence !== "high")
+            continue;
+        const refs = (update.evidenceIds ?? []).map((id) => normalizedCitationToken(id)).filter((id) => id.length > 0);
+        let canKeepHigh = refs.length > 0;
+        if (canKeepHigh) {
+            for (const ref of refs) {
+                const paper = paperLookup.get(ref);
+                if (!paper || !isFullTextRead(paper)) {
+                    canKeepHigh = false;
+                    break;
+                }
+            }
+        }
+        if (!canKeepHigh) {
+            update.confidence = "medium";
+            downgradedHighConfidenceCount += 1;
+        }
+    }
+    const reasons = [];
+    if (fullTextCoverage < MIN_CORE_FULLTEXT_COVERAGE) {
+        reasons.push(`core_fulltext_coverage_below_threshold(${fullTextCoveragePct}% < ${Number((MIN_CORE_FULLTEXT_COVERAGE * 100).toFixed(0))}%)`);
+    }
+    if (evidenceBindingRate < MIN_EVIDENCE_BINDING_RATE) {
+        reasons.push(`evidence_binding_rate_below_threshold(${evidenceBindingRatePct}% < ${Number((MIN_EVIDENCE_BINDING_RATE * 100).toFixed(0))}%)`);
+    }
+    if (citationErrorRate >= MAX_CITATION_ERROR_RATE) {
+        reasons.push(`citation_error_rate_above_threshold(${citationErrorRatePct}% >= ${Number((MAX_CITATION_ERROR_RATE * 100).toFixed(0))}%)`);
+    }
+    if (downgradedHighConfidenceCount > 0) {
+        reasons.push(`high_confidence_downgraded(${downgradedHighConfidenceCount})`);
+    }
+    return {
+        qualityGate: {
+            passed: reasons.length === 0,
+            fullTextCoveragePct,
+            evidenceBindingRatePct,
+            citationErrorRatePct,
+            reasons,
+        },
+        unreadCorePaperIds,
+        downgradedHighConfidenceCount,
+    };
+}
+function normalizeChange(input) {
+    const statement = normalizeText(input.statement ?? "");
+    if (!statement)
+        return undefined;
+    const type = ["NEW", "CONFIRM", "REVISE", "BRIDGE"].includes(input.type) ? input.type : "NEW";
+    const evidenceIds = Array.isArray(input.evidenceIds)
+        ? input.evidenceIds.map((id) => normalizeText(id)).filter((id) => id.length > 0)
+        : undefined;
+    return {
+        type,
+        statement,
+        ...(evidenceIds && evidenceIds.length > 0 ? { evidenceIds } : {}),
+        ...(input.topic ? { topic: normalizeText(input.topic) } : {}),
+    };
+}
+function normalizeUpdate(input) {
+    const topic = normalizeText(input.topic ?? "");
+    const content = normalizeText(input.content ?? "");
+    if (!topic || !content)
+        return undefined;
+    const op = ["append", "revise", "confirm", "bridge"].includes(input.op) ? input.op : "append";
+    const evidenceIds = Array.isArray(input.evidenceIds)
+        ? input.evidenceIds.map((id) => normalizeText(id)).filter((id) => id.length > 0)
+        : undefined;
+    const confidence = input.confidence && ["low", "medium", "high"].includes(input.confidence) ? input.confidence : undefined;
+    return {
+        topic,
+        op,
+        content,
+        ...(confidence ? { confidence } : {}),
+        ...(evidenceIds && evidenceIds.length > 0 ? { evidenceIds } : {}),
+    };
+}
+function normalizeHypothesis(input) {
+    const statement = normalizeText(input.statement ?? "");
+    if (!statement)
+        return undefined;
+    const trigger = ["GAP", "BRIDGE", "TREND", "CONTRADICTION"].includes(input.trigger)
+        ? input.trigger
+        : "TREND";
+    const dependencyPath = Array.isArray(input.dependencyPath)
+        ? input.dependencyPath.map((step) => normalizeText(step)).filter((step) => step.length > 0)
+        : undefined;
+    const evidenceIds = Array.isArray(input.evidenceIds)
+        ? input.evidenceIds.map((id) => normalizeText(id)).filter((id) => id.length > 0)
+        : undefined;
+    const validationStatusRaw = input.validationStatus?.trim().toLowerCase();
+    const validationStatus = validationStatusRaw &&
+        ["unchecked", "supporting", "conflicting", "openreview_related", "openreview_not_found"].includes(validationStatusRaw)
+        ? validationStatusRaw
+        : undefined;
+    const validationEvidence = normalizeStringArray(input.validationEvidence);
+    const validationNotes = input.validationNotes ? normalizeText(input.validationNotes) : undefined;
+    const withScore = (value) => typeof value === "number" && Number.isFinite(value) ? Number(value.toFixed(2)) : undefined;
+    return {
+        ...(input.id ? { id: sanitizeId(input.id) } : {}),
+        statement,
+        trigger,
+        ...(dependencyPath && dependencyPath.length > 0 ? { dependencyPath } : {}),
+        ...(typeof withScore(input.novelty) === "number" ? { novelty: withScore(input.novelty) } : {}),
+        ...(typeof withScore(input.feasibility) === "number" ? { feasibility: withScore(input.feasibility) } : {}),
+        ...(typeof withScore(input.impact) === "number" ? { impact: withScore(input.impact) } : {}),
+        ...(evidenceIds && evidenceIds.length > 0 ? { evidenceIds } : {}),
+        ...(validationStatus ? { validationStatus } : {}),
+        ...(validationNotes ? { validationNotes } : {}),
+        ...(validationEvidence ? { validationEvidence } : {}),
+    };
+}
+async function acquireLock(projectPath) {
+    const lockPath = getLockPath(projectPath);
+    const start = Date.now();
+    while (Date.now() - start < 8_000) {
+        try {
+            await writeFile(lockPath, String(process.pid), { flag: "wx" });
+            return;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, 120));
+        }
+    }
+    throw new Error("knowledge_state lock timeout");
+}
+async function releaseLock(projectPath) {
+    const lockPath = getLockPath(projectPath);
+    await unlink(lockPath).catch(() => undefined);
+}
+function makeStreamKey(scope, topic, fallbackTopicKey) {
+    const normalizedScope = normalizeScope(scope);
+    const normalizedTopic = normalizeText(topic).toLowerCase();
+    const digest = createHash("sha1").update(`${normalizedScope}\n${normalizedTopic}`).digest("hex").slice(0, 20);
+    return fallbackTopicKey || digest;
+}
+function toSummary(stream) {
+    return {
+        projectId: stream.projectId,
+        streamKey: stream.topicKey,
+        totalRuns: stream.totalRuns,
+        totalHypotheses: stream.totalHypotheses,
+        knowledgeTopicsCount: stream.knowledgeTopics.length,
+        paperNotesCount: stream.paperNotes.length,
+        recentFullTextReadCount: stream.recentFullTextReadCount,
+        recentNotFullTextReadCount: stream.recentNotFullTextReadCount,
+        qualityGate: stream.lastQualityGate,
+        unreadCorePaperIds: stream.lastUnreadCorePaperIds,
+        recentPapers: stream.recentPapers,
+        ...(stream.lastRunAtMs ? { lastRunAtMs: stream.lastRunAtMs } : {}),
+        ...(stream.lastStatus ? { lastStatus: stream.lastStatus } : {}),
+        recentHypotheses: stream.recentHypotheses,
+        recentChangeStats: stream.recentChangeStats,
+        lastExplorationTrace: stream.lastExplorationTrace,
+    };
+}
+function countChangeStats(day, runId, changes) {
+    let newCount = 0;
+    let confirmCount = 0;
+    let reviseCount = 0;
+    let bridgeCount = 0;
+    for (const item of changes) {
+        if (item.type === "NEW")
+            newCount += 1;
+        else if (item.type === "CONFIRM")
+            confirmCount += 1;
+        else if (item.type === "REVISE")
+            reviseCount += 1;
+        else if (item.type === "BRIDGE")
+            bridgeCount += 1;
+    }
+    return {
+        day,
+        runId,
+        newCount,
+        confirmCount,
+        reviseCount,
+        bridgeCount,
+    };
+}
+export async function commitKnowledgeRun(input) {
+    const project = await resolveProjectContext({
+        projectId: input.projectId,
+        scope: input.scope,
+        topic: input.topic,
+        autoCreate: true,
+    });
+    await ensureLayout(project.projectPath);
+    await acquireLock(project.projectPath);
+    try {
+        const root = await loadState(project.projectPath);
+        const nowMs = Date.now();
+        const nowIso = new Date(nowMs).toISOString();
+        const dayKey = dayKeyFromTimestamp(nowMs);
+        const knowledgeState = input.knowledgeState ?? {};
+        const corePapersFromState = (knowledgeState.corePapers ?? [])
+            .filter((item) => item && typeof item === "object")
+            .map((item) => withReadMark(item, "Core paper was recorded without full-text evidence."));
+        const explorationPapers = (knowledgeState.explorationPapers ?? [])
+            .filter((item) => item && typeof item === "object")
+            .map((item) => withReadMark(item, "Exploration paper not fully read in this run."));
+        const explorationTrace = (knowledgeState.explorationTrace ?? [])
+            .map(normalizeTrace)
+            .filter((item) => Boolean(item));
+        const knowledgeChanges = (knowledgeState.knowledgeChanges ?? [])
+            .map(normalizeChange)
+            .filter((item) => Boolean(item));
+        const knowledgeUpdates = (knowledgeState.knowledgeUpdates ?? [])
+            .map(normalizeUpdate)
+            .filter((item) => Boolean(item));
+        const hypotheses = (knowledgeState.hypotheses ?? [])
+            .map(normalizeHypothesis)
+            .filter((item) => Boolean(item));
+        const selectedPapers = (input.papers ?? [])
+            .filter((paper) => paper && typeof paper === "object")
+            .map((paper) => withReadMark({
+            id: paper.id,
+            title: paper.title,
+            url: paper.url,
+            score: paper.score,
+            reason: paper.reason,
+            summary: paper.reason,
+        }, "Paper selected from ranking payload without full-text-read evidence."));
+        const corePapers = mergePapers(selectedPapers, corePapersFromState).map((paper) => withReadMark(paper, "Core paper missing explicit full-text-read evidence."));
+        const streamKey = makeStreamKey(input.scope, input.topic, input.topicKey);
+        const stream = root.streams[streamKey] ??
+            {
+                scope: normalizeScope(input.scope),
+                topic: normalizeText(input.topic),
+                topicKey: streamKey,
+                projectId: project.projectId,
+                totalRuns: 0,
+                totalHypotheses: 0,
+                knowledgeTopics: [],
+                paperNotes: [],
+                recentFullTextReadCount: 0,
+                recentNotFullTextReadCount: 0,
+                lastQualityGate: defaultQualityGateState(),
+                lastUnreadCorePaperIds: [],
+                recentPapers: [],
+                recentRunIds: [],
+                recentHypothesisIds: [],
+                recentHypotheses: [],
+                recentChangeStats: [],
+                lastExplorationTrace: [],
+            };
+        const paperIds = mergePapers(corePapers, explorationPapers)
+            .map((paper) => paper.id || paper.url || paper.title || "")
+            .map((value) => normalizeText(value))
+            .filter((value) => value.length > 0);
+        const runId = input.runId?.trim()
+            ? sanitizeId(input.runId)
+            : buildRunFingerprint({
+                scope: stream.scope,
+                topic: stream.topic,
+                status: input.status,
+                day: dayKey,
+                paperIds,
+                note: input.note,
+            });
+        if (stream.recentRunIds.includes(runId)) {
+            root.streams[streamKey] = stream;
+            return {
+                projectId: project.projectId,
+                streamKey,
+                summary: toSummary(stream),
+                runId,
+                createdProject: project.created,
+            };
+        }
+        const rootPath = getKnowledgeStateRoot(project.projectPath);
+        const logDir = path.join(rootPath, "logs");
+        const dailyDir = path.join(rootPath, "daily_changes");
+        const knowledgeDir = path.join(rootPath, "knowledge");
+        const paperNotesDir = path.join(rootPath, "paper_notes");
+        const hypothesesDir = path.join(rootPath, "hypotheses");
+        await appendMarkdown(path.join(logDir, `day-${dayKey}-ingest.md`), renderIngestLogMarkdown({ now: nowIso, runId, scope: stream.scope, topic: stream.topic, papers: corePapers }));
+        await appendMarkdown(path.join(logDir, `day-${dayKey}-exploration.md`), renderExplorationLogMarkdown({
+            now: nowIso,
+            runId,
+            trace: explorationTrace,
+            papers: explorationPapers,
+        }));
+        await appendMarkdown(path.join(dailyDir, `day-${dayKey}.md`), renderDailyChangesMarkdown({ now: nowIso, runId, topic: stream.topic, changes: knowledgeChanges }));
+        const mergedRunPapers = mergePapers(corePapers, explorationPapers);
+        const qualityEval = applyQualityGates({
+            corePapers,
+            allRunPapers: mergedRunPapers,
+            knowledgeChanges,
+            knowledgeUpdates,
+            hypotheses,
+        });
+        const requestedStatus = normalizeText(input.status ?? "ok");
+        const qualitySensitiveStatus = requestedStatus === "ok" || requestedStatus === "fallback_representative";
+        const effectiveStatus = qualitySensitiveStatus && !qualityEval.qualityGate.passed ? "degraded_quality" : requestedStatus;
+        const topicToUpdates = new Map();
+        for (const update of knowledgeUpdates) {
+            const key = slugifyTopic(update.topic);
+            const list = topicToUpdates.get(key) ?? [];
+            list.push(update);
+            topicToUpdates.set(key, list);
+        }
+        for (const [topicSlug, updates] of topicToUpdates.entries()) {
+            const topicFile = `topic-${topicSlug}.md`;
+            const topicPath = path.join(knowledgeDir, topicFile);
+            if (!existsSync(topicPath)) {
+                await writeFile(topicPath, `# Topic: ${topicSlug}\n\n`, "utf-8");
+            }
+            await appendMarkdown(topicPath, renderTopicUpdateMarkdown({ now: nowIso, runId, updates }));
+            if (!stream.knowledgeTopics.includes(topicFile)) {
+                stream.knowledgeTopics.push(topicFile);
+            }
+        }
+        const coreKeys = new Set(corePapers.map((paper) => paperIdentity(paper)).filter((item) => item.length > 0));
+        const runPaperNoteFiles = [];
+        for (const paper of mergedRunPapers) {
+            const noteFile = `paper-${toPaperNoteSlug(paper)}.md`;
+            const notePath = path.join(paperNotesDir, noteFile);
+            const role = coreKeys.has(paperIdentity(paper)) ? "core" : "exploration";
+            if (!existsSync(notePath)) {
+                await writeFile(notePath, `${renderPaperNoteHeaderMarkdown({ paper, file: noteFile })}\n`, "utf-8");
+            }
+            await appendMarkdown(notePath, renderPaperNoteRunMarkdown({
+                now: nowIso,
+                runId,
+                role,
+                paper,
+            }));
+            runPaperNoteFiles.push(noteFile);
+        }
+        stream.paperNotes = [...new Set([...runPaperNoteFiles, ...stream.paperNotes])].slice(0, MAX_PAPER_NOTES);
+        const recentHypothesisSummaries = [];
+        let seq = stream.totalHypotheses;
+        const dayToken = dayKey.replace(/-/g, "");
+        for (const hypothesis of hypotheses) {
+            seq += 1;
+            const hypothesisId = hypothesis.id && hypothesis.id.length > 0 ? sanitizeId(hypothesis.id) : `hyp-${dayToken}-${String(seq).padStart(4, "0")}`;
+            const file = `${hypothesisId}.md`;
+            await writeFile(path.join(hypothesesDir, file), renderHypothesisMarkdown({ now: nowIso, hypothesisId, runId, hypothesis }), "utf-8");
+            recentHypothesisSummaries.push({
+                id: hypothesisId,
+                statement: hypothesis.statement,
+                trigger: hypothesis.trigger,
+                createdAtMs: nowMs,
+                file,
+            });
+        }
+        const fullTextStats = countFullTextStats(mergedRunPapers);
+        const structuredProfileCount = mergedRunPapers.filter(hasStructuredProfile).length;
+        await writeFile(path.join(knowledgeDir, "_index.md"), renderKnowledgeIndexMarkdown({
+            now: nowIso,
+            topic: stream.topic,
+            topicFiles: stream.knowledgeTopics,
+            paperNotesCount: stream.paperNotes.length,
+            totalHypotheses: stream.totalHypotheses + recentHypothesisSummaries.length,
+            recentPapers: mergedRunPapers,
+            fullTextReadCount: fullTextStats.fullTextReadCount,
+            notFullTextReadCount: fullTextStats.notFullTextReadCount,
+            qualityGate: qualityEval.qualityGate,
+            unreadCorePaperIds: qualityEval.unreadCorePaperIds,
+            lastStatus: effectiveStatus,
+        }), "utf-8");
+        const changeStat = countChangeStats(dayKey, runId, knowledgeChanges);
+        stream.projectId = project.projectId;
+        stream.totalRuns += 1;
+        stream.totalHypotheses += recentHypothesisSummaries.length;
+        stream.lastRunAtMs = nowMs;
+        stream.lastStatus = effectiveStatus;
+        stream.recentFullTextReadCount = fullTextStats.fullTextReadCount;
+        stream.recentNotFullTextReadCount = fullTextStats.notFullTextReadCount;
+        stream.lastQualityGate = qualityEval.qualityGate;
+        stream.lastUnreadCorePaperIds = qualityEval.unreadCorePaperIds;
+        stream.lastExplorationTrace = explorationTrace.slice(0, MAX_LAST_TRACE);
+        stream.recentPapers = mergePapers(mergedRunPapers, stream.recentPapers).slice(0, MAX_RECENT_PAPERS);
+        stream.recentRunIds = [runId, ...stream.recentRunIds.filter((id) => id !== runId)].slice(0, MAX_RECENT_RUN_IDS);
+        stream.recentHypothesisIds = [
+            ...recentHypothesisSummaries.map((item) => item.id),
+            ...stream.recentHypothesisIds,
+        ].slice(0, MAX_RECENT_HYPOTHESES);
+        stream.recentHypotheses = [...recentHypothesisSummaries, ...stream.recentHypotheses].slice(0, MAX_RECENT_HYPOTHESES);
+        stream.recentChangeStats = [changeStat, ...stream.recentChangeStats].slice(0, MAX_RECENT_CHANGE_STATS);
+        root.streams[streamKey] = stream;
+        await saveStateAtomic(project.projectPath, root);
+        await appendFile(path.join(logDir, `day-${dayKey}-run-details.jsonl`), `${JSON.stringify({
+            ts: nowMs,
+            runId,
+            scope: stream.scope,
+            topic: stream.topic,
+            streamKey,
+            status: effectiveStatus,
+            corePapers,
+            explorationPapers,
+            explorationTrace,
+            knowledgeChanges,
+            knowledgeUpdates,
+            hypotheses,
+            paperNoteFiles: runPaperNoteFiles,
+            quality: {
+                fullTextReadCount: fullTextStats.fullTextReadCount,
+                notFullTextReadCount: fullTextStats.notFullTextReadCount,
+                paperNotesCount: stream.paperNotes.length,
+                structuredProfileCount,
+                qualityGate: qualityEval.qualityGate,
+                unreadCorePaperIds: qualityEval.unreadCorePaperIds,
+                downgradedHighConfidenceCount: qualityEval.downgradedHighConfidenceCount,
+            },
+            runLog: input.knowledgeState?.runLog ?? null,
+            note: input.note ?? null,
+        })}\n`, "utf-8");
+        await appendEvent(project.projectPath, {
+            ts: nowMs,
+            runId,
+            scope: stream.scope,
+            topic: stream.topic,
+            streamKey,
+            projectId: project.projectId,
+            status: effectiveStatus,
+            paperCount: corePapers.length,
+            explorationPaperCount: explorationPapers.length,
+            fullTextReadCount: fullTextStats.fullTextReadCount,
+            notFullTextReadCount: fullTextStats.notFullTextReadCount,
+            paperNotesCount: stream.paperNotes.length,
+            paperNoteFiles: runPaperNoteFiles,
+            structuredProfileCount,
+            qualityGate: qualityEval.qualityGate,
+            unreadCorePaperIds: qualityEval.unreadCorePaperIds,
+            downgradedHighConfidenceCount: qualityEval.downgradedHighConfidenceCount,
+            changeCount: knowledgeChanges.length,
+            hypothesisCount: recentHypothesisSummaries.length,
+            corePapers,
+            explorationPapers,
+            note: input.note,
+            runLog: input.knowledgeState?.runLog ?? null,
+        });
+        return {
+            projectId: project.projectId,
+            streamKey,
+            summary: toSummary(stream),
+            runId,
+            createdProject: project.created,
+        };
+    }
+    finally {
+        await releaseLock(project.projectPath);
+    }
+}
+export async function readKnowledgeSummary(args) {
+    let project;
+    try {
+        project = await resolveProjectContext({
+            projectId: args.projectId,
+            scope: args.scope,
+            topic: args.topic,
+            autoCreate: false,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const statePath = getStatePath(project.projectPath);
+    if (!existsSync(statePath))
+        return undefined;
+    const root = await loadState(project.projectPath);
+    const streamKey = makeStreamKey(args.scope, args.topic, args.topicKey);
+    const stream = root.streams[streamKey];
+    if (!stream)
+        return undefined;
+    return {
+        projectId: project.projectId,
+        streamKey,
+        summary: toSummary(stream),
+    };
+}
+//# sourceMappingURL=store.js.map