freshcontext-mcp 0.3.19 → 0.3.21

package/dist/adapters/jobs.js

@@ -131,7 +131,7 @@ export async function jobsAdapter(options) {
 async function fetchRemotive(query, location, maxAgeDays, keywords) {
     const url = `https://remotive.com/api/remote-jobs?search=${encodeURIComponent(query)}&limit=15`;
     const res = await fetch(url, {
-        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.21", "Accept": "application/json" },
     });
     if (!res.ok)
         throw new Error(`Remotive ${res.status}`);
@@ -161,7 +161,7 @@ async function fetchRemoteOK(query, location, maxAgeDays, keywords) {
     const tag = query.toLowerCase().replace(/\s+/g, "-");
     const url = `https://remoteok.com/api?tag=${encodeURIComponent(tag)}`;
     const res = await fetch(url, {
-        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.21", "Accept": "application/json" },
     });
     if (!res.ok)
         throw new Error(`RemoteOK ${res.status}`);
@@ -199,7 +199,7 @@ async function fetchArbeitnow(query, location, maxAgeDays, keywords, remoteOnly)
         params.set("remote", "true");
     const url = `https://arbeitnow.com/api/job-board-api?${params.toString()}`;
     const res = await fetch(url, {
-        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.21", "Accept": "application/json" },
     });
     if (!res.ok)
         throw new Error(`Arbeitnow ${res.status}`);
@@ -233,7 +233,7 @@ async function fetchMuse(query, location, maxAgeDays, keywords) {
         : "&location=Flexible%20%2F%20Remote";
     const url = `https://www.themuse.com/api/public/jobs?name=${encodeURIComponent(query)}${locParam}&page=0&descending=true`;
     const res = await fetch(url, {
-        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.21", "Accept": "application/json" },
     });
     if (!res.ok)
         throw new Error(`The Muse ${res.status}`);
@@ -263,7 +263,7 @@ async function fetchMuse(query, location, maxAgeDays, keywords) {
 // instead of all HN comments. Uses the parent_id filter to target the thread.
 async function fetchHNHiring(query, location, maxAgeDays, keywords) {
     // Step 1: Find the most recent "Ask HN: Who is hiring?" thread
-    const threadRes = await fetch(`https://hn.algolia.com/api/v1/search?query=Ask+HN+Who+is+hiring&tags=story&hitsPerPage=5`, { headers: { "User-Agent": "freshcontext-mcp/0.3.0" } });
+    const threadRes = await fetch(`https://hn.algolia.com/api/v1/search?query=Ask+HN+Who+is+hiring&tags=story&hitsPerPage=5`, { headers: { "User-Agent": "freshcontext-mcp/0.3.21" } });
     if (!threadRes.ok)
         throw new Error(`HN thread search ${threadRes.status}`);
     const threadData = await threadRes.json();
@@ -273,7 +273,7 @@ async function fetchHNHiring(query, location, maxAgeDays, keywords) {
         throw new Error("HN hiring thread not found");
     // Step 2: Search comments within that thread for the query
     const searchTerms = [query, location].filter(Boolean).join(" ");
-    const commentsRes = await fetch(`https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchTerms)}&tags=comment,story_${hiringThread.objectID}&hitsPerPage=10`, { headers: { "User-Agent": "freshcontext-mcp/0.3.0" } });
+    const commentsRes = await fetch(`https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchTerms)}&tags=comment,story_${hiringThread.objectID}&hitsPerPage=10`, { headers: { "User-Agent": "freshcontext-mcp/0.3.21" } });
     if (!commentsRes.ok)
         throw new Error(`HN comments ${commentsRes.status}`);
     const commentsData = await commentsRes.json();

package/dist/adapters/packageTrends.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function packageTrendsAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/productHunt.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function productHuntAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/reddit.d.ts

@@ -0,0 +1,8 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+/**
+ * Reddit adapter — public JSON API, no auth required.
+ * Accepts subreddit URLs or search queries.
+ * e.g. https://www.reddit.com/r/MachineLearning/.json
+ *      https://www.reddit.com/search.json?q=mcp+server&sort=hot
+ */
+export declare function redditAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/reddit.js

@@ -1,3 +1,4 @@
+import { sanitizeQuery, validateUrl } from "../security.js";
 /**
  * Reddit adapter — public JSON API, no auth required.
  * Accepts subreddit URLs or search queries.
@@ -6,10 +7,15 @@
  */
 export async function redditAdapter(options) {
     let apiUrl = options.url;
-    // If they pass a plain subreddit name like "r/MachineLearning", build the URL
+    // If they pass a plain subreddit or search query, build a Reddit JSON URL.
     if (!apiUrl.startsWith("http")) {
-        const clean = apiUrl.replace(/^r\//, "");
-        apiUrl = `https://www.reddit.com/r/${clean}/.json?limit=25&sort=hot`;
+        const clean = sanitizeQuery(apiUrl, 120).replace(/^r\//, "").replace(/^\/+|\/+$/g, "");
+        if (/^[A-Za-z0-9_]{2,21}$/.test(clean)) {
+            apiUrl = `https://www.reddit.com/r/${clean}/.json?limit=25&sort=hot`;
+        }
+        else {
+            apiUrl = `https://www.reddit.com/search.json?q=${encodeURIComponent(clean)}&sort=new&limit=25`;
+        }
     }
     // Ensure we hit the JSON endpoint
     if (!apiUrl.includes(".json")) {
@@ -19,9 +25,10 @@ export async function redditAdapter(options) {
     if (!apiUrl.includes("limit=")) {
         apiUrl += (apiUrl.includes("?") ? "&" : "?") + "limit=25";
     }
-    const res = await fetch(apiUrl, {
+    const safeUrl = validateUrl(apiUrl, "reddit");
+    const res = await fetch(safeUrl, {
         headers: {
-            "User-Agent": "freshcontext-mcp/0.1.5 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+            "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
             "Accept": "application/json",
         },
     });

package/dist/adapters/registry.d.ts

@@ -0,0 +1,19 @@
+import type { SourceProfileId } from "../core/index.js";
+export type AdapterRisk = "low" | "medium" | "high";
+export type AdapterOutputMode = "single" | "batch" | "composite";
+export type AdapterRuntimeKind = "api" | "browser" | "composite" | "mixed" | "local";
+export interface FreshContextAdapterDescriptor {
+    adapter_id: string;
+    tool_name: string;
+    source_profile: SourceProfileId;
+    secondary_source_profiles?: SourceProfileId[];
+    output_mode: AdapterOutputMode;
+    runtime_kind: AdapterRuntimeKind;
+    risk: AdapterRisk;
+    notes?: string;
+}
+export declare const BUILT_IN_ADAPTER_REGISTRY: readonly FreshContextAdapterDescriptor[];
+export declare function listAdapterDescriptors(): FreshContextAdapterDescriptor[];
+export declare function getAdapterDescriptor(adapterIdOrToolName: string): FreshContextAdapterDescriptor | undefined;
+export declare function listAdaptersBySourceProfile(profileId: SourceProfileId): FreshContextAdapterDescriptor[];
+export declare function listAdaptersByRisk(risk: AdapterRisk): FreshContextAdapterDescriptor[];

package/dist/adapters/repoSearch.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function repoSearchAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/repoSearch.js

@@ -22,7 +22,7 @@ export async function repoSearchAdapter(options) {
     const res = await fetch(apiUrl, {
         headers: {
             Accept: "application/vnd.github.v3+json",
-            "User-Agent": "freshcontext-mcp/0.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+            "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
         },
     });
     if (!res.ok) {

package/dist/adapters/scholar.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function scholarAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/secFilings.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function secFilingsAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/adapters/secFilings.js

@@ -12,7 +12,7 @@
  */
 const HEADERS = {
     "Accept": "application/json",
-    "User-Agent": "freshcontext-mcp/0.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+    "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
 };
 async function fetchSecFilings(query, maxResults = 10) {
     const today = new Date().toISOString().slice(0, 10);

package/dist/adapters/yc.d.ts

@@ -0,0 +1,2 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+export declare function ycAdapter(options: ExtractOptions): Promise<AdapterResult>;

package/dist/core/decay.d.ts

@@ -0,0 +1,5 @@
+export declare const LAMBDA: Record<string, number>;
+export declare const FUTURE_CLOCK_SKEW_TOLERANCE_MS: number;
+export declare function isMeaningfullyFutureDate(content_date: string | null, retrieved_at: string): boolean;
+export declare function calculateFreshnessScore(content_date: string | null, retrieved_at: string, adapter: string): number | null;
+export declare function scoreLabel(score: number | null): string;

package/dist/core/decision.d.ts

@@ -0,0 +1,3 @@
+import type { ContextDecisionOptions, ContextDecisionResult, CoreSignalEvaluationResult } from "./types.js";
+export declare function interpretEvaluation(evaluation: CoreSignalEvaluationResult, options?: ContextDecisionOptions): ContextDecisionResult;
+export declare function interpretEvaluations(evaluations: CoreSignalEvaluationResult[], options?: ContextDecisionOptions): ContextDecisionResult[];

package/dist/core/decision.js

@@ -125,7 +125,6 @@ export function interpretEvaluation(evaluation, options = {}) {
     ]);
     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"
@@ -153,7 +152,6 @@ export function interpretEvaluation(evaluation, options = {}) {
     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);
@@ -163,7 +161,7 @@ export function interpretEvaluation(evaluation, options = {}) {
     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) {
+    if (finalScore < 0.35) {
         return decisionResult(confidence === "low" ? "exclude" : "watch_only", reasons, warnings);
     }
     if (finalScore >= 0.55) {

package/dist/core/envelope.d.ts

@@ -0,0 +1,5 @@
+import type { FreshContext, AdapterResult, ExtractOptions, EnvelopeFormatOptions } from "./types.js";
+export declare const MAX_ENVELOPE_CONTENT_LENGTH = 20000;
+export declare function stampFreshness(result: AdapterResult, options: ExtractOptions, adapter: string): FreshContext;
+export declare function toStructuredJSON(ctx: FreshContext): object;
+export declare function formatForLLM(ctx: FreshContext, options?: EnvelopeFormatOptions): string;

package/dist/core/envelope.js

@@ -1,5 +1,13 @@
 import { calculateFreshnessScore, isMeaningfullyFutureDate, scoreLabel } from "./decay.js";
 import { looksLikeFailedAdapterContent } from "./guards.js";
+export const MAX_ENVELOPE_CONTENT_LENGTH = 20000;
+function clampEnvelopeMaxLength(maxLength) {
+    if (maxLength === 0)
+        return 0;
+    if (maxLength === undefined || !Number.isFinite(maxLength))
+        return 8000;
+    return Math.min(MAX_ENVELOPE_CONTENT_LENGTH, Math.max(1, Math.floor(maxLength)));
+}
 export function stampFreshness(result, options, adapter) {
     const retrieved_at = new Date().toISOString();
     const failedContent = looksLikeFailedAdapterContent(result.raw);
@@ -8,7 +16,7 @@ export function stampFreshness(result, options, adapter) {
     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),
+        content: result.raw.slice(0, clampEnvelopeMaxLength(options.maxLength)),
         source_url: options.url,
         content_date,
         retrieved_at,

package/dist/core/explain.d.ts

@@ -0,0 +1,12 @@
+import type { SignalConfidence } from "./types.js";
+interface ExplainSignalInput {
+    source?: string;
+    source_type?: string;
+    semantic_score: number;
+    freshness_score: number | null;
+    final_score: number;
+    confidence: SignalConfidence;
+    published_at?: string | null;
+}
+export declare function explainSignal(input: ExplainSignalInput): string;
+export {};

package/dist/core/guards.d.ts

@@ -0,0 +1 @@
+export declare function looksLikeFailedAdapterContent(raw: string): boolean;

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+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 { toReadableContextResult } from "./readable.js";
+export { prepareProvenanceReadiness } from "./provenanceReadiness.js";
+export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles } from "./sourceProfiles.js";
+export { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, verifyHaPriV2, } from "./provenance.js";
+export type { FreshContext, ExtractOptions, AdapterResult, EnvelopeFormatOptions, SignalConfidence, SignalDateConfidence, SignalContractVersion, SourceAuthorityHint, SourceDatePolicy, SourceFailurePolicy, SourceProfile, SourceProfileId, SourceSurface, ContextDecision, IntentProfileId, ContextDecisionOptions, ContextDecisionResult, HumanReadableHandoffResult, HumanReadableContextResult, SignalNormalizeOptions, FreshContextSignalInput, FreshContextSignal, FreshSignal, RankedSignal, RankOptions, ContextUtilityStatus, ContextUtilityInput, ContextUtilityResult, HaPriV2Input, HaPriV2Material, HaPriV2Result, HaPriVerificationStatus, HaPriV2VerificationResult, ProvenanceReadinessState, ProvenanceSourceIdentityCompleteness, ProvenanceTimingCompleteness, ProvenanceReadinessInput, ProvenanceReadinessOptions, ProvenanceSourceIdentityResult, ProvenanceReadinessResult, CoreSignalProvenanceOptions, CoreSignalEnvelopeResult, CoreSignalEvaluationOptions, CoreSignalEvaluationResult, } from "./types.js";

package/dist/core/index.js

@@ -7,5 +7,7 @@ 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 { toReadableContextResult } from "./readable.js";
+export { prepareProvenanceReadiness } from "./provenanceReadiness.js";
 export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles } from "./sourceProfiles.js";
 export { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, verifyHaPriV2, } from "./provenance.js";

package/dist/core/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { CoreSignalEvaluationOptions, CoreSignalEvaluationResult, FreshContextSignalInput } from "./types.js";
+export declare function evaluateSignal(input: FreshContextSignalInput, options?: CoreSignalEvaluationOptions): CoreSignalEvaluationResult;
+export declare function evaluateSignals(inputs: FreshContextSignalInput[], options?: CoreSignalEvaluationOptions): CoreSignalEvaluationResult[];

package/dist/core/pipeline.js

@@ -1,6 +1,7 @@
 import { LAMBDA, calculateFreshnessScore } from "./decay.js";
 import { formatForLLM, toStructuredJSON } from "./envelope.js";
 import { calculateHaPriV2 } from "./provenance.js";
+import { prepareProvenanceReadiness } from "./provenanceReadiness.js";
 import { rankSignal } from "./rank.js";
 import { normalizeSignal } from "./signal.js";
 import { calculateContextUtility } from "./utility.js";
@@ -79,6 +80,12 @@ export function evaluateSignal(input, options = {}) {
     const reasons = [...signal.reasons, ...utility.reasons];
     const envelope = createEnvelope(signal, freshness_score, options);
     const provenance = createProvenance(signal, options, reasons);
+    const provenance_readiness = prepareProvenanceReadiness(signal, {
+        now: options.now,
+        resultId: options.provenance?.resultId ?? signal.id,
+        semanticFingerprint: options.provenance?.semanticFingerprint ?? null,
+        engineVersion: options.provenance?.engineVersion,
+    });
     return {
         signal,
         freshness_score,
@@ -87,6 +94,7 @@ export function evaluateSignal(input, options = {}) {
         explanation: ranked.reason,
         envelope,
         provenance,
+        provenance_readiness,
         reasons,
     };
 }

package/dist/core/provenance.d.ts

@@ -0,0 +1,5 @@
+import type { HaPriV2Input, HaPriV2Result, HaPriV2VerificationResult } from "./types.js";
+export declare function canonicalizeHaPriContent(input: string): string;
+export declare function sha256Hex(input: string): string;
+export declare function calculateHaPriV2(input: HaPriV2Input): HaPriV2Result;
+export declare function verifyHaPriV2(input: HaPriV2Input, actualSig: string | null | undefined): HaPriV2VerificationResult;

package/dist/core/provenanceReadiness.d.ts

@@ -0,0 +1,2 @@
+import type { ProvenanceReadinessInput, ProvenanceReadinessOptions, ProvenanceReadinessResult } from "./types.js";
+export declare function prepareProvenanceReadiness(input: ProvenanceReadinessInput, options?: ProvenanceReadinessOptions): ProvenanceReadinessResult;

package/dist/core/provenanceReadiness.js

@@ -0,0 +1,220 @@
+import { calculateHaPriV2, canonicalizeHaPriContent, sha256Hex } from "./provenance.js";
+import { SIGNAL_CONTRACT_VERSION, normalizeSignal } from "./signal.js";
+const UNUSABLE_SOURCE_VALUES = new Set([
+    "unknown",
+    "n/a",
+    "na",
+    "none",
+    "null",
+    "undefined",
+    "not provided",
+    "tbd",
+]);
+const WEAK_SOURCE_TYPES = new Set(["", "default", "unknown", "custom"]);
+const DERIVED_SOURCE_TYPES = new Set([
+    "copy",
+    "copied",
+    "derived",
+    "excerpt",
+    "local",
+    "local_custom",
+    "local_file",
+    "local_handoff",
+    "secondary",
+    "summary",
+]);
+function cleanString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function isNormalizedSignal(input) {
+    return input.contract_version === SIGNAL_CONTRACT_VERSION;
+}
+function coerceInput(input) {
+    const value = input;
+    return {
+        ...value,
+        source: cleanString(value.source) ?? "",
+    };
+}
+function metadataString(signal, keys) {
+    for (const key of keys) {
+        const value = signal.metadata[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return null;
+}
+function metadataBoolean(signal, keys) {
+    return keys.some((key) => signal.metadata[key] === true);
+}
+function hasStringField(input, field) {
+    return cleanString(input[field]) !== null;
+}
+function sourceIdentityCompleteness(source) {
+    if (!source)
+        return "missing";
+    const lower = source.toLowerCase();
+    if (UNUSABLE_SOURCE_VALUES.has(lower))
+        return "unusable";
+    if (source.length < 4)
+        return "weak";
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source))
+        return "complete";
+    if (/^[a-z][a-z0-9+.-]*:/i.test(source))
+        return "complete";
+    if (/^[a-z]:\\/i.test(source) || source.startsWith("/") || source.startsWith("\\\\"))
+        return "complete";
+    if (source.includes("/") || source.includes("\\") || source.includes("."))
+        return "complete";
+    return source.length >= 12 ? "complete" : "weak";
+}
+function isDerivedContext(signal) {
+    const sourceType = signal.source_type.toLowerCase();
+    if (DERIVED_SOURCE_TYPES.has(sourceType))
+        return true;
+    if (metadataBoolean(signal, ["is_derived", "derived", "copied", "is_secondary"]))
+        return true;
+    return metadataString(signal, [
+        "derived_from",
+        "copied_from",
+        "original_source",
+        "origin_source",
+        "source_chain",
+    ]) !== null;
+}
+function timingCompleteness(signal, retrievedAtWasProvided) {
+    if (signal.status === "failed")
+        return "unknown";
+    if (!signal.published_at && !signal.retrieved_at)
+        return "missing";
+    if (!signal.published_at || signal.date_confidence === "unknown" || retrievedAtWasProvided === false) {
+        return "partial";
+    }
+    return "complete";
+}
+function readinessState(input) {
+    if (input.signal.status === "failed" || input.sourceCompleteness === "unusable")
+        return "unknown";
+    if (input.derived)
+        return "derived";
+    if (input.sourceCompleteness === "missing" || !input.hasCanonicalHash)
+        return "incomplete";
+    if (input.sourceCompleteness === "complete"
+        && input.timingCompleteness === "complete"
+        && !input.sourceTypeWeak) {
+        return "complete";
+    }
+    return "partial";
+}
+function canonicalContentHash(signal) {
+    return signal.content === undefined ? null : sha256Hex(canonicalizeHaPriContent(signal.content));
+}
+function prepareHaPriV2(input) {
+    if (input.signal.status === "failed") {
+        input.reasons.push("Ha-Pri v2 identity material was not prepared for failed context");
+        return null;
+    }
+    if (!input.signal.content) {
+        input.reasons.push("Ha-Pri v2 identity material needs content");
+        return null;
+    }
+    if (!input.resultId) {
+        input.reasons.push("Ha-Pri v2 identity material needs a result id or stable source identity");
+        return null;
+    }
+    if (!input.engineVersion) {
+        input.reasons.push("Ha-Pri v2 identity material needs an explicit engine version");
+        return null;
+    }
+    input.reasons.push("Ha-Pri v2 identity material prepared from caller-provided context");
+    return calculateHaPriV2({
+        resultId: input.resultId,
+        rawContent: input.signal.content,
+        semanticFingerprint: input.semanticFingerprint,
+        adapter: input.signal.source_type,
+        publishedAt: input.signal.published_at,
+        retrievedAt: input.signal.retrieved_at,
+        engineVersion: input.engineVersion,
+    });
+}
+export function prepareProvenanceReadiness(input, options = {}) {
+    const normalizedInput = isNormalizedSignal(input);
+    const signal = normalizedInput ? input : normalizeSignal(coerceInput(input), options);
+    const warnings = [];
+    const reasons = [...signal.reasons];
+    const source = cleanString(signal.source);
+    const sourceCompleteness = sourceIdentityCompleteness(source);
+    const sourceType = cleanString(signal.source_type);
+    const sourceTypeWeak = !sourceType || WEAK_SOURCE_TYPES.has(sourceType.toLowerCase());
+    const retrievedAtWasProvided = normalizedInput ? null : hasStringField(input, "retrieved_at");
+    const timeCompleteness = timingCompleteness(signal, retrievedAtWasProvided);
+    const canonicalHash = canonicalContentHash(signal);
+    const semanticFingerprint = cleanString(options.semanticFingerprint)
+        ?? metadataString(signal, ["semantic_fingerprint", "semanticFingerprint"]);
+    const semanticFingerprintHash = semanticFingerprint ? sha256Hex(semanticFingerprint) : null;
+    const resultId = cleanString(options.resultId)
+        ?? cleanString(signal.id)
+        ?? metadataString(signal, ["result_id", "resultId", "source_id", "sourceId"])
+        ?? (sourceCompleteness === "complete" ? source : null);
+    const engineVersion = cleanString(options.engineVersion);
+    const derived = isDerivedContext(signal);
+    if (sourceCompleteness === "missing")
+        warnings.push("source identity is missing");
+    if (sourceCompleteness === "weak")
+        warnings.push("source identity is weak");
+    if (sourceCompleteness === "unusable")
+        warnings.push("source identity is unusable");
+    if (sourceTypeWeak)
+        warnings.push("source_type is missing or generic");
+    if (!signal.published_at)
+        warnings.push("published_at is missing or unusable");
+    if (retrievedAtWasProvided === false)
+        warnings.push("retrieved_at was missing; normalization time was used");
+    if (signal.date_confidence === "unknown")
+        warnings.push("timing confidence is unknown");
+    if (!canonicalHash)
+        warnings.push("content is missing; canonical content hash is unavailable");
+    if (!semanticFingerprintHash)
+        reasons.push("semantic fingerprint was not provided");
+    if (derived)
+        warnings.push("context appears copied, local, secondary, or derived; preserve the upstream source chain");
+    if (signal.status === "failed")
+        warnings.push("failed context has unknown provenance readiness");
+    const haPriV2 = prepareHaPriV2({
+        signal,
+        resultId,
+        semanticFingerprint,
+        engineVersion,
+        reasons,
+    });
+    const state = readinessState({
+        signal,
+        sourceCompleteness,
+        timingCompleteness: timeCompleteness,
+        sourceTypeWeak,
+        hasCanonicalHash: canonicalHash !== null,
+        derived,
+    });
+    return {
+        state,
+        source_identity: {
+            source,
+            source_type: sourceType,
+            result_id: resultId,
+            completeness: sourceCompleteness,
+        },
+        source_type: sourceType,
+        published_at: signal.published_at,
+        retrieved_at: signal.retrieved_at,
+        timing_confidence: signal.date_confidence,
+        timing_completeness: timeCompleteness,
+        canonical_content_sha256: canonicalHash,
+        semantic_fingerprint_sha256: semanticFingerprintHash,
+        ha_pri_v2: haPriV2,
+        warnings: unique(warnings),
+        reasons: unique(reasons),
+    };
+}

package/dist/core/rank.d.ts

@@ -0,0 +1,4 @@
+import type { FreshSignal, RankOptions, RankedSignal } from "./types.js";
+export declare function clampScore(value: number): number;
+export declare function rankSignal(signal: FreshSignal, options?: RankOptions): RankedSignal;
+export declare function rankSignals(signals: FreshSignal[], options?: RankOptions): RankedSignal[];

package/dist/core/readable.d.ts

@@ -0,0 +1,2 @@
+import type { ContextDecisionResult, CoreSignalEvaluationResult, HumanReadableContextResult } from "./types.js";
+export declare function toReadableContextResult(evaluation: CoreSignalEvaluationResult, decision: ContextDecisionResult): HumanReadableContextResult;

package/dist/core/readable.js

@@ -0,0 +1,75 @@
+const MAX_READABLE_REASONS = 5;
+const HANDOFF_SAFE_REASON = "Decision and complete provenance support agent handoff.";
+const HANDOFF_UNSAFE_DECISION_REASON = "Decision does not support agent handoff.";
+const HANDOFF_UNSAFE_PROVENANCE_REASON = "Provenance is not complete enough for agent handoff.";
+const HANDOFF_SAFE_DECISIONS = new Set([
+    "use_first",
+    "cite_as_primary",
+    "cite_as_supporting",
+    "use_as_background",
+]);
+const READER_LABELS = {
+    use_first: "Use first",
+    cite_as_primary: "Primary source",
+    cite_as_supporting: "Supporting source",
+    use_as_background: "Background only",
+    needs_verification: "Needs verification",
+    needs_refresh: "Needs refresh",
+    watch_only: "Watch only",
+    exclude: "Excluded",
+};
+const SUMMARIES = {
+    use_first: "This source is strong enough to use early in the context bundle.",
+    cite_as_primary: "This source is strong enough to use as main evidence.",
+    cite_as_supporting: "This source is useful as supporting evidence.",
+    use_as_background: "This source is useful as background, but should not carry the main claim.",
+    needs_verification: "This source may be relevant, but timing, origin, or confidence needs checking.",
+    needs_refresh: "This source may be outdated for the current task and should be refreshed.",
+    watch_only: "This source may be related, but is too weak to rely on directly.",
+    exclude: "This source should not be included as trusted context.",
+};
+const ACTIONS = {
+    use_first: "Use this near the front of the selected context while preserving provenance.",
+    cite_as_primary: "Use this as main evidence while preserving citation and provenance.",
+    cite_as_supporting: "Use this to support or qualify the answer, not as the only source.",
+    use_as_background: "Keep this as background context only.",
+    needs_verification: "Do not use this as primary evidence until it is checked.",
+    needs_refresh: "Look for a newer source before using this as current evidence.",
+    watch_only: "Do not rely on this directly; keep it for monitoring or review.",
+    exclude: "Keep this out of the final model context unless a human reviews it.",
+};
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function handoffFor(evaluation, decision) {
+    if (!HANDOFF_SAFE_DECISIONS.has(decision.decision)) {
+        return {
+            safe_for_agent_handoff: false,
+            reason: HANDOFF_UNSAFE_DECISION_REASON,
+        };
+    }
+    if (evaluation.provenance_readiness.state !== "complete") {
+        return {
+            safe_for_agent_handoff: false,
+            reason: HANDOFF_UNSAFE_PROVENANCE_REASON,
+        };
+    }
+    return {
+        safe_for_agent_handoff: true,
+        reason: HANDOFF_SAFE_REASON,
+    };
+}
+export function toReadableContextResult(evaluation, decision) {
+    const why = unique([
+        ...decision.reasons,
+        evaluation.explanation,
+    ]).slice(0, MAX_READABLE_REASONS);
+    return {
+        label: READER_LABELS[decision.decision],
+        summary: SUMMARIES[decision.decision],
+        why,
+        action: ACTIONS[decision.decision],
+        warnings: [...decision.warnings],
+        handoff: handoffFor(evaluation, decision),
+    };
+}

package/dist/core/signal.d.ts

@@ -0,0 +1,3 @@
+import type { FreshContextSignal, FreshContextSignalInput, SignalNormalizeOptions } from "./types.js";
+export declare const SIGNAL_CONTRACT_VERSION: "freshcontext.signal.v1";
+export declare function normalizeSignal(input: FreshContextSignalInput, options?: SignalNormalizeOptions): FreshContextSignal;

package/dist/core/sourceProfiles.d.ts

@@ -0,0 +1,4 @@
+import type { SourceProfile, SourceProfileId } from "./types.js";
+export declare const BUILT_IN_SOURCE_PROFILES: Readonly<Record<SourceProfileId, SourceProfile>>;
+export declare function listSourceProfiles(): SourceProfile[];
+export declare function getSourceProfile(profileId: string): SourceProfile | undefined;