freshcontext-mcp 0.3.20 → 0.3.22

package/docs/SIGNAL_CONTRACT.md

@@ -1,30 +1,32 @@
-# FreshContext Signal Contract v1
-
-FreshContext Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context that should be judged before it reaches a model.
-
-In plain terms:
-
-```text
-candidate context -> Signal Contract v1 -> FreshContext judgment -> decision-ready context
-```
-
-The Signal Contract is live product architecture. It is used by Core normalization, `evaluate_context`, bring-your-own-context demos, reference adapter signal paths, and future batch validation.
-
-Do not rename this with future-signal terminology. Future context signals, control signals, provenance confidence signals, and richer decision metadata are optional future layers on top of this stable input shape. They are not replacements for Signal Contract v1 and are not required fields today.
-
-It is an additive Core API. It does not change MCP tool schemas, Worker runtime behavior, D1 schema, Store scoring, feeds, or deployment behavior.
-
-## Batch Validation Harness
-
-Source checkouts include a small validation harness for testing larger Signal Contract v1 batches:
-
-```bash
-npm run batch:validate -- examples/batches/signal-contract-v1.academic.json
-```
-
-The harness reads caller-provided JSON, evaluates it through Core, summarizes status/date/decision counts, and prints a structured evidence block. It does not add required fields to the Signal Contract and does not fetch, crawl, scan folders, or call reference adapters.
-
-Replay output includes concise decision explanations and small reason-code lists for top results and human-review mismatches. These are reporting aids for auditability: they surface whether relevance, freshness, date confidence, status, utility, score normalization, or Source Profile behavior influenced a treatment label. They do not change Core scoring, ranking, normalization, or decision thresholds, and they do not certify truth.
+# FreshContext Signal Contract v1
+
+FreshContext Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context that should be judged before it reaches a model.
+
+In plain terms:
+
+```text
+candidate context -> Signal Contract v1 -> FreshContext judgment -> decision-ready context
+```
+
+The Signal Contract is live product architecture. It is used by Core normalization, `evaluate_context`, bring-your-own-context demos, reference adapter signal paths, and future batch validation.
+
+Do not rename this with future-signal terminology. Future context signals, control signals, provenance confidence signals, and richer decision metadata are optional future layers on top of this stable input shape. They are not replacements for Signal Contract v1 and are not required fields today.
+
+It is an additive Core API. It does not change MCP tool schemas, Worker runtime behavior, D1 schema, Store scoring, feeds, or deployment behavior.
+
+Provenance readiness is an output-side judgment over this signal material. It can warn about weak source identity or missing timing metadata without adding new required input fields.
+
+## Batch Validation Harness
+
+Source checkouts include a small validation harness for testing larger Signal Contract v1 batches:
+
+```bash
+npm run batch:validate -- examples/batches/signal-contract-v1.academic.json
+```
+
+The harness reads caller-provided JSON, evaluates it through Core, summarizes status/date/decision counts, and prints a structured evidence block. It does not add required fields to the Signal Contract and does not fetch, crawl, scan folders, or call reference adapters.
+
+Replay output includes concise decision explanations and small reason-code lists for top results and human-review mismatches. These are reporting aids for auditability: they surface whether relevance, freshness, date confidence, status, utility, score normalization, or Source Profile behavior influenced a treatment label. They do not change Core scoring, ranking, normalization, or decision thresholds, and they do not certify truth.
 
 ## Contract Version
 
@@ -38,9 +40,9 @@ Every normalized signal includes:
 contract_version: "freshcontext.signal.v1"
 ```
 
-## Input Shape
-
-`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, `evaluate_context`, and future Store wiring:
+## Input Shape
+
+`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, `evaluate_context`, and future Store wiring:
 
 ```ts
 interface FreshContextSignalInput {
@@ -60,21 +62,21 @@ interface FreshContextSignalInput {
 }
 ```
 
-`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias.
-
-Minimal caller-provided input usually looks like:
-
-```json
-{
-  "title": "Example source",
-  "content": "Candidate context text...",
-  "source": "https://example.com/source",
-  "source_type": "official_docs",
-  "published_at": "2026-06-01T00:00:00.000Z",
-  "retrieved_at": "2026-06-09T00:00:00.000Z",
-  "semantic_score": 0.92
-}
-```
+`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias.
+
+Minimal caller-provided input usually looks like:
+
+```json
+{
+  "title": "Example source",
+  "content": "Candidate context text...",
+  "source": "https://example.com/source",
+  "source_type": "official_docs",
+  "published_at": "2026-06-01T00:00:00.000Z",
+  "retrieved_at": "2026-06-09T00:00:00.000Z",
+  "semantic_score": 0.92
+}
+```
 
 ## Normalized Output
 
@@ -98,166 +100,166 @@ interface FreshContextSignal {
 }
 ```
 
-## Normalization Rules
-
-- Missing or invalid `published_at` / `content_date` becomes `published_at: null`.
+## Normalization Rules
+
+- Missing or invalid `published_at` / `content_date` becomes `published_at: null`.
 - `content_date` maps to `published_at` when `published_at` is absent.
 - Meaningfully future-dated timestamps are cleared and receive `date_confidence: "unknown"`.
 - Small clock skew is tolerated by the same Core freshness policy used by envelope scoring.
 - Failed, empty, timeout, blocked, or error-looking content becomes `status: "failed"`.
 - Missing, invalid, negative, or oversized `semantic_score` is clamped into `0..1`.
-- `metadata` is shallow-copied so normalization does not mutate caller-owned objects.
-- `reasons` records meaningful normalization changes.
-
-## Examples
-
-These examples are intentionally small. They show the current contract shape, not future optional metadata.
-
-### Valid Candidate Signals
-
-Academic research:
-
-```json
-{
-  "title": "A fresh retrieval-augmented generation benchmark",
-  "content": "The paper reports a 2026 benchmark for retrieval-augmented generation systems.",
-  "source": "https://arxiv.org/abs/2606.00001",
-  "source_type": "arxiv",
-  "published_at": "2026-06-01T09:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.94,
-  "metadata": {
-    "profile": "academic_research"
-  }
-}
-```
-
-Official docs:
-
-```json
-{
-  "title": "API changelog",
-  "content": "The official changelog documents the current API behavior.",
-  "source": "https://docs.example.com/changelog",
-  "source_type": "official_docs",
-  "published_at": "2026-06-08T10:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.88
-}
-```
-
-Jobs/opportunities:
-
-```json
-{
-  "title": "AI tools engineer",
-  "content": "A current remote role for an AI tools engineer.",
-  "source": "https://jobs.example.com/ai-tools-engineer",
-  "source_type": "jobs",
-  "published_at": "2026-06-07T08:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.86
-}
-```
-
-Market/finance:
-
-```json
-{
-  "title": "Company quarterly update",
-  "content": "The company reported current quarter revenue and guidance.",
-  "source": "https://investors.example.com/q2-update",
-  "source_type": "finance",
-  "published_at": "2026-06-09T07:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.83
-}
-```
-
-Social pulse:
-
-```json
-{
-  "title": "Developer discussion",
-  "content": "Developers are discussing setup friction and recent adoption.",
-  "source": "https://news.ycombinator.com/item?id=123456",
-  "source_type": "hackernews",
-  "published_at": "2026-06-09T11:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.71
-}
-```
-
-### Invalid Or Risky Candidate Signals
-
-Missing date:
-
-```json
-{
-  "title": "Relevant source with no date",
-  "content": "Useful candidate context, but no publication timestamp is available.",
-  "source": "https://example.com/no-date",
-  "source_type": "official_docs",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.78
-}
-```
-
-Invalid timestamp:
-
-```json
-{
-  "title": "Invalid date source",
-  "content": "Candidate context with malformed date metadata.",
-  "source": "https://example.com/bad-date",
-  "source_type": "official_docs",
-  "published_at": "not-a-date",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.78
-}
-```
-
-Meaningfully future-dated timestamp:
-
-```json
-{
-  "title": "Future-dated source",
-  "content": "Candidate context whose publication timestamp is after retrieval time.",
-  "source": "https://example.com/future-date",
-  "source_type": "official_docs",
-  "published_at": "2026-06-09T12:06:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.78
-}
-```
-
-Failed/error-looking content:
-
-```json
-{
-  "title": "Blocked source",
-  "content": "[Error] upstream timeout",
-  "source": "https://example.com/blocked",
-  "source_type": "official_docs",
-  "published_at": "2026-06-09T10:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 0.91
-}
-```
-
-Out-of-range semantic score:
-
-```json
-{
-  "title": "Overscored source",
-  "content": "Candidate context with an out-of-range relevance score.",
-  "source": "https://example.com/overscored",
-  "source_type": "official_docs",
-  "published_at": "2026-06-09T10:00:00.000Z",
-  "retrieved_at": "2026-06-09T12:00:00.000Z",
-  "semantic_score": 1.7
-}
-```
+- `metadata` is shallow-copied so normalization does not mutate caller-owned objects.
+- `reasons` records meaningful normalization changes.
+
+## Examples
+
+These examples are intentionally small. They show the current contract shape, not future optional metadata.
+
+### Valid Candidate Signals
+
+Academic research:
+
+```json
+{
+  "title": "A fresh retrieval-augmented generation benchmark",
+  "content": "The paper reports a 2026 benchmark for retrieval-augmented generation systems.",
+  "source": "https://arxiv.org/abs/2606.00001",
+  "source_type": "arxiv",
+  "published_at": "2026-06-01T09:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.94,
+  "metadata": {
+    "profile": "academic_research"
+  }
+}
+```
+
+Official docs:
+
+```json
+{
+  "title": "API changelog",
+  "content": "The official changelog documents the current API behavior.",
+  "source": "https://docs.example.com/changelog",
+  "source_type": "official_docs",
+  "published_at": "2026-06-08T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.88
+}
+```
+
+Jobs/opportunities:
+
+```json
+{
+  "title": "AI tools engineer",
+  "content": "A current remote role for an AI tools engineer.",
+  "source": "https://jobs.example.com/ai-tools-engineer",
+  "source_type": "jobs",
+  "published_at": "2026-06-07T08:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.86
+}
+```
+
+Market/finance:
+
+```json
+{
+  "title": "Company quarterly update",
+  "content": "The company reported current quarter revenue and guidance.",
+  "source": "https://investors.example.com/q2-update",
+  "source_type": "finance",
+  "published_at": "2026-06-09T07:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.83
+}
+```
+
+Social pulse:
+
+```json
+{
+  "title": "Developer discussion",
+  "content": "Developers are discussing setup friction and recent adoption.",
+  "source": "https://news.ycombinator.com/item?id=123456",
+  "source_type": "hackernews",
+  "published_at": "2026-06-09T11:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.71
+}
+```
+
+### Invalid Or Risky Candidate Signals
+
+Missing date:
+
+```json
+{
+  "title": "Relevant source with no date",
+  "content": "Useful candidate context, but no publication timestamp is available.",
+  "source": "https://example.com/no-date",
+  "source_type": "official_docs",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Invalid timestamp:
+
+```json
+{
+  "title": "Invalid date source",
+  "content": "Candidate context with malformed date metadata.",
+  "source": "https://example.com/bad-date",
+  "source_type": "official_docs",
+  "published_at": "not-a-date",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Meaningfully future-dated timestamp:
+
+```json
+{
+  "title": "Future-dated source",
+  "content": "Candidate context whose publication timestamp is after retrieval time.",
+  "source": "https://example.com/future-date",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T12:06:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Failed/error-looking content:
+
+```json
+{
+  "title": "Blocked source",
+  "content": "[Error] upstream timeout",
+  "source": "https://example.com/blocked",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.91
+}
+```
+
+Out-of-range semantic score:
+
+```json
+{
+  "title": "Overscored source",
+  "content": "Candidate context with an out-of-range relevance score.",
+  "source": "https://example.com/overscored",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 1.7
+}
+```
 
 ## Relationship to Existing Core Types
 
@@ -270,16 +272,16 @@ The signal contract does not replace existing Core types:
 
 The contract gives these surfaces a shared signal vocabulary without requiring Store, Worker, or MCP schema changes.
 
-## Boundary
-
-Signal Contract v1 does not determine truth, certify data, or provide legal, medical, tax, or financial advice. It provides normalized context metadata for freshness, provenance, relevance, and workflow review.
-
-## Future Metadata Boundary
-
-Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals may later improve decisions such as `cite_as_primary`, `needs_refresh`, `needs_verification`, or `exclude`.
-
-Those are roadmap metadata layers. They should remain optional until tests prove they improve decisions. The public input contract should stay boring and stable:
-
-```text
-title + content + source + source_type + published_at + retrieved_at + semantic_score
-```
+## Boundary
+
+Signal Contract v1 does not determine truth, certify data, or provide legal, medical, tax, or financial advice. It provides normalized context metadata for freshness, provenance, relevance, and workflow review.
+
+## Future Metadata Boundary
+
+Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals may later improve decisions such as `cite_as_primary`, `needs_refresh`, `needs_verification`, or `exclude`.
+
+Those are roadmap metadata layers. They should remain optional until tests prove they improve decisions. The public input contract should stay boring and stable:
+
+```text
+title + content + source + source_type + published_at + retrieved_at + semantic_score
+```

package/docs/SOURCE_PROFILES.md

@@ -1,6 +1,6 @@
 # FreshContext Source Profiles
 
-Status: early Core metadata
+Status: current Core metadata
 
 FreshContext is a context gateway for agents and humans before reasoning. It turns raw candidate context into freshness-ranked, explained, provenance-aware context.
 
@@ -39,10 +39,12 @@ They demonstrate that FreshContext can evaluate different information classes:
 - social pulse
 - academic and research material
 - financial and market signals
-- jobs and opportunities
-- government, regulatory, and procurement data
-- competitive and company intelligence
-- composite multi-source landscapes
+- jobs and opportunities
+- government, regulatory, and procurement data
+- competitive and company intelligence
+- product research and adoption evidence
+- composite multi-source landscapes
+- multi-agent handoff context
 
 ## Source Profiles
 
@@ -59,7 +61,7 @@ adapter output
   -> host response
 ```
 
-As of Pass 8-J, Core exports built-in profile presets and a small metadata contract shaped like:
+Core exports built-in profile presets and a small metadata contract shaped like:
 
 ```ts
 type SourceProfile = {
@@ -77,7 +79,7 @@ type SourceProfile = {
 
 The existing Core `LAMBDA` table is the current decay-policy reference. Source Profiles make that policy understandable and product-facing without changing Core behavior.
 
-Pass 8-J adds:
+The current Core API includes:
 
 - `BUILT_IN_SOURCE_PROFILES`
 - `getSourceProfile(profileId)`
@@ -96,9 +98,9 @@ The likely first extraction target remains `extract_arxiv`, because it is a low-
 
 ## Profile Groups
 
-### Official / Canonical Documentation
-
-Strategic future profile.
+### Official / Canonical Documentation
+
+Current built-in profile.
 
 Purpose: official product docs, API docs, standards, changelogs, specifications, legal references, and canonical source material.
 
@@ -252,9 +254,9 @@ Policy intent:
 - filing and tender dates should be strict
 - unknown dates should not be treated as fresh
 
-### Company / Competitive Intelligence
-
-Purpose: company research, product velocity, ecosystem activity, funding/procurement signals, and competitive context.
+### Company / Competitive Intelligence
+
+Purpose: company research, product velocity, ecosystem activity, funding/procurement signals, and competitive context.
 
 Current reference adapters:
 
@@ -271,11 +273,34 @@ Policy intent:
 - mixed-source profile
 - should preserve per-source timestamps where possible
 - should explain whether signal came from official records, market data, community pulse, or repository activity
-- useful for agents and buyer workflows, but not a replacement for due diligence
-
-### Composite Landscape / Validation
-
-Purpose: multi-source validation and idea or market landscape checks.
+- useful for agents and buyer workflows, but not a replacement for due diligence
+
+### Product Research / Adoption Evidence
+
+Purpose: product pages, launch material, pricing pages, vendor documentation, changelogs, and adoption evidence.
+
+Current source types:
+
+- `product_page`
+- `pricing_page`
+- `launch_page`
+- `vendor_docs`
+- `changelog`
+- `producthunt`
+
+Policy intent:
+
+- useful for buyer, developer-adoption, and product-comparison workflows
+- official documentation and changelogs should outrank vague promotional material
+- pricing and roadmap pages should be verified before acting on them
+- missing, invalid, or future-dated timestamps should stay visible
+- failed product pages should be excluded or downgraded, not wrapped as useful context
+
+This profile is a judgment policy for caller-provided candidate context. It does not fetch vendor sites, select adapters, crawl product pages, browse, or implement a product-research agent.
+
+### Composite Landscape / Validation
+
+Purpose: multi-source validation and idea or market landscape checks.
 
 Current reference adapters:
 
@@ -297,12 +322,32 @@ Policy intent:
 
 - each section should retain source-specific timestamps
 - composite freshness must not collapse all sections into one fake timestamp
-- partial failures should be visible
-- all-unavailable composites should not be cached or promoted as fresh
-
-### Local / Custom Context
-
-Strategic future profile.
+- partial failures should be visible
+- all-unavailable composites should not be cached or promoted as fresh
+
+### Multi-Agent Handoff Context
+
+Purpose: caller-provided context passed between agents or workflow steps, with warnings and provenance preserved.
+
+Current source types:
+
+- `agent_handoff`
+- `agent_context`
+- `workflow_context`
+- `user_provided`
+
+Policy intent:
+
+- preserve what another agent thought mattered without treating it as automatically trustworthy
+- keep missing dates, failed upstream outputs, weak provenance, and score normalization visible
+- prefer source-preserving handoffs over vague summaries
+- make context safe to pass forward only when the decision and provenance state support handoff
+
+This profile is not Operator mode. It does not orchestrate agents, call tools, browse, crawl, read folders, or retrieve sources. It judges candidate context that a caller or agent already supplied.
+
+### Local / Custom Context
+
+Current built-in profile.
 
 Purpose: user-provided files, PDFs, notes, lecture material, source lists, internal docs, research folders, and custom retrieval results.