freshcontext-mcp 0.3.17 → 0.3.19

package/dist/core/decision.js

@@ -0,0 +1,176 @@
+import { getSourceProfile } from "./sourceProfiles.js";
+const CITATION_INTENTS = new Set(["citation_check", "student_research"]);
+const STRICT_REFRESH_PROFILES = new Set(["market_finance", "jobs_opportunities"]);
+function resolveSourceProfile(profile) {
+    if (!profile)
+        return undefined;
+    return typeof profile === "string" ? getSourceProfile(profile) : profile;
+}
+function profileId(profile) {
+    return profile?.profile_id;
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function hasFailureReason(evaluation) {
+    return evaluation.reasons.some((reason) => /\b(?:failed|failure|timeout|error|blocked|upstream)\b/i.test(reason));
+}
+function isCitationIntent(intent) {
+    return intent !== undefined && CITATION_INTENTS.has(intent);
+}
+function nonAdviceWarnings(intent) {
+    switch (intent) {
+        case "citation_check":
+        case "student_research":
+            return ["FreshContext judges citation readiness and context usefulness; it does not certify truth."];
+        case "medical_literature_triage":
+            return ["FreshContext provides literature triage only; it is not medical advice."];
+        case "market_watch":
+            return ["FreshContext provides market signal triage only; it is not investment advice."];
+        case "business_due_diligence":
+            return ["FreshContext supports context triage only; it is not legal, tax, or investment advice."];
+        case "job_search":
+            return ["FreshContext provides opportunity triage only; it is not employment or legal advice."];
+        default:
+            return [];
+    }
+}
+function decisionResult(decision, reasons, warnings) {
+    const copyReasons = unique(reasons);
+    const copyWarnings = unique(warnings);
+    switch (decision) {
+        case "use_first":
+            return {
+                decision,
+                label: "Use first",
+                meaning: "This is strong, current context for the task.",
+                action: "Use this near the top of the context bundle.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "cite_as_primary":
+            return {
+                decision,
+                label: "Cite as primary",
+                meaning: "This source is relevant, current, and traceable enough to use as main evidence.",
+                action: "Use it as primary citation evidence, while keeping normal source-review standards.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "cite_as_supporting":
+            return {
+                decision,
+                label: "Cite as supporting",
+                meaning: "This source is useful evidence, but should not be the only or latest support.",
+                action: "Use it as supporting evidence and pair it with stronger or newer sources.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "use_as_background":
+            return {
+                decision,
+                label: "Use as background",
+                meaning: "This source is relevant context, but not strong enough for latest-evidence claims.",
+                action: "Use it for framing, history, or background rather than as the main current source.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "needs_verification":
+            return {
+                decision,
+                label: "Needs verification",
+                meaning: "This source may be useful, but its date, confidence, or traceability is uncertain.",
+                action: "Verify the source details before citing it, acting on it, or sending it to a model as trusted context.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "needs_refresh":
+            return {
+                decision,
+                label: "Needs refresh",
+                meaning: "This source may be useful, but it is too stale or date-uncertain for this source type.",
+                action: "Refresh or re-query this source before relying on it as current context.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "watch_only":
+            return {
+                decision,
+                label: "Watch only",
+                meaning: "This is an interesting signal, but not strong enough to prioritize.",
+                action: "Monitor it or keep it as a weak signal; do not use it as main evidence.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "exclude":
+            return {
+                decision,
+                label: "Exclude",
+                meaning: "This source is failed, too weak, or unsafe to include as useful context.",
+                action: "Keep it out of the final context bundle unless a human explicitly reviews it.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+    }
+}
+export function interpretEvaluation(evaluation, options = {}) {
+    const sourceProfile = resolveSourceProfile(options.sourceProfile);
+    const sourceProfileId = profileId(sourceProfile);
+    const intentProfile = options.intentProfile;
+    const reasons = unique([
+        evaluation.explanation,
+        ...evaluation.signal.reasons,
+        ...evaluation.utility.reasons,
+        ...evaluation.reasons,
+    ]);
+    const warnings = [...nonAdviceWarnings(intentProfile)];
+    const finalScore = evaluation.ranked.final_score;
+    const utilityScore = evaluation.utility.score;
+    const freshnessScore = evaluation.freshness_score;
+    const confidence = evaluation.ranked.confidence;
+    const isFailed = evaluation.signal.status === "failed"
+        || (confidence === "low" && hasFailureReason(evaluation));
+    if (sourceProfile) {
+        reasons.push(`source profile ${sourceProfile.profile_id} uses ${sourceProfile.date_policy} date policy`);
+    }
+    if (intentProfile) {
+        reasons.push(`intent profile ${intentProfile} selected`);
+    }
+    if (isFailed) {
+        return decisionResult("exclude", reasons, warnings);
+    }
+    if (sourceProfileId
+        && STRICT_REFRESH_PROFILES.has(sourceProfileId)
+        && (freshnessScore === null || freshnessScore < 50)) {
+        return decisionResult("needs_refresh", reasons, warnings);
+    }
+    if (evaluation.signal.date_confidence === "unknown") {
+        if (sourceProfileId === "academic_research" && finalScore >= 0.75) {
+            return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings);
+        }
+        return decisionResult("needs_verification", reasons, warnings);
+    }
+    if (finalScore >= 0.85
+        && freshnessScore !== null
+        && freshnessScore >= 70
+        && utilityScore >= 60
+        && confidence === "high") {
+        if (sourceProfile?.authority_hint === "high" && isCitationIntent(intentProfile)) {
+            return decisionResult("cite_as_primary", reasons, warnings);
+        }
+        return decisionResult("use_first", reasons, warnings);
+    }
+    if (finalScore >= 0.55 && freshnessScore !== null && freshnessScore < 50) {
+        return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings);
+    }
+    if (finalScore < 0.35 && utilityScore < 30) {
+        return decisionResult(confidence === "low" ? "exclude" : "watch_only", reasons, warnings);
+    }
+    if (finalScore >= 0.55) {
+        return decisionResult("use_as_background", reasons, warnings);
+    }
+    return decisionResult("watch_only", reasons, warnings);
+}
+export function interpretEvaluations(evaluations, options = {}) {
+    return evaluations.map((evaluation) => interpretEvaluation(evaluation, options));
+}

package/dist/core/envelope.js

@@ -0,0 +1,59 @@
+import { calculateFreshnessScore, isMeaningfullyFutureDate, scoreLabel } from "./decay.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+export function stampFreshness(result, options, adapter) {
+    const retrieved_at = new Date().toISOString();
+    const failedContent = looksLikeFailedAdapterContent(result.raw);
+    const content_date = failedContent ? null : result.content_date;
+    const futureDated = !failedContent && isMeaningfullyFutureDate(content_date, retrieved_at);
+    const freshness_confidence = failedContent || futureDated ? "low" : result.freshness_confidence;
+    const freshness_score = calculateFreshnessScore(content_date, retrieved_at, adapter);
+    return {
+        content: result.raw.slice(0, options.maxLength ?? 8000),
+        source_url: options.url,
+        content_date,
+        retrieved_at,
+        freshness_confidence,
+        freshness_score,
+        adapter,
+    };
+}
+export function toStructuredJSON(ctx) {
+    return {
+        freshcontext: {
+            source_url: ctx.source_url,
+            content_date: ctx.content_date,
+            retrieved_at: ctx.retrieved_at,
+            freshness_confidence: ctx.freshness_confidence,
+            freshness_score: ctx.freshness_score,
+            adapter: ctx.adapter,
+        },
+        content: ctx.content,
+    };
+}
+export function formatForLLM(ctx, options = {}) {
+    const publishedLabel = options.publishedLabel ?? "Published";
+    const unknownDateText = options.unknownDateText ?? "Publish date: unknown";
+    const dateInfo = ctx.content_date
+        ? `${publishedLabel}: ${ctx.content_date}`
+        : unknownDateText;
+    const scoreLine = ctx.freshness_score !== null
+        ? `Score: ${ctx.freshness_score}/100 (${scoreLabel(ctx.freshness_score)})`
+        : `Score: unknown`;
+    const textEnvelope = [
+        `[FRESHCONTEXT]`,
+        `Source: ${ctx.source_url}`,
+        `${dateInfo}`,
+        `Retrieved: ${ctx.retrieved_at}`,
+        `Confidence: ${ctx.freshness_confidence}`,
+        `${scoreLine}`,
+        `---`,
+        ctx.content,
+        `[/FRESHCONTEXT]`,
+    ].join("\n");
+    const jsonBlock = [
+        `[FRESHCONTEXT_JSON]`,
+        JSON.stringify(toStructuredJSON(ctx), null, 2),
+        `[/FRESHCONTEXT_JSON]`,
+    ].join("\n");
+    return `${textEnvelope}\n\n${jsonBlock}`;
+}

package/dist/core/explain.js

@@ -0,0 +1,28 @@
+function sourceLabel(input) {
+    return input.source_type || input.source || "source";
+}
+export function explainSignal(input) {
+    const source = sourceLabel(input);
+    if (input.freshness_score === null) {
+        if (input.semantic_score < 0.5) {
+            return `Low confidence: weak semantic match and missing freshness data for ${source}.`;
+        }
+        return `Missing freshness data for ${source}; ranked mostly by semantic relevance.`;
+    }
+    if (input.semantic_score < 0.5) {
+        if (input.freshness_score >= 70) {
+            return `Fresh signal from ${source}, but semantic relevance is weak.`;
+        }
+        return `Weak semantic match with limited freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 90) {
+        return `Strong semantic match and current freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 70) {
+        return `Relevant signal with reliable freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 50) {
+        return `Relevant signal, but freshness should be verified for ${source}.`;
+    }
+    return `Relevant signal, but stale for ${source}.`;
+}

package/dist/core/guards.js

@@ -0,0 +1,17 @@
+export function looksLikeFailedAdapterContent(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return true;
+    if (/^\[(?:error|security)\]/i.test(trimmed))
+        return true;
+    if (/^(?:error|failed|upstream|timeout)\b/i.test(trimmed))
+        return true;
+    const meaningful = trimmed
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (!meaningful.length)
+        return true;
+    const failureLines = meaningful.filter((line) => /\b(?:error|failed|failure|timeout|401|403|404|429|5\d\d)\b/i.test(line));
+    return failureLines.length === meaningful.length;
+}

package/dist/core/index.js

@@ -0,0 +1,11 @@
+export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { looksLikeFailedAdapterContent } from "./guards.js";
+export { stampFreshness, toStructuredJSON, formatForLLM } from "./envelope.js";
+export { explainSignal } from "./explain.js";
+export { rankSignals, rankSignal, clampScore } from "./rank.js";
+export { calculateContextUtility } from "./utility.js";
+export { SIGNAL_CONTRACT_VERSION, normalizeSignal } from "./signal.js";
+export { evaluateSignal, evaluateSignals } from "./pipeline.js";
+export { interpretEvaluation, interpretEvaluations } from "./decision.js";
+export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles } from "./sourceProfiles.js";
+export { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, verifyHaPriV2, } from "./provenance.js";

package/dist/core/pipeline.js

@@ -0,0 +1,101 @@
+import { LAMBDA, calculateFreshnessScore } from "./decay.js";
+import { formatForLLM, toStructuredJSON } from "./envelope.js";
+import { calculateHaPriV2 } from "./provenance.js";
+import { rankSignal } from "./rank.js";
+import { normalizeSignal } from "./signal.js";
+import { calculateContextUtility } from "./utility.js";
+function ageHours(signal) {
+    if (!signal.published_at)
+        return 0;
+    const published = new Date(signal.published_at).getTime();
+    const retrieved = new Date(signal.retrieved_at).getTime();
+    if (isNaN(published) || isNaN(retrieved))
+        return 0;
+    return Math.max(0, (retrieved - published) / (1000 * 60 * 60));
+}
+function envelopeConfidence(signal) {
+    if (signal.status === "failed" || signal.date_confidence === "unknown")
+        return "low";
+    return signal.date_confidence;
+}
+function createEnvelope(signal, freshnessScore, options) {
+    if (!options.includeEnvelope || signal.content === undefined)
+        return undefined;
+    const ctx = {
+        content: signal.content.slice(0, options.envelopeMaxLength ?? 8000),
+        source_url: signal.source,
+        content_date: signal.published_at,
+        retrieved_at: signal.retrieved_at,
+        freshness_confidence: envelopeConfidence(signal),
+        freshness_score: freshnessScore,
+        adapter: signal.source_type,
+    };
+    return {
+        context: ctx,
+        text: formatForLLM(ctx, options.envelopeFormat),
+        structured: toStructuredJSON(ctx),
+    };
+}
+function createProvenance(signal, options, reasons) {
+    if (!options.includeProvenance)
+        return undefined;
+    const resultId = options.provenance?.resultId ?? signal.id;
+    const engineVersion = options.provenance?.engineVersion;
+    if (!signal.content) {
+        reasons.push("provenance was requested but content was missing");
+        return undefined;
+    }
+    if (!resultId) {
+        reasons.push("provenance was requested but resultId was missing");
+        return undefined;
+    }
+    if (!engineVersion) {
+        reasons.push("provenance was requested but engineVersion was missing");
+        return undefined;
+    }
+    return calculateHaPriV2({
+        resultId,
+        rawContent: signal.content,
+        semanticFingerprint: options.provenance?.semanticFingerprint ?? null,
+        adapter: signal.source_type,
+        publishedAt: signal.published_at,
+        retrievedAt: signal.retrieved_at,
+        engineVersion,
+    });
+}
+export function evaluateSignal(input, options = {}) {
+    const signal = normalizeSignal(input, options);
+    const freshness_score = signal.status === "failed" || signal.date_confidence === "unknown"
+        ? null
+        : calculateFreshnessScore(signal.published_at, signal.retrieved_at, signal.source_type);
+    const utility = calculateContextUtility({
+        contextualRelevance: signal.semantic_score * 100,
+        lambda: LAMBDA[signal.source_type] ?? LAMBDA.default,
+        ageHours: ageHours(signal),
+        dateConfidence: signal.date_confidence,
+        status: signal.status,
+    });
+    const ranked = rankSignal(signal, options);
+    const reasons = [...signal.reasons, ...utility.reasons];
+    const envelope = createEnvelope(signal, freshness_score, options);
+    const provenance = createProvenance(signal, options, reasons);
+    return {
+        signal,
+        freshness_score,
+        utility,
+        ranked,
+        explanation: ranked.reason,
+        envelope,
+        provenance,
+        reasons,
+    };
+}
+export function evaluateSignals(inputs, options = {}) {
+    return inputs
+        .map((input, index) => ({ evaluation: evaluateSignal(input, options), index }))
+        .sort((a, b) => {
+        const scoreDiff = b.evaluation.ranked.final_score - a.evaluation.ranked.final_score;
+        return scoreDiff !== 0 ? scoreDiff : a.index - b.index;
+    })
+        .map(({ evaluation }) => evaluation);
+}

package/dist/core/provenance.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+const HA_PRI_V2_VERSION = "FRESHCONTEXT_HA_PRI_V2";
+const NULL_SENTINEL = "null";
+function fieldValue(value) {
+    return value ?? NULL_SENTINEL;
+}
+export function canonicalizeHaPriContent(input) {
+    return input
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+export function calculateHaPriV2(input) {
+    const canonicalContentSha256 = sha256Hex(canonicalizeHaPriContent(input.rawContent));
+    const semanticFingerprintSha256 = sha256Hex(fieldValue(input.semanticFingerprint));
+    const resultId = fieldValue(input.resultId);
+    const adapter = fieldValue(input.adapter);
+    const publishedAt = fieldValue(input.publishedAt);
+    const retrievedAt = fieldValue(input.retrievedAt);
+    const engineVersion = fieldValue(input.engineVersion);
+    const signingPayload = [
+        HA_PRI_V2_VERSION,
+        `result_id=${resultId}`,
+        `canonical_content_sha256=${canonicalContentSha256}`,
+        `semantic_fingerprint_sha256=${semanticFingerprintSha256}`,
+        `adapter=${adapter}`,
+        `published_at=${publishedAt}`,
+        `retrieved_at=${retrievedAt}`,
+        `engine_version=${engineVersion}`,
+    ].join("\n");
+    return {
+        version: HA_PRI_V2_VERSION,
+        resultId,
+        canonicalContentSha256,
+        semanticFingerprintSha256,
+        adapter,
+        publishedAt,
+        retrievedAt,
+        engineVersion,
+        signingPayload,
+        haPriSigV2: sha256Hex(signingPayload),
+    };
+}
+export function verifyHaPriV2(input, actualSig) {
+    if (actualSig === null || actualSig === undefined || actualSig.trim() === "") {
+        return {
+            status: "unknown",
+            expected: null,
+            actual: actualSig ?? null,
+            reasons: ["missing ha_pri_sig_v2; verification status unknown"],
+        };
+    }
+    const expected = calculateHaPriV2(input).haPriSigV2;
+    if (actualSig === expected) {
+        return {
+            status: "valid",
+            expected,
+            actual: actualSig,
+            reasons: [],
+        };
+    }
+    return {
+        status: "invalid",
+        expected,
+        actual: actualSig,
+        reasons: ["stored ha_pri_sig_v2 did not match recomputed signature"],
+    };
+}

package/dist/core/rank.js

@@ -0,0 +1,84 @@
+import { calculateFreshnessScore } from "./decay.js";
+import { explainSignal } from "./explain.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+const DEFAULT_SEMANTIC_WEIGHT = 0.7;
+const DEFAULT_FRESHNESS_WEIGHT = 0.3;
+export function clampScore(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function positiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function resolveWeights(options) {
+    let semantic = positiveNumber(options.semanticWeight);
+    let freshness = positiveNumber(options.freshnessWeight);
+    if (semantic === 0 && freshness === 0) {
+        semantic = DEFAULT_SEMANTIC_WEIGHT;
+        freshness = DEFAULT_FRESHNESS_WEIGHT;
+    }
+    const total = semantic + freshness;
+    return {
+        semantic: semantic / total,
+        freshness: freshness / total,
+    };
+}
+function resolveRetrievedAt(signal, options) {
+    if (signal.retrieved_at)
+        return signal.retrieved_at;
+    if (options.now instanceof Date)
+        return options.now.toISOString();
+    if (typeof options.now === "string")
+        return options.now;
+    return new Date().toISOString();
+}
+function resolveSourceType(signal, options) {
+    return signal.source_type ?? options.defaultSourceType ?? signal.source ?? "default";
+}
+function isFailedSignal(signal) {
+    return signal.status === "failed"
+        || (signal.content !== undefined && looksLikeFailedAdapterContent(signal.content));
+}
+function confidenceFor(signal, semanticScore, freshnessScore) {
+    if (isFailedSignal(signal)) {
+        return "low";
+    }
+    if (freshnessScore !== null && semanticScore >= 0.7) {
+        return "high";
+    }
+    if (freshnessScore !== null || semanticScore >= 0.5) {
+        return "medium";
+    }
+    return "low";
+}
+export function rankSignal(signal, options = {}) {
+    const weights = resolveWeights(options);
+    const semantic_score = clampScore(signal.semantic_score);
+    const freshness_score = isFailedSignal(signal) || signal.date_confidence === "unknown"
+        ? null
+        : calculateFreshnessScore(signal.published_at ?? signal.content_date ?? null, resolveRetrievedAt(signal, options), resolveSourceType(signal, options));
+    const freshnessComponent = freshness_score === null ? 0 : clampScore(freshness_score / 100);
+    const final_score = clampScore(semantic_score * weights.semantic + freshnessComponent * weights.freshness);
+    const confidence = confidenceFor(signal, semantic_score, freshness_score);
+    const ranked = {
+        ...signal,
+        semantic_score,
+        freshness_score,
+        final_score,
+        confidence,
+    };
+    return {
+        ...ranked,
+        reason: explainSignal(ranked),
+    };
+}
+export function rankSignals(signals, options = {}) {
+    return signals
+        .map((signal, index) => ({ ranked: rankSignal(signal, options), index }))
+        .sort((a, b) => {
+        const scoreDiff = b.ranked.final_score - a.ranked.final_score;
+        return scoreDiff !== 0 ? scoreDiff : a.index - b.index;
+    })
+        .map(({ ranked }) => ranked);
+}

package/dist/core/signal.js

@@ -0,0 +1,101 @@
+import { isMeaningfullyFutureDate } from "./decay.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+export const SIGNAL_CONTRACT_VERSION = "freshcontext.signal.v1";
+const DATE_CONFIDENCE_VALUES = new Set(["high", "medium", "low", "unknown"]);
+const STATUS_VALUES = new Set(["success", "partial", "stale", "failed", "unknown"]);
+function isSignalDateConfidence(value) {
+    return typeof value === "string" && DATE_CONFIDENCE_VALUES.has(value);
+}
+function isContextUtilityStatus(value) {
+    return typeof value === "string" && STATUS_VALUES.has(value);
+}
+function normalizeDate(value) {
+    if (!value)
+        return null;
+    const timestamp = new Date(value).getTime();
+    if (isNaN(timestamp))
+        return null;
+    return new Date(timestamp).toISOString();
+}
+function resolveRetrievedAt(input, options, reasons) {
+    const retrievedAt = normalizeDate(input.retrieved_at);
+    if (retrievedAt)
+        return retrievedAt;
+    if (input.retrieved_at) {
+        reasons.push("retrieved_at was invalid; used normalization time");
+    }
+    const optionNow = options.now instanceof Date
+        ? (isNaN(options.now.getTime()) ? null : options.now.toISOString())
+        : normalizeDate(options.now);
+    return optionNow ?? new Date().toISOString();
+}
+function normalizeSemanticScore(value, reasons) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        reasons.push("semantic_score was missing or invalid; clamped to 0");
+        return 0;
+    }
+    if (value < 0) {
+        reasons.push("semantic_score was below 0; clamped to 0");
+        return 0;
+    }
+    if (value > 1) {
+        reasons.push("semantic_score exceeded 1; clamped to 1");
+        return 1;
+    }
+    return value;
+}
+function resolveDateConfidence(input, hasTrustedDate) {
+    if (!hasTrustedDate)
+        return "unknown";
+    if (isSignalDateConfidence(input.date_confidence))
+        return input.date_confidence;
+    if (input.freshness_confidence)
+        return input.freshness_confidence;
+    return "medium";
+}
+function resolveStatus(input, failedContent) {
+    if (failedContent)
+        return "failed";
+    if (isContextUtilityStatus(input.status))
+        return input.status;
+    return "success";
+}
+export function normalizeSignal(input, options = {}) {
+    const reasons = [];
+    const retrieved_at = resolveRetrievedAt(input, options, reasons);
+    const rawPublishedAt = input.published_at ?? input.content_date ?? null;
+    let published_at = normalizeDate(rawPublishedAt);
+    if (!input.published_at && input.content_date) {
+        reasons.push("content_date alias was normalized to published_at");
+    }
+    if (rawPublishedAt && !published_at) {
+        reasons.push("published_at/content_date was invalid; cleared");
+    }
+    if (published_at && isMeaningfullyFutureDate(published_at, retrieved_at)) {
+        published_at = null;
+        reasons.push("published_at/content_date was meaningfully future-dated; cleared");
+    }
+    const failedContent = input.content !== undefined && looksLikeFailedAdapterContent(input.content);
+    if (failedContent) {
+        reasons.push("content looked like failed adapter output; status set to failed");
+    }
+    const source_type = input.source_type ?? options.defaultSourceType ?? "default";
+    if (!input.source_type && !options.defaultSourceType) {
+        reasons.push("source_type was missing; defaulted to default");
+    }
+    return {
+        contract_version: SIGNAL_CONTRACT_VERSION,
+        id: input.id,
+        source: input.source,
+        source_type,
+        title: input.title,
+        content: input.content,
+        published_at,
+        retrieved_at,
+        semantic_score: normalizeSemanticScore(input.semantic_score, reasons),
+        date_confidence: resolveDateConfidence(input, published_at !== null),
+        status: resolveStatus(input, failedContent),
+        metadata: input.metadata ? { ...input.metadata } : {},
+        reasons,
+    };
+}