freshcontext-mcp 0.3.20 → 0.3.21

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/package-script-guard.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
 
 const SOURCE_CHECKOUT_MESSAGE = [
   "This npm script is for the FreshContext source checkout.",
@@ -40,19 +40,24 @@ const commands = {
     command: "tsx",
     args: ["examples/evaluate-with-source-profile.ts"],
   },
-  "demo:evaluate:file": {
-    required: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
-    command: "tsx",
-    args: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
-    passThroughArgs: true,
-  },
-  "batch:validate": {
-    required: ["examples/validate-signal-batch.ts"],
-    command: "tsx",
-    args: ["examples/validate-signal-batch.ts"],
-    passThroughArgs: true,
-  },
-  "smoke:stdio": {
+  "demo:evaluate:file": {
+    required: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
+    command: "tsx",
+    args: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
+    passThroughArgs: true,
+  },
+  "batch:validate": {
+    required: ["examples/validate-signal-batch.ts"],
+    command: "tsx",
+    args: ["examples/validate-signal-batch.ts"],
+    passThroughArgs: true,
+  },
+  "core:fixture": {
+    required: ["scripts/pack-core-fixture.mjs", "dist/core/index.js"],
+    command: "node",
+    args: ["scripts/pack-core-fixture.mjs"],
+  },
+  "smoke:stdio": {
     required: ["scripts/smoke-stdio.mjs"],
     command: "node",
     args: ["scripts/smoke-stdio.mjs"],
@@ -98,20 +103,24 @@ const commands = {
       "tests/freshnessStamp.test.ts",
       "tests/hackernews.test.ts",
       "tests/arxivSignals.test.ts",
-      "tests/arxivDecisionIntegration.test.ts",
-      "tests/core.test.ts",
-      "tests/haPriV2GoldenVectors.test.ts",
-      "tests/signalContractExamples.test.ts",
-      "tests/batchValidationHarness.test.ts",
-      "tests/rank.test.ts",
-      "tests/workerEnvelope.test.ts",
-      "tests/packageScriptGuard.test.mjs",
-      "tests/adapterNetworkBoundary.test.ts",
-      "tests/workerRouteSecurity.test.ts",
-      "tests/workerCoreEnvelopeParity.test.ts",
+      "tests/arxivDecisionIntegration.test.ts",
+      "tests/core.test.ts",
+      "tests/haPriV2GoldenVectors.test.ts",
+      "tests/signalContractExamples.test.ts",
+      "tests/batchValidationHarness.test.ts",
+      "tests/rank.test.ts",
+      "tests/workerEnvelope.test.ts",
+      "tests/packageScriptGuard.test.mjs",
+      "tests/corePackageFixture.test.mjs",
+      "tests/readableOutput.test.ts",
+      "tests/provenanceReadiness.test.ts",
+      "tests/adapterNetworkBoundary.test.ts",
+      "tests/workerRouteSecurity.test.ts",
+      "tests/workerCoreEnvelopeParity.test.ts",
       "tests/coreEnvelopeOptions.test.ts",
       "tests/mathSpine.test.ts",
       "tests/coreApiContract.test.ts",
+      "tests/coreSubpathExport.test.mjs",
       "tests/corePipeline.test.ts",
       "tests/decision.test.ts",
       "tests/evaluateContextTool.test.ts",
@@ -131,54 +140,54 @@ if (!config) {
   process.exit(1);
 }
 
-const hasSourceCheckoutFiles = config.required.every((path) => existsSync(path));
-if (!hasSourceCheckoutFiles) {
-  console.log(SOURCE_CHECKOUT_MESSAGE);
-  process.exit(0);
-}
-
-function resolveCommand(command, args) {
-  if (command === "node") return { command: process.execPath, args };
-
-  const localNodeEntrypoints = {
-    tsx: join("node_modules", "tsx", "dist", "cli.mjs"),
-    tsc: join("node_modules", "typescript", "bin", "tsc"),
-  };
-  const nodeEntrypoint = localNodeEntrypoints[command];
-  if (nodeEntrypoint && existsSync(nodeEntrypoint)) {
-    return { command: process.execPath, args: [nodeEntrypoint, ...args] };
-  }
-
-  const localBin = process.platform === "win32"
-    ? join("node_modules", ".bin", `${command}.cmd`)
-    : join("node_modules", ".bin", command);
-
-  if (existsSync(localBin)) return { command: localBin, args };
-  if (process.platform === "win32" && !command.endsWith(".cmd")) {
-    return { command: `${command}.cmd`, args };
-  }
-  return { command, args };
-}
-
-function validatePassThroughArgs(args) {
-  for (const arg of args) {
-    if (arg.includes("\0")) {
-      console.error("FreshContext package script arguments cannot contain null bytes.");
-      process.exit(1);
-    }
-  }
-  return args;
-}
-
-const args = [
-  ...config.args,
-  ...(config.passThroughArgs ? validatePassThroughArgs(process.argv.slice(3)) : []),
-];
-const invocation = resolveCommand(config.command, args);
-const child = spawnSync(invocation.command, invocation.args, {
-  stdio: "inherit",
-  shell: false,
-});
+const hasSourceCheckoutFiles = config.required.every((path) => existsSync(path));
+if (!hasSourceCheckoutFiles) {
+  console.log(SOURCE_CHECKOUT_MESSAGE);
+  process.exit(0);
+}
+
+function resolveCommand(command, args) {
+  if (command === "node") return { command: process.execPath, args };
+
+  const localNodeEntrypoints = {
+    tsx: join("node_modules", "tsx", "dist", "cli.mjs"),
+    tsc: join("node_modules", "typescript", "bin", "tsc"),
+  };
+  const nodeEntrypoint = localNodeEntrypoints[command];
+  if (nodeEntrypoint && existsSync(nodeEntrypoint)) {
+    return { command: process.execPath, args: [nodeEntrypoint, ...args] };
+  }
+
+  const localBin = process.platform === "win32"
+    ? join("node_modules", ".bin", `${command}.cmd`)
+    : join("node_modules", ".bin", command);
+
+  if (existsSync(localBin)) return { command: localBin, args };
+  if (process.platform === "win32" && !command.endsWith(".cmd")) {
+    return { command: `${command}.cmd`, args };
+  }
+  return { command, args };
+}
+
+function validatePassThroughArgs(args) {
+  for (const arg of args) {
+    if (arg.includes("\0")) {
+      console.error("FreshContext package script arguments cannot contain null bytes.");
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+const args = [
+  ...config.args,
+  ...(config.passThroughArgs ? validatePassThroughArgs(process.argv.slice(3)) : []),
+];
+const invocation = resolveCommand(config.command, args);
+const child = spawnSync(invocation.command, invocation.args, {
+  stdio: "inherit",
+  shell: false,
+});
 
 if (child.error) {
   console.error(child.error.message);