freshcontext-mcp 0.3.23 → 0.4.0

package/README.md

@@ -170,7 +170,7 @@ FreshContext does not certify truth. It records why context was used, supported,
 
 `evaluate_context` does not fetch URLs, crawl, scrape, browse, read folders, or call adapters. It only evaluates candidate context the caller provides.
 
-Current boundary: `evaluate_context` is part of the npm/local stdio MCP server prepared for `0.3.22`. The hosted Cloudflare Worker MCP endpoint was last verified separately at `0.3.22 / 22 tools`. The Worker remains a separate deployment surface, so future package interfaces should be re-verified remotely before being claimed live.
+Current boundary: `evaluate_context` is part of the npm/local stdio MCP server prepared for `0.4.0`. The hosted Cloudflare Worker MCP endpoint was last verified separately at `0.4.0 / 22 tools`. The Worker remains a separate deployment surface, so future package interfaces should be re-verified remotely before being claimed live.
 
 ### Network Boundary
 

package/dist/adapters/arxiv.js

@@ -1,5 +1,5 @@
 import { validateUrl } from "../security.js";
-const USER_AGENT = "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)";
+const USER_AGENT = "freshcontext-mcp/0.4.0 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)";
 const DEFAULT_ARXIV_SIGNAL_SCORE = 0.8;
 function buildArxivApiUrl(input, maxResults = 10) {
     const trimmed = input.trim();

package/dist/adapters/finance.js

@@ -30,7 +30,7 @@ async function fetchStooqQuote(ticker) {
     const url = `https://stooq.com/q/l/?s=${encodeURIComponent(stooqSymbol.toLowerCase())}&f=sd2t2ohlcv&h&e=json`;
     const res = await fetch(url, {
         headers: {
-            "User-Agent": "freshcontext-mcp/0.3.21",
+            "User-Agent": "freshcontext-mcp/0.4.0",
             "Accept": "application/json",
         },
     });

package/dist/adapters/gdelt.js

@@ -11,7 +11,7 @@
  */
 const HEADERS = {
     "Accept": "application/json",
-    "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+    "User-Agent": "freshcontext-mcp/0.4.0 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
 };
 function parseGdeltDate(raw) {
     if (!raw)

package/dist/adapters/gebiz.js

@@ -20,7 +20,7 @@ const DATASET_ID = "d_acde1106003906a75c3fa052592f2fcb";
 const BASE_URL = "https://data.gov.sg/api/action/datastore_search";
 const HEADERS = {
     "Accept": "application/json",
-    "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+    "User-Agent": "freshcontext-mcp/0.4.0 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
 };
 function formatDate(raw) {
     if (!raw)

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.21", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.4.0", "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.21", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.4.0", "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.21", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.4.0", "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.21", "Accept": "application/json" },
+        headers: { "User-Agent": "freshcontext-mcp/0.4.0", "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.21" } });
+    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.4.0" } });
     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.21" } });
+    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.4.0" } });
     if (!commentsRes.ok)
         throw new Error(`HN comments ${commentsRes.status}`);
     const commentsData = await commentsRes.json();

package/dist/adapters/reddit.js

@@ -28,7 +28,7 @@ export async function redditAdapter(options) {
     const safeUrl = validateUrl(apiUrl, "reddit");
     const res = await fetch(safeUrl, {
         headers: {
-            "User-Agent": "freshcontext-mcp/0.3.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+            "User-Agent": "freshcontext-mcp/0.4.0 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
             "Accept": "application/json",
         },
     });

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.21 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+            "User-Agent": "freshcontext-mcp/0.4.0 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
         },
     });
     if (!res.ok) {

package/dist/adapters/secFilings.js

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

package/dist/core/decay.d.ts

@@ -3,3 +3,6 @@ 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;
+export type StalenessVerdict = "fresh" | "aging" | "stale" | "unknown";
+export declare function stalenessVerdict(score: number | null): StalenessVerdict;
+export declare function computeRevalidateAfter(content_date: string | null, retrieved_at: string, adapter: string): string | null;

package/dist/core/decay.js

@@ -1,6 +1,13 @@
 // Spec-compliant exponential DAR model.
 // Higher lambda = data goes stale faster. Half-life formula: t1/2 = ln(2) / lambda.
-// Lambda is measured per hour and mirrors the Worker/D1 intelligence engine.
+// Lambda is measured per hour.
+//
+// CANONICAL SOURCE OF DECAY POLICY. This is the single definition of LAMBDA in the
+// codebase. Core (pipeline, sourceProfiles, freshness scoring) and the Worker
+// intelligence module (via the core/edge boundary) both derive from it — neither
+// keeps its own copy. To tune a source's decay, change it here and only here. The
+// single-source guard (tests/lambdaSingleSource.test.ts) goes red if a second
+// `const LAMBDA` table is ever reintroduced anywhere in runtime source.
 export const LAMBDA = {
     hackernews: 0.050,
     reddit: 0.010,
@@ -59,3 +66,35 @@ export function scoreLabel(score) {
         return "verify before acting";
     return "use with caution";
 }
+// Derived from the SAME score buckets as scoreLabel, not a second decay system.
+// "fresh" merges scoreLabel's "current"/"reliable" (score >= 70); "aging" matches
+// "verify before acting" (>= 50); "stale" matches "use with caution" (< 50). The
+// 50-point line is also where computeRevalidateAfter is anchored below — crossing
+// 50 is the one staleness boundary, expressed two ways (a verdict and a timestamp).
+export function stalenessVerdict(score) {
+    if (score === null)
+        return "unknown";
+    if (score >= 70)
+        return "fresh";
+    if (score >= 50)
+        return "aging";
+    return "stale";
+}
+// The timestamp at which this content's freshness_score would cross the staleness
+// boundary (score = 50). Since 100 * e^(-lambda*t) = 50 solves to t = ln(2)/lambda
+// — exactly one half-life — revalidate_after is always content_date + half-life.
+// Uses the same null/future-date guards as calculateFreshnessScore so the two
+// stay in lockstep: staleness === "unknown" if and only if revalidate_after === null.
+export function computeRevalidateAfter(content_date, retrieved_at, adapter) {
+    if (!content_date)
+        return null;
+    const published = new Date(content_date).getTime();
+    const retrieved = new Date(retrieved_at).getTime();
+    if (isNaN(published) || isNaN(retrieved))
+        return null;
+    if (published - retrieved > FUTURE_CLOCK_SKEW_TOLERANCE_MS)
+        return null;
+    const lambda = LAMBDA[adapter] ?? LAMBDA.default;
+    const halfLifeHours = Math.log(2) / lambda;
+    return new Date(published + halfLifeHours * 60 * 60 * 1000).toISOString();
+}

package/dist/core/decision.d.ts

@@ -1,3 +1,19 @@
-import type { ContextDecisionOptions, ContextDecisionResult, CoreSignalEvaluationResult } from "./types.js";
+import type { ContextDecision, ContextDecisionOptions, ContextDecisionResult, CoreSignalEvaluationResult, IntentProfileId, SourceProfileId } from "./types.js";
+/**
+ * Deterministic identity for a single decision (a "verdict").
+ *
+ * Derived only from the inputs that determine the decision itself: signal
+ * identity, source, the decision label, and profile selection. Deliberately
+ * EXCLUDES utility and provenance_readiness, which must stay free to vary
+ * without changing what verdict this is — mirrors the existing
+ * "utility/provenance_readiness does not control decision labels" rule.
+ *
+ * Re-evaluating identical inputs always yields the same verdict_id. It is a
+ * fingerprint, not a random id, so any caller can recompute and recognize it
+ * later without FreshContext having to store an id-issuing table. This is
+ * the id a future verification event would reference when resolving a
+ * needs_verification (or similar) decision into a cleared state.
+ */
+export declare function computeVerdictId(evaluation: CoreSignalEvaluationResult, decision: ContextDecision, sourceProfileId: SourceProfileId | undefined, intentProfile: IntentProfileId | undefined): string;
 export declare function interpretEvaluation(evaluation: CoreSignalEvaluationResult, options?: ContextDecisionOptions): ContextDecisionResult;
 export declare function interpretEvaluations(evaluations: CoreSignalEvaluationResult[], options?: ContextDecisionOptions): ContextDecisionResult[];

package/dist/core/decision.js

@@ -1,6 +1,8 @@
+import { sha256Hex } from "./provenance.js";
 import { getSourceProfile } from "./sourceProfiles.js";
 const CITATION_INTENTS = new Set(["citation_check", "student_research"]);
 const STRICT_REFRESH_PROFILES = new Set(["market_finance", "jobs_opportunities"]);
+const VERDICT_ID_VERSION = "FRESHCONTEXT_VERDICT_V1";
 function resolveSourceProfile(profile) {
     if (!profile)
         return undefined;
@@ -18,6 +20,26 @@ function hasFailureReason(evaluation) {
 function isCitationIntent(intent) {
     return intent !== undefined && CITATION_INTENTS.has(intent);
 }
+// Pass 21: decision-time clock. Honors options.now for deterministic verdicts,
+// falls back to wall time. Never recomputed at read.
+function computeEvaluatedAt(now) {
+    if (now === undefined)
+        return new Date().toISOString();
+    const date = typeof now === "string" ? new Date(now) : now;
+    return date.toISOString();
+}
+// Pass 21: revalidate_after = evaluated_at + 1.0 × source profile half-life.
+// The half-life is the literal inflection where the source has lost half its
+// freshness signal value, the one number on the decay curve the source profile
+// is calibrated to express. Explicit null when no source profile basis exists
+// — never a fabricated timestamp.
+function computeRevalidateAfter(evaluatedAt, sourceProfile) {
+    if (!sourceProfile)
+        return null;
+    const baseMs = new Date(evaluatedAt).getTime();
+    const halfLifeMs = sourceProfile.half_life_hours * 60 * 60 * 1000;
+    return new Date(baseMs + halfLifeMs).toISOString();
+}
 function nonAdviceWarnings(intent) {
     switch (intent) {
         case "citation_check":
@@ -35,13 +57,46 @@ function nonAdviceWarnings(intent) {
             return [];
     }
 }
-function decisionResult(decision, reasons, warnings) {
+/**
+ * Deterministic identity for a single decision (a "verdict").
+ *
+ * Derived only from the inputs that determine the decision itself: signal
+ * identity, source, the decision label, and profile selection. Deliberately
+ * EXCLUDES utility and provenance_readiness, which must stay free to vary
+ * without changing what verdict this is — mirrors the existing
+ * "utility/provenance_readiness does not control decision labels" rule.
+ *
+ * Re-evaluating identical inputs always yields the same verdict_id. It is a
+ * fingerprint, not a random id, so any caller can recompute and recognize it
+ * later without FreshContext having to store an id-issuing table. This is
+ * the id a future verification event would reference when resolving a
+ * needs_verification (or similar) decision into a cleared state.
+ */
+export function computeVerdictId(evaluation, decision, sourceProfileId, intentProfile) {
+    const signal = evaluation.signal;
+    const basis = [
+        VERDICT_ID_VERSION,
+        `signal_id=${signal.id ?? "null"}`,
+        `source=${signal.source}`,
+        `source_type=${signal.source_type}`,
+        `published_at=${signal.published_at ?? "null"}`,
+        `decision=${decision}`,
+        `source_profile=${sourceProfileId ?? "null"}`,
+        `intent_profile=${intentProfile ?? "null"}`,
+    ].join("\n");
+    return sha256Hex(basis);
+}
+function decisionResult(decision, reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter) {
     const copyReasons = unique(reasons);
     const copyWarnings = unique(warnings);
+    const verdict_id = computeVerdictId(evaluation, decision, sourceProfileId, intentProfile);
     switch (decision) {
         case "use_first":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 label: "Use first",
                 meaning: "This is strong, current context for the task.",
                 action: "Use this near the top of the context bundle.",
@@ -51,6 +106,9 @@ function decisionResult(decision, reasons, warnings) {
         case "cite_as_primary":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -60,6 +118,9 @@ function decisionResult(decision, reasons, warnings) {
         case "cite_as_supporting":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -69,6 +130,9 @@ function decisionResult(decision, reasons, warnings) {
         case "use_as_background":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -78,6 +142,9 @@ function decisionResult(decision, reasons, warnings) {
         case "needs_verification":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -87,6 +154,9 @@ function decisionResult(decision, reasons, warnings) {
         case "needs_refresh":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -96,6 +166,9 @@ function decisionResult(decision, reasons, warnings) {
         case "watch_only":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -105,6 +178,9 @@ function decisionResult(decision, reasons, warnings) {
         case "exclude":
             return {
                 decision,
+                verdict_id,
+                evaluated_at: evaluatedAt,
+                revalidate_after: revalidateAfter,
                 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.",
@@ -117,6 +193,11 @@ export function interpretEvaluation(evaluation, options = {}) {
     const sourceProfile = resolveSourceProfile(options.sourceProfile);
     const sourceProfileId = profileId(sourceProfile);
     const intentProfile = options.intentProfile;
+    // Pass 21: decision-time clock. Computed once here and passed through to the
+    // factory — never recomputed at read time. revalidate_after is explicit null
+    // when no source profile is available (no decay basis = no honest hint).
+    const evaluatedAt = computeEvaluatedAt(options.now);
+    const revalidateAfter = computeRevalidateAfter(evaluatedAt, sourceProfile);
     const reasons = unique([
         evaluation.explanation,
         ...evaluation.signal.reasons,
@@ -136,38 +217,38 @@ export function interpretEvaluation(evaluation, options = {}) {
         reasons.push(`intent profile ${intentProfile} selected`);
     }
     if (isFailed) {
-        return decisionResult("exclude", reasons, warnings);
+        return decisionResult("exclude", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     if (sourceProfileId
         && STRICT_REFRESH_PROFILES.has(sourceProfileId)
         && (freshnessScore === null || freshnessScore < 50)) {
-        return decisionResult("needs_refresh", reasons, warnings);
+        return decisionResult("needs_refresh", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     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(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
         }
-        return decisionResult("needs_verification", reasons, warnings);
+        return decisionResult("needs_verification", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     if (finalScore >= 0.85
         && freshnessScore !== null
         && freshnessScore >= 70
         && confidence === "high") {
         if (sourceProfile?.authority_hint === "high" && isCitationIntent(intentProfile)) {
-            return decisionResult("cite_as_primary", reasons, warnings);
+            return decisionResult("cite_as_primary", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
         }
-        return decisionResult("use_first", reasons, warnings);
+        return decisionResult("use_first", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     if (finalScore >= 0.55 && freshnessScore !== null && freshnessScore < 50) {
-        return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings);
+        return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     if (finalScore < 0.35) {
-        return decisionResult(confidence === "low" ? "exclude" : "watch_only", reasons, warnings);
+        return decisionResult(confidence === "low" ? "exclude" : "watch_only", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
     if (finalScore >= 0.55) {
-        return decisionResult("use_as_background", reasons, warnings);
+        return decisionResult("use_as_background", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
     }
-    return decisionResult("watch_only", reasons, warnings);
+    return decisionResult("watch_only", reasons, warnings, evaluation, sourceProfileId, intentProfile, evaluatedAt, revalidateAfter);
 }
 export function interpretEvaluations(evaluations, options = {}) {
     return evaluations.map((evaluation) => interpretEvaluation(evaluation, options));

package/dist/core/edge.d.ts

@@ -0,0 +1,3 @@
+export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles, } from "./sourceProfiles.js";
+export type { SourceProfile, SourceProfileId } from "./types.js";

package/dist/core/edge.js

@@ -0,0 +1,18 @@
+// edge.ts — Edge-safe Core math boundary (Pass 20-A).
+//
+// Re-exports ONLY Core modules whose entire transitive import graph is free
+// of node:crypto, so the Worker — or any runtime without nodejs_compat — can
+// pull the math without dragging in Node-only APIs.
+//
+// Guard: tests/coreEdgeBoundary.test.ts walks this barrel's transitive value-
+// import graph and fails if anything reachable from here imports node:crypto.
+// Adding a new export here MUST keep that test green.
+//
+// Cleared-but-deliberately-deferred (verified crypto-free in Phase 0, kept
+// out for now because no consumer needs them at the edge yet):
+//   guards.ts, rank.ts, utility.ts, signal.ts
+// Widening the boundary before there is a real consumer just creates more
+// contract to maintain. Add here only when a Worker or external consumer
+// actually needs them at the edge — and re-run the guard test at that moment.
+export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles, } from "./sourceProfiles.js";

package/dist/core/envelope.js

@@ -1,4 +1,4 @@
-import { calculateFreshnessScore, isMeaningfullyFutureDate, scoreLabel } from "./decay.js";
+import { calculateFreshnessScore, computeRevalidateAfter, isMeaningfullyFutureDate, scoreLabel, stalenessVerdict } from "./decay.js";
 import { looksLikeFailedAdapterContent } from "./guards.js";
 export const MAX_ENVELOPE_CONTENT_LENGTH = 20000;
 function clampEnvelopeMaxLength(maxLength) {
@@ -15,6 +15,8 @@ export function stampFreshness(result, options, adapter) {
     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);
+    const staleness = stalenessVerdict(freshness_score);
+    const revalidate_after = computeRevalidateAfter(content_date, retrieved_at, adapter);
     return {
         content: result.raw.slice(0, clampEnvelopeMaxLength(options.maxLength)),
         source_url: options.url,
@@ -23,6 +25,8 @@ export function stampFreshness(result, options, adapter) {
         freshness_confidence,
         freshness_score,
         adapter,
+        staleness,
+        revalidate_after,
     };
 }
 export function toStructuredJSON(ctx) {
@@ -34,6 +38,8 @@ export function toStructuredJSON(ctx) {
             freshness_confidence: ctx.freshness_confidence,
             freshness_score: ctx.freshness_score,
             adapter: ctx.adapter,
+            staleness: ctx.staleness,
+            revalidate_after: ctx.revalidate_after,
         },
         content: ctx.content,
     };
@@ -47,6 +53,9 @@ export function formatForLLM(ctx, options = {}) {
     const scoreLine = ctx.freshness_score !== null
         ? `Score: ${ctx.freshness_score}/100 (${scoreLabel(ctx.freshness_score)})`
         : `Score: unknown`;
+    const stalenessLine = ctx.revalidate_after !== null
+        ? `Staleness: ${ctx.staleness} (revalidate by ${ctx.revalidate_after})`
+        : `Staleness: ${ctx.staleness}`;
     const textEnvelope = [
         `[FRESHCONTEXT]`,
         `Source: ${ctx.source_url}`,
@@ -54,6 +63,7 @@ export function formatForLLM(ctx, options = {}) {
         `Retrieved: ${ctx.retrieved_at}`,
         `Confidence: ${ctx.freshness_confidence}`,
         `${scoreLine}`,
+        `${stalenessLine}`,
         `---`,
         ctx.content,
         `[/FRESHCONTEXT]`,

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
-export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { LAMBDA, calculateFreshnessScore, scoreLabel, stalenessVerdict, computeRevalidateAfter } from "./decay.js";
+export type { StalenessVerdict } from "./decay.js";
 export { looksLikeFailedAdapterContent } from "./guards.js";
 export { stampFreshness, toStructuredJSON, formatForLLM } from "./envelope.js";
 export { explainSignal } from "./explain.js";
@@ -6,9 +7,9 @@ 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 { interpretEvaluation, interpretEvaluations, computeVerdictId } 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";
+export { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, buildHaPriPayload, buildHaPriPayloadV3, 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, HaPriV3Input, HaPriV2Material, HaPriV2Result, HaPriVerificationStatus, HaPriV2VerificationResult, ProvenanceReadinessState, ProvenanceSourceIdentityCompleteness, ProvenanceTimingCompleteness, ProvenanceReadinessInput, ProvenanceReadinessOptions, ProvenanceSourceIdentityResult, ProvenanceReadinessResult, CoreSignalProvenanceOptions, CoreSignalEnvelopeResult, CoreSignalEvaluationOptions, CoreSignalEvaluationResult, } from "./types.js";

package/dist/core/index.js

@@ -1,4 +1,4 @@
-export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { LAMBDA, calculateFreshnessScore, scoreLabel, stalenessVerdict, computeRevalidateAfter } from "./decay.js";
 export { looksLikeFailedAdapterContent } from "./guards.js";
 export { stampFreshness, toStructuredJSON, formatForLLM } from "./envelope.js";
 export { explainSignal } from "./explain.js";
@@ -6,8 +6,8 @@ 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 { interpretEvaluation, interpretEvaluations, computeVerdictId } 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 { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, buildHaPriPayload, buildHaPriPayloadV3, verifyHaPriV2, } from "./provenance.js";

package/dist/core/pipeline.js

@@ -1,4 +1,4 @@
-import { LAMBDA, calculateFreshnessScore } from "./decay.js";
+import { LAMBDA, calculateFreshnessScore, computeRevalidateAfter, stalenessVerdict } from "./decay.js";
 import { formatForLLM, toStructuredJSON } from "./envelope.js";
 import { calculateHaPriV2 } from "./provenance.js";
 import { prepareProvenanceReadiness } from "./provenanceReadiness.js";
@@ -22,6 +22,13 @@ function envelopeConfidence(signal) {
 function createEnvelope(signal, freshnessScore, options) {
     if (!options.includeEnvelope || signal.content === undefined)
         return undefined;
+    // Mirrors the same failed/unknown override applied to freshnessScore at the
+    // call site, so staleness === "unknown" iff revalidate_after === null holds
+    // here too (computeRevalidateAfter's own date guard alone wouldn't catch a
+    // failed-status signal that still carries a parseable published_at).
+    const revalidate_after = signal.status === "failed" || signal.date_confidence === "unknown"
+        ? null
+        : computeRevalidateAfter(signal.published_at, signal.retrieved_at, signal.source_type);
     const ctx = {
         content: signal.content.slice(0, options.envelopeMaxLength ?? 8000),
         source_url: signal.source,
@@ -30,6 +37,8 @@ function createEnvelope(signal, freshnessScore, options) {
         freshness_confidence: envelopeConfidence(signal),
         freshness_score: freshnessScore,
         adapter: signal.source_type,
+        staleness: stalenessVerdict(freshnessScore),
+        revalidate_after,
     };
     return {
         context: ctx,

package/dist/core/provenance.d.ts

@@ -1,5 +1,7 @@
-import type { HaPriV2Input, HaPriV2Result, HaPriV2VerificationResult } from "./types.js";
+import type { HaPriV2Input, HaPriV3Input, 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 buildHaPriPayload(input: HaPriV2Input): string;
+export declare function buildHaPriPayloadV3(input: HaPriV3Input): string;
 export declare function verifyHaPriV2(input: HaPriV2Input, actualSig: string | null | undefined): HaPriV2VerificationResult;