freshcontext-mcp 0.3.20 → 0.3.22

package/dist/types.d.ts

@@ -0,0 +1 @@
+export type { FreshContext, ExtractOptions, AdapterResult } from "./core/types.js";

package/docs/API_DESIGN.md

@@ -12,7 +12,7 @@ The REST host should expose the simplest useful path:
 
 1. User has raw retrieved signals.
 2. User sends those signals to FreshContext.
-3. Core evaluates freshness, confidence, ranking, explanation, optional envelope, and optional provenance.
+3. Core evaluates freshness, confidence, ranking, explanation, provenance readiness, optional envelope, and optional provenance.
 4. Host returns ranked context.
 5. Agent or app uses best context first.
 
@@ -122,6 +122,27 @@ Shape: `CoreSignalEvaluationResult`.
     "reason": "Strong semantic match and current freshness for blog."
   },
   "explanation": "Strong semantic match and current freshness for blog.",
+  "provenance_readiness": {
+    "state": "complete",
+    "source_identity": {
+      "source": "https://example.com/article",
+      "source_type": "blog",
+      "result_id": "sig_001",
+      "completeness": "complete"
+    },
+    "source_type": "blog",
+    "published_at": "2026-05-24T12:00:00.000Z",
+    "retrieved_at": "2026-05-24T13:00:00.000Z",
+    "timing_confidence": "high",
+    "timing_completeness": "complete",
+    "canonical_content_sha256": "abc123...",
+    "semantic_fingerprint_sha256": null,
+    "ha_pri_v2": null,
+    "warnings": [],
+    "reasons": [
+      "semantic fingerprint was not provided"
+    ]
+  },
   "envelope": {
     "context": {},
     "text": "[FRESHCONTEXT]...",
@@ -131,6 +152,8 @@ Shape: `CoreSignalEvaluationResult`.
 }
 ```
 
+`provenance_readiness` is always a Core judgment sidecar. It classifies source identity and timing completeness. It must not be used by the REST host to fetch, verify truth, reject context by policy, or change ranking.
+
 The REST host must not fetch upstream data, cache results, write D1, enforce Ha-Pri, or alter ranking policy.
 
 ## POST /v1/evaluate-batch
@@ -181,6 +204,9 @@ Evaluates and ranks multiple signals.
         "final_score": 0.85
       },
       "explanation": "Strong semantic match and current freshness for blog.",
+      "provenance_readiness": {
+        "state": "complete"
+      },
       "reasons": []
     }
   ]
@@ -342,6 +368,7 @@ Core owns:
 - timestamp/future-date/failure guards
 - freshness scoring
 - context utility sidecar
+- provenance readiness sidecar
 - default rank/explain behavior
 - optional envelope generation
 - optional Ha-Pri v2 material preparation

package/docs/CLIENT_SETUP.md

@@ -6,7 +6,7 @@ Use this guide when connecting Claude Desktop, Codex, or another MCP-compatible
 
 ## What You Should See
 
-FreshContext `0.3.19` exposes:
+FreshContext `0.3.22` exposes:
 
 ```text
 22 tools = evaluate_context + 21 read-only reference adapters
@@ -105,8 +105,8 @@ Expected smoke result:
 ```json
 {
   "ok": true,
-  "package_version": "0.3.19",
-  "server_version": "0.3.19",
+  "package_version": "0.3.22",
+  "server_version": "0.3.22",
   "tool_count": 22
 }
 ```
@@ -132,7 +132,7 @@ Some clients can use `mcp-remote`:
 }
 ```
 
-The npm/local stdio package remains the safest default client path. The hosted Worker endpoint was verified on 2026-06-11 at `0.3.19 / 22 tools` with `evaluate_context` present and returning decision-first output. Because the Worker is a separate deployment surface, re-run remote verification before claiming future package interfaces are live there.
+The npm/local stdio package remains the safest default client path. The hosted Worker endpoint was last verified on 2026-06-14 at `0.3.21 / 22 tools` with `evaluate_context` present and returning decision-first output, including `provenance_readiness`, `readable`, and `readable.handoff`. Because the Worker is a separate deployment surface, re-run remote verification before claiming future package interfaces are live there.
 
 ## ChatGPT / OpenAI Connector Boundary
 

package/docs/CODEX_MCP_USAGE.md

@@ -67,7 +67,7 @@ command = "npx"
 args = ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
 ```
 
-This remote path was verified on 2026-06-11 as a live Worker MCP endpoint exposing `0.3.19 / 22 tools`, including `evaluate_context`. That confirms Worker availability and MCP tool discovery. It does not by itself claim Codex Cloud support or guarantee every MCP client can use the remote bridge without its own client-specific setup check.
+This remote path was last verified on 2026-06-14 as a live Worker MCP endpoint exposing `0.3.21 / 22 tools`, including `evaluate_context`, `provenance_readiness`, `readable`, and `readable.handoff`. That confirms Worker availability and MCP tool discovery. It does not by itself claim Codex Cloud support or guarantee every MCP client can use the remote bridge without its own client-specific setup check.
 
 ## Verification steps
 
@@ -83,8 +83,8 @@ Expected result:
 ```json
 {
   "ok": true,
-  "package_version": "0.3.19",
-  "server_version": "0.3.19",
+  "package_version": "0.3.22",
+  "server_version": "0.3.22",
   "tool_count": 22
 }
 ```

package/docs/CORE_API.md

@@ -13,14 +13,21 @@ Import stable Core functions from:
 ```ts
 import {
   calculateFreshnessScore,
+  evaluateSignals,
   formatForLLM,
+  getSourceProfile,
+  interpretEvaluations,
   looksLikeFailedAdapterContent,
+  normalizeSignal,
+  prepareProvenanceReadiness,
   scoreLabel,
   stampFreshness,
   toStructuredJSON,
-} from "./src/core/index.js";
+} from "freshcontext-mcp/core";
 ```
 
+The `freshcontext-mcp/core` subpath is the direct Core import boundary inside the current MCP package. It does not create a standalone `freshcontext-core` package yet; that remains a future package-split lane.
+
 ### Envelope
 
 - `stampFreshness(result, options, adapter)` creates a `FreshContext` object from adapter output.
@@ -55,7 +62,7 @@ It does not fetch, cache, write D1, inspect Worker bindings, know MCP tool schem
 
 `evaluateSignals` evaluates each input and returns evaluations sorted by existing `rankSignal` final score, preserving input order when scores tie. Context utility is returned as a sidecar and does not replace `final_score`.
 
-Context utility is returned as sidecar output in the current pipeline; it does not replace or modify the default `rankSignal` / `evaluateSignals` ordering. A future pass may add an explicit utility-weighted ranking mode.
+Context utility is returned as sidecar output in the current pipeline. It does not replace or modify the default `rankSignal` / `evaluateSignals` ordering, and it does not control default decision labels. A future pass may add an explicit utility-weighted ranking or decision-support mode.
 
 Local demo:
 
@@ -76,9 +83,9 @@ The demo reads caller-provided JSON with `profile`, `intent`, and `signals`, the
 
 These types describe the stable envelope and adapter result contract.
 
-## Signal Contract v1
-
-Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context before it is ranked, wrapped, stored, judged by `evaluate_context`, or passed to an agent workflow.
+## Signal Contract v1
+
+Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context before it is ranked, wrapped, stored, judged by `evaluate_context`, or passed to an agent workflow.
 
 Public exports:
 
@@ -90,11 +97,11 @@ Public exports:
 - `SignalContractVersion`
 - `SignalNormalizeOptions`
 
-`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias. Normalization clears invalid or meaningfully future-dated timestamps, marks failed/error-looking content as `status: "failed"`, clamps `semantic_score` into `0..1`, and records normalization reasons.
-
-Future context signals and control signals are optional future metadata layers, not replacements for Signal Contract v1 and not required public input fields today.
-
-See [Signal Contract v1](./SIGNAL_CONTRACT.md).
+`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias. Normalization clears invalid or meaningfully future-dated timestamps, marks failed/error-looking content as `status: "failed"`, clamps `semantic_score` into `0..1`, and records normalization reasons.
+
+Future context signals and control signals are optional future metadata layers, not replacements for Signal Contract v1 and not required public input fields today.
+
+See [Signal Contract v1](./SIGNAL_CONTRACT.md).
 
 ## Source Profiles
 
@@ -112,9 +119,11 @@ Public exports:
 - `SourceFailurePolicy`
 - `SourceSurface`
 
-They reframe the 21 named adapter tools as reference adapters and source-profile examples instead of the product identity. The MCP server also exposes `evaluate_context` as the generic caller-provided context evaluation path. Source Profiles do not implement `retrieve(...)`, Operator mode, adapter selection, crawling, local file search, or any host/runtime behavior.
-
-## Decision Helper
+They reframe the 21 named adapter tools as reference adapters and source-profile examples instead of the product identity. The MCP server also exposes `evaluate_context` as the generic caller-provided context evaluation path. Source Profiles do not implement `retrieve(...)`, Operator mode, adapter selection, crawling, local file search, or any host/runtime behavior.
+
+Current built-in profiles include canonical docs, code activity, social pulse, academic research, market/finance, jobs, government/regulatory material, company intelligence, product research, composite landscapes, multi-agent handoff context, and local/custom caller-provided context.
+
+## Decision Helper
 
 The decision helper translates a Core evaluation result into user-facing action meaning.
 
@@ -154,6 +163,51 @@ FreshContext decisions judge citation readiness, context usefulness, freshness,
 
 Demo output will be updated separately so presentation stays separate from Core decision logic.
 
+## Human-Readable Output
+
+The human-readable output helper adds a small reader-facing layer on top of existing Core evaluations and decisions.
+
+Public exports:
+
+- `toReadableContextResult(evaluation, decision)`
+- `HumanReadableContextResult`
+
+The helper returns a bounded object with:
+
+- `label`
+- `summary`
+- `why`
+- `action`
+- `warnings`
+
+This is additive. It does not change machine decisions, ranking, freshness math, utility math, Source Profiles, envelopes, provenance, or host behavior. Utility may appear in `why` when it is already part of the decision reasons, but utility still does not control default decision labels.
+
+Example structured result fragment:
+
+```json
+{
+  "decision": "cite_as_primary",
+  "label": "Cite as primary",
+  "readable": {
+    "label": "Primary source",
+    "summary": "This source is strong enough to use as main evidence.",
+    "why": [
+      "Strong semantic match and current freshness for arxiv.",
+      "source profile academic_research uses lenient date policy",
+      "intent profile citation_check selected"
+    ],
+    "action": "Use this as main evidence while preserving citation and provenance.",
+    "warnings": [
+      "FreshContext judges citation readiness and context usefulness; it does not certify truth."
+    ]
+  }
+}
+```
+
+FreshContext does not certify truth. It records why context was used, supported, questioned, refreshed, watched, or excluded before it reaches a model.
+
+See [Human-Readable Output Contract](./HUMAN_READABLE_OUTPUT_CONTRACT.md).
+
 ## Public Ranking Primitives
 
 The ranking primitives are public, but consumers should treat their score scales carefully:
@@ -175,7 +229,7 @@ Ranking combines semantic relevance and freshness into a deterministic order. It
 
 ## Experimental Utility Primitive
 
-The context-conditioned utility primitive is pure and tested, but it is not production-wired into MCP ranking, Worker feeds, Store scoring, or runtime behavior.
+The context-conditioned utility primitive is pure and tested. It is surfaced in Core evaluation output and decision reasons, but it does not control default ranking or decision labels.
 
 Experimental exports:
 
@@ -184,7 +238,7 @@ Experimental exports:
 - `ContextUtilityInput`
 - `ContextUtilityResult`
 
-These are pure Core math. They are now connected inside `evaluateSignal` as sidecar utility output, but they are not production-wired into MCP ranking, Worker feeds, Store scoring, or runtime behavior.
+These are pure Core math. They are now connected inside `evaluateSignal` as sidecar utility output and explanatory material, but they are not production-wired into MCP ranking, Worker feeds, Store scoring, or default decision thresholds.
 
 ## Provenance Helpers
 
@@ -200,6 +254,16 @@ Ha-Pri v2 is available as pure Core helper functionality:
 
 `evaluateSignal` can optionally prepare Ha-Pri v2 material when `includeProvenance` is set and required input material is present. Core does not persist provenance, add D1 columns, verify rows on read, reject rows, or replace Worker Ha-Pri v1 behavior.
 
+Provenance readiness is available as a pure Core sidecar:
+
+- `prepareProvenanceReadiness(input, options?)`
+- `ProvenanceReadinessState`
+- `ProvenanceReadinessResult`
+
+It classifies caller-provided signal provenance as `complete`, `partial`, `incomplete`, `unknown`, or `derived`. The result exposes source identity completeness, timing completeness, normalized source and timestamp fields, canonical content hash material, optional semantic fingerprint hash material, optional Ha-Pri v2 identity material when the caller supplies enough inputs, warnings, and reasons.
+
+`provenance_readiness` is included additively on `evaluateSignal` results and in the structured `evaluate_context` JSON result. It does not fetch, crawl, scrape, read folders, call adapters, change ranking, change decisions, certify truth, or enforce rejection policy.
+
 ## Internal, Policy, and Compatibility Exports
 
 - `clampScore` is an internal ranking helper. It is currently exported for tests and utility use, but it should not be presented as a primary buyer-facing API.

package/docs/CORE_MCP_BOUNDARY.md

@@ -50,18 +50,27 @@ Worker/site surfaces own deployment concerns:
 
 Live today:
 
-- npm package: `freshcontext-mcp@0.3.19`
+- npm package: `freshcontext-mcp@0.3.21`
 - MCP stdio server and published binary: `freshcontext-mcp`
+- Core subpath export: `freshcontext-mcp/core`
 - `evaluate_context` MCP tool for caller-provided candidate context
 - 21 named read-only reference adapters
 - Core signal evaluation
 - Source Profiles
-- Decision Helper
-- adapter registry metadata
+- Decision Helper
+- human-readable `readable` output on structured `evaluate_context` results
+- provenance readiness and readable handoff safety
+- adapter registry metadata
 - arXiv signal-to-decision proof
 - bring-your-own-context local demos
 - Trust Scanner release gate
 
+Network boundary:
+
+- `evaluate_context` does not fetch, crawl, scrape, browse, read folders, or call adapters.
+- The 21 named reference adapters are optional read-only network tools and use network access only when invoked.
+- FreshContext Core remains the no-network judgment layer.
+
 Not live today:
 
 - standalone Core npm package
@@ -78,7 +87,7 @@ Not live today:
 The safe split path is staged:
 
 1. Keep `freshcontext-mcp` stable for current users.
-2. Maintain Core as a pure internal export surface.
+2. Maintain Core as a pure package subpath export surface.
 3. Audit Core dependencies, Node/browser compatibility, and API stability.
 4. Publish a standalone Core package only after compatibility tests exist.
 5. Make `freshcontext-mcp` depend on the standalone Core package.

package/docs/FUTURE_LANES.md

@@ -6,16 +6,16 @@ FreshContext is live today as an integrated MCP/Core package. Future work should
 
 The current package boundary is documented in [Core / MCP Boundary](./CORE_MCP_BOUNDARY.md). Treat MCP as the first live host over FreshContext Core, not as the whole product identity.
 
-## Current Live Boundary
-
-Live today:
-
-- npm package: `freshcontext-mcp@0.3.19`
-- MCP stdio server
-- `evaluate_context` MCP tool for caller-provided candidate context
-- Signal Contract v1 as the stable candidate-context input shape
-- 21 read-only reference adapters
-- Core signal evaluation
+## Current Live Boundary
+
+Live today:
+
+- npm package: `freshcontext-mcp@0.3.21`
+- MCP stdio server
+- `evaluate_context` MCP tool for caller-provided candidate context
+- Signal Contract v1 as the stable candidate-context input shape
+- 21 read-only reference adapters
+- Core signal evaluation
 - Source Profiles
 - Decision Helper
 - adapter registry metadata
@@ -30,32 +30,32 @@ Not live today:
 - automatic local file, folder, or PDF scanning
 - hosted dashboard or billing
 - hard Ha-Pri v2 production enforcement
-- standalone Core SDK package
-- full adapter ingestion
-
-## Phase 0: Stabilize The Signal Contract
-
-Goal:
-
-```text
-Treat Signal Contract v1 as the stable input boundary for FreshContext.
-```
-
-Current contract:
-
-```text
-title + content + source + source_type + published_at + retrieved_at + semantic_score
-```
-
-This is live today. It is not the same thing as future context signals or control signals.
-
-Tasks in this lane should document examples, invalid-input behavior, and normalization expectations. Do not expand required fields unless tests prove the new metadata improves decisions.
-
-Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals belong to later Decision Layer upgrades. They should remain optional metadata, not public required fields.
-
-## Lane 1: Client Setup Reliability
-
-Goal:
+- standalone Core SDK package
+- full adapter ingestion
+
+## Phase 0: Stabilize The Signal Contract
+
+Goal:
+
+```text
+Treat Signal Contract v1 as the stable input boundary for FreshContext.
+```
+
+Current contract:
+
+```text
+title + content + source + source_type + published_at + retrieved_at + semantic_score
+```
+
+This is live today. It is not the same thing as future context signals or control signals.
+
+Tasks in this lane should document examples, invalid-input behavior, and normalization expectations. Do not expand required fields unless tests prove the new metadata improves decisions.
+
+Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals belong to later Decision Layer upgrades. They should remain optional metadata, not public required fields.
+
+## Lane 1: Client Setup Reliability
+
+Goal:
 
 ```text
 Make Claude, Codex, and MCP-compatible clients connect reliably to the published package.
@@ -134,19 +134,19 @@ Hard boundary:
 Consent-first design. No automatic folder scanning or background file reading.
 ```
 
-## Lane 6: Decision Layer Upgrade
-
-Goal:
+## Lane 6: Decision Layer Upgrade
+
+Goal:
 
 ```text
 Make decisions more useful without silently changing ranking.
 ```
 
-Possible inputs include context utility, control signal, future context signal, ingestion quality, structure preservation, provenance confidence, confidence tiers, and source-profile-specific thresholds.
-
-These are optional future metadata upgrades on top of Signal Contract v1. They should only be exposed when they make decisions clearer without making the caller-facing contract harder to use.
+Possible inputs include context utility, control signal, future context signal, ingestion quality, structure preservation, provenance confidence, confidence tiers, and source-profile-specific thresholds.
+
+These are optional future metadata upgrades on top of Signal Contract v1. They should only be exposed when they make decisions clearer without making the caller-facing contract harder to use.
 
-Do not make `utility.score` affect ranking by default without a dedicated ranking policy pass.
+Do not make `utility.score` affect ranking or decision labels by default without a dedicated policy pass.
 
 ## Lane 7: Ha-Pri v2 Production Path