freshcontext-mcp 0.3.18 → 0.3.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/FRESHCONTEXT_SPEC.md +317 -0
- package/METHODOLOGY.md +381 -0
- package/README.md +87 -19
- package/dist/adapters/arxiv.js +2 -1
- package/dist/adapters/changelog.js +4 -2
- package/dist/adapters/finance.js +1 -1
- package/dist/adapters/gdelt.js +1 -1
- package/dist/adapters/gebiz.js +1 -1
- package/dist/adapters/reddit.js +11 -4
- package/dist/adapters/repoSearch.js +1 -1
- package/dist/adapters/secFilings.js +1 -1
- package/dist/core/envelope.js +9 -1
- package/dist/security.js +3 -1
- package/dist/server.js +40 -2
- package/dist/tools/evaluateContext.js +146 -0
- package/docs/CLIENT_SETUP.md +166 -0
- package/docs/CODEX_MCP_USAGE.md +7 -7
- package/docs/CORE_API.md +12 -8
- package/docs/CORE_MCP_BOUNDARY.md +106 -0
- package/docs/FUTURE_LANES.md +196 -0
- package/docs/HA_PRI_V2_DESIGN.md +7 -1
- package/docs/HA_PRI_V2_PRODUCTION_ENFORCEMENT_PLAN.md +414 -0
- package/docs/RELEASE_INTEGRITY.md +2 -0
- package/docs/RELEASE_NOTES.md +22 -5
- package/docs/SIGNAL_CONTRACT.md +213 -17
- package/docs/SOURCE_PROFILES.md +3 -3
- package/package-script-guard.mjs +76 -28
- package/package.json +14 -7
- package/server.json +3 -3
- package/docs/OPERATIONAL_DEMO_RUNBOOK.md +0 -458
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# FreshContext Future Lanes
|
|
2
|
+
|
|
3
|
+
This document keeps future FreshContext work organized without turning roadmap ideas into public claims.
|
|
4
|
+
|
|
5
|
+
FreshContext is live today as an integrated MCP/Core package. Future work should stay in lanes, start with audits, and avoid feature sprawl.
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Current Live Boundary
|
|
10
|
+
|
|
11
|
+
Live today:
|
|
12
|
+
|
|
13
|
+
- npm package: `freshcontext-mcp@0.3.19`
|
|
14
|
+
- MCP stdio server
|
|
15
|
+
- `evaluate_context` MCP tool for caller-provided candidate context
|
|
16
|
+
- Signal Contract v1 as the stable candidate-context input shape
|
|
17
|
+
- 21 read-only reference adapters
|
|
18
|
+
- Core signal evaluation
|
|
19
|
+
- Source Profiles
|
|
20
|
+
- Decision Helper
|
|
21
|
+
- adapter registry metadata
|
|
22
|
+
- arXiv signal-to-decision proof
|
|
23
|
+
- bring-your-own-context local demos
|
|
24
|
+
- Trust Scanner release gate
|
|
25
|
+
|
|
26
|
+
Not live today:
|
|
27
|
+
|
|
28
|
+
- Operator / `retrieve(...)`
|
|
29
|
+
- browser crawling
|
|
30
|
+
- automatic local file, folder, or PDF scanning
|
|
31
|
+
- hosted dashboard or billing
|
|
32
|
+
- hard Ha-Pri v2 production enforcement
|
|
33
|
+
- standalone Core SDK package
|
|
34
|
+
- full adapter ingestion
|
|
35
|
+
|
|
36
|
+
## Phase 0: Stabilize The Signal Contract
|
|
37
|
+
|
|
38
|
+
Goal:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
Treat Signal Contract v1 as the stable input boundary for FreshContext.
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Current contract:
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
title + content + source + source_type + published_at + retrieved_at + semantic_score
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
This is live today. It is not the same thing as future context signals or control signals.
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
## Lane 1: Client Setup Reliability
|
|
57
|
+
|
|
58
|
+
Goal:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
Make Claude, Codex, and MCP-compatible clients connect reliably to the published package.
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Start with setup guide audits, Claude Desktop local/global package paths, Codex local MCP config paths, stale global package fixes, and smoke command expectations.
|
|
65
|
+
|
|
66
|
+
Do not claim ChatGPT/OpenAI connector compatibility until a separate compatibility audit is done.
|
|
67
|
+
|
|
68
|
+
## Lane 2: Generic Context Evaluation
|
|
69
|
+
|
|
70
|
+
Goal:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
Let any caller provide candidate context and get decision-ready output.
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Current live MCP path:
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
evaluate_context
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Hard boundary:
|
|
83
|
+
|
|
84
|
+
```text
|
|
85
|
+
No fetching, crawling, browsing, folder reading, or retrieval orchestration.
|
|
86
|
+
Only evaluate caller-provided candidate context.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Next work in this lane should focus on CLI, SDK, and REST ergonomics over the same caller-provided signal shape.
|
|
90
|
+
|
|
91
|
+
## Lane 3: Multi-Agent Context Handoff Proof
|
|
92
|
+
|
|
93
|
+
Goal:
|
|
94
|
+
|
|
95
|
+
```text
|
|
96
|
+
Show FreshContext as an independent context judgment layer between agents.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Proof shape:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
agent A produces candidate context
|
|
103
|
+
-> FreshContext evaluates it
|
|
104
|
+
-> agent B receives decision-ready context
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Do not build a full multi-agent framework. Prove the handoff boundary.
|
|
108
|
+
|
|
109
|
+
## Lane 4: Core SDK Extraction Audit
|
|
110
|
+
|
|
111
|
+
Goal:
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
Decide whether Core should become a standalone package.
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Audit current Core exports, dependency boundaries, package shape, browser/node compatibility, public API stability, and what remains MCP-only.
|
|
118
|
+
|
|
119
|
+
No extraction without a compatibility plan. Keep `freshcontext-mcp` stable until a standalone Core package has compatibility tests and a migration path.
|
|
120
|
+
|
|
121
|
+
## Lane 5: Local/User Data Intake Audit
|
|
122
|
+
|
|
123
|
+
Goal:
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
Explore student, research, and local-PC workflows safely.
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Candidate sources include notes, PDFs, local JSON/CSV, citation exports, and database rows.
|
|
130
|
+
|
|
131
|
+
Hard boundary:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
Consent-first design. No automatic folder scanning or background file reading.
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Lane 6: Decision Layer Upgrade
|
|
138
|
+
|
|
139
|
+
Goal:
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
Make decisions more useful without silently changing ranking.
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Possible inputs include context utility, control signal, future context signal, ingestion quality, structure preservation, provenance confidence, confidence tiers, and source-profile-specific thresholds.
|
|
146
|
+
|
|
147
|
+
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.
|
|
148
|
+
|
|
149
|
+
Do not make `utility.score` affect ranking by default without a dedicated ranking policy pass.
|
|
150
|
+
|
|
151
|
+
## Lane 7: Ha-Pri v2 Production Path
|
|
152
|
+
|
|
153
|
+
Goal:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
Turn Ha-Pri v2 from pure Core helper/design into production enforcement where appropriate.
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Audit canonical content material, storage path, verification timing, failure mode, D1/Worker compatibility, and migration plan.
|
|
160
|
+
|
|
161
|
+
Do not claim hard tamper enforcement until the read/write path exists.
|
|
162
|
+
|
|
163
|
+
## Lane 8: GDELT GKG / Richer Source Intelligence
|
|
164
|
+
|
|
165
|
+
Goal:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
Upgrade GDELT intelligence with richer global knowledge graph signals.
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Possible fields include tone, Goldstein scale, event codes, actor geography, theme density, and source timeline.
|
|
172
|
+
|
|
173
|
+
Do not mix this with generic context evaluation or local intake.
|
|
174
|
+
|
|
175
|
+
## Lane 9: Operator / Retrieve Orchestration
|
|
176
|
+
|
|
177
|
+
Goal:
|
|
178
|
+
|
|
179
|
+
```text
|
|
180
|
+
Coordinate retrieval only after the decision layer and adapter boundaries are mature.
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Operator may later select adapters, call retrievers, refresh stale sources, and package best context.
|
|
184
|
+
|
|
185
|
+
Not now. Operator is a later workflow layer over Core and adapters.
|
|
186
|
+
|
|
187
|
+
## Operating Rule
|
|
188
|
+
|
|
189
|
+
Every lane starts with:
|
|
190
|
+
|
|
191
|
+
```text
|
|
192
|
+
audit -> small patch -> validation -> stop
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Do not combine lanes because the architecture is tempting.
|
|
196
|
+
|
package/docs/HA_PRI_V2_DESIGN.md
CHANGED
|
@@ -10,7 +10,13 @@ Ha-Pri v2 is an additive provenance-hardening model for FreshContext Store/Ledge
|
|
|
10
10
|
|
|
11
11
|
The goal is to keep Ha-Pri v1 readable while designing a stronger future signature that binds a row to canonical content, semantic identity, source metadata, timestamps, and engine version.
|
|
12
12
|
|
|
13
|
-
Phase 3-B adds pure Core helper functions and deterministic tests for the v2 model. Phase 3-C adds `examples/ha-pri-v2-example.ts`, a deterministic developer fixture showing `calculateHaPriV2` and `verifyHaPriV2` returning valid, invalid, and unknown verification states. Production Store wiring remains future work. This document does not change the D1 schema, change Worker write paths, migrate old rows, add HMAC secrets, or alter production scoring.
|
|
13
|
+
Phase 3-B adds pure Core helper functions and deterministic tests for the v2 model. Phase 3-C adds `examples/ha-pri-v2-example.ts`, a deterministic developer fixture showing `calculateHaPriV2` and `verifyHaPriV2` returning valid, invalid, and unknown verification states. Production Store wiring remains future work. This document does not change the D1 schema, change Worker write paths, migrate old rows, add HMAC secrets, or alter production scoring.
|
|
14
|
+
|
|
15
|
+
Pass 11-J adds golden test vectors for the pure Core helpers. Ha-Pri v2 golden vectors prove deterministic Core provenance behavior: canonicalization, SHA-256 hashes, signing payload construction, signature generation, and verification status are stable and repeatable. They do not mean Ha-Pri v2 is production-enforced on Worker/D1 reads.
|
|
16
|
+
|
|
17
|
+
Plain SHA-256 provides deterministic integrity and audit checks. HMAC or private-key signing would be needed later for stronger origin-authentication guarantees.
|
|
18
|
+
|
|
19
|
+
Pass 11-K adds a design-only production enforcement plan in `docs/HA_PRI_V2_PRODUCTION_ENFORCEMENT_PLAN.md`. That plan covers the future D1/storage, write-path, read/debug verification, compatibility, backfill, threat model, and rollout path. It does not implement Worker/D1 enforcement.
|
|
14
20
|
|
|
15
21
|
## Current Ha-Pri v1 Audit
|
|
16
22
|
|
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
# Ha-Pri v2 Production Enforcement Plan
|
|
2
|
+
|
|
3
|
+
Status: design only
|
|
4
|
+
Phase: Pass 11-K
|
|
5
|
+
Runtime impact: none
|
|
6
|
+
|
|
7
|
+
Ha-Pri v2 production enforcement is a future rollout path. Current FreshContext releases only include the Core helper and deterministic golden vectors unless a later implementation pass explicitly wires Worker/D1 enforcement.
|
|
8
|
+
|
|
9
|
+
This plan describes how Ha-Pri v2 could move from pure Core provenance helper to production Store/Worker verification without overclaiming current behavior.
|
|
10
|
+
|
|
11
|
+
## 1. Current State
|
|
12
|
+
|
|
13
|
+
Current FreshContext behavior:
|
|
14
|
+
|
|
15
|
+
- Ha-Pri v1 is the current Worker/feed audit stamp.
|
|
16
|
+
- Ha-Pri v1 is stored as `scrape_results.ha_pri_sig`.
|
|
17
|
+
- Ha-Pri v1 is returned in Worker feed `intelligence_stamps`.
|
|
18
|
+
- Ha-Pri v1 is a provenance stamp and audit reference, not hard row rejection.
|
|
19
|
+
- Ha-Pri v2 exists as a pure Core helper in `src/core/provenance.ts`.
|
|
20
|
+
- Ha-Pri v2 has deterministic golden vectors in `tests/fixtures/ha-pri-v2-golden-vectors.json`.
|
|
21
|
+
- Ha-Pri v2 is not production-enforced on Worker/D1 reads.
|
|
22
|
+
- Ha-Pri v2 does not currently reject rows.
|
|
23
|
+
- Ha-Pri v2 does not currently provide private-key origin authentication.
|
|
24
|
+
|
|
25
|
+
The current v2 helper provides deterministic canonicalization, SHA-256 hashing, signing payload construction, signature calculation, and verification status:
|
|
26
|
+
|
|
27
|
+
```txt
|
|
28
|
+
valid
|
|
29
|
+
invalid
|
|
30
|
+
unknown
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
That is real Core behavior. It is not yet Worker/D1 enforcement.
|
|
34
|
+
|
|
35
|
+
## 2. Target Future State
|
|
36
|
+
|
|
37
|
+
Future production enforcement should make stored context rows independently reviewable after write.
|
|
38
|
+
|
|
39
|
+
Target behavior:
|
|
40
|
+
|
|
41
|
+
- Worker write path stores Ha-Pri v2 provenance material for new rows.
|
|
42
|
+
- Rows can later be verified as `valid`, `invalid`, or `unknown`.
|
|
43
|
+
- Debug/internal read paths can report verification status.
|
|
44
|
+
- Safe public read paths can expose limited verification status without leaking internals.
|
|
45
|
+
- Invalid rows are not silently treated as trusted.
|
|
46
|
+
- Old rows remain compatible through `unknown` and optional backfill behavior.
|
|
47
|
+
- Strict rejection remains optional and staged, not the first rollout.
|
|
48
|
+
|
|
49
|
+
The target is not "FreshContext proves truth." The target is "FreshContext can detect whether stored provenance material still matches the stored row material under the documented v2 contract."
|
|
50
|
+
|
|
51
|
+
## 3. Proposed D1 / Storage Fields
|
|
52
|
+
|
|
53
|
+
Essential fields:
|
|
54
|
+
|
|
55
|
+
```txt
|
|
56
|
+
ha_pri_sig_v2 TEXT
|
|
57
|
+
ha_pri_canonical_content_sha256 TEXT
|
|
58
|
+
ha_pri_semantic_fingerprint_sha256 TEXT
|
|
59
|
+
ha_pri_signing_payload_version TEXT
|
|
60
|
+
ha_pri_engine_version TEXT
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Recommended operational fields:
|
|
64
|
+
|
|
65
|
+
```txt
|
|
66
|
+
ha_pri_verification_status TEXT
|
|
67
|
+
ha_pri_verified_at TEXT
|
|
68
|
+
ha_pri_backfill_status TEXT
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Likely unnecessary as separate stored fields:
|
|
72
|
+
|
|
73
|
+
```txt
|
|
74
|
+
ha_pri_adapter
|
|
75
|
+
ha_pri_published_at
|
|
76
|
+
ha_pri_retrieved_at
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Reason: adapter, published timestamp, and retrieved/scraped timestamp already exist or should exist as first-class row fields. Duplicating them inside Ha-Pri-specific columns risks drift. The signing payload should read those canonical row fields directly during verification.
|
|
80
|
+
|
|
81
|
+
Minimum practical schema:
|
|
82
|
+
|
|
83
|
+
```sql
|
|
84
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_sig_v2 TEXT;
|
|
85
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_canonical_content_sha256 TEXT;
|
|
86
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_semantic_fingerprint_sha256 TEXT;
|
|
87
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_signing_payload_version TEXT;
|
|
88
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_engine_version TEXT;
|
|
89
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_verification_status TEXT;
|
|
90
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_verified_at TEXT;
|
|
91
|
+
ALTER TABLE scrape_results ADD COLUMN ha_pri_backfill_status TEXT;
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Storage status values should be boring and explicit:
|
|
95
|
+
|
|
96
|
+
```txt
|
|
97
|
+
valid
|
|
98
|
+
invalid
|
|
99
|
+
unknown
|
|
100
|
+
not_checked
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Backfill status values should avoid pretending old rows were originally v2-stamped:
|
|
104
|
+
|
|
105
|
+
```txt
|
|
106
|
+
none
|
|
107
|
+
backfilled
|
|
108
|
+
unknown_origin
|
|
109
|
+
failed
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## 4. Write-Path Design
|
|
113
|
+
|
|
114
|
+
The future Worker write path should dual-stamp v1 and v2 for new rows.
|
|
115
|
+
|
|
116
|
+
Recommended write sequence:
|
|
117
|
+
|
|
118
|
+
1. Adapter returns raw candidate content.
|
|
119
|
+
2. Existing Worker scoring computes current DAR fields and Ha-Pri v1.
|
|
120
|
+
3. Write path prepares Ha-Pri v2 input:
|
|
121
|
+
- `resultId`: row id that will be stored
|
|
122
|
+
- `rawContent`: canonical row raw content
|
|
123
|
+
- `semanticFingerprint`: semantic fingerprint material or stored fingerprint
|
|
124
|
+
- `adapter`: adapter id
|
|
125
|
+
- `publishedAt`: normalized source publication timestamp or `null`
|
|
126
|
+
- `retrievedAt`: normalized scrape/retrieval timestamp
|
|
127
|
+
- `engineVersion`: FreshContext engine/package version or explicit Worker engine version
|
|
128
|
+
4. If required v2 material is complete, calculate:
|
|
129
|
+
- canonical content SHA-256
|
|
130
|
+
- semantic fingerprint SHA-256
|
|
131
|
+
- signing payload version
|
|
132
|
+
- Ha-Pri v2 signature
|
|
133
|
+
5. Store v1 fields as today.
|
|
134
|
+
6. Store v2 fields alongside v1 fields.
|
|
135
|
+
7. If material is incomplete, store unknown-compatible metadata and do not pretend the row is valid.
|
|
136
|
+
|
|
137
|
+
Recommended incomplete-material behavior:
|
|
138
|
+
|
|
139
|
+
```txt
|
|
140
|
+
ha_pri_sig_v2 = null
|
|
141
|
+
ha_pri_verification_status = "unknown"
|
|
142
|
+
ha_pri_backfill_status = "none"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Canonical content should be produced by the same pure helper behavior used in Core golden vectors. Do not invent a second Worker-only canonicalization contract.
|
|
146
|
+
|
|
147
|
+
Semantic fingerprint should be produced before signing and should be stable across retries for the same underlying source item. If the fingerprint is missing, v2 signing should fall back to `unknown`, not a fake valid signature.
|
|
148
|
+
|
|
149
|
+
Engine version should be explicit. The safest initial choice is the package/server version used by the running Worker build.
|
|
150
|
+
|
|
151
|
+
## 5. Read / Debug Verification Design
|
|
152
|
+
|
|
153
|
+
Future read verification should be a pure recomputation:
|
|
154
|
+
|
|
155
|
+
```txt
|
|
156
|
+
verifyHaPriV2(row) -> valid | invalid | unknown
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Suggested internal verification input:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
{
|
|
163
|
+
resultId: row.id,
|
|
164
|
+
rawContent: row.raw_content,
|
|
165
|
+
semanticFingerprint: row.semantic_fingerprint,
|
|
166
|
+
adapter: row.adapter,
|
|
167
|
+
publishedAt: row.published_at,
|
|
168
|
+
retrievedAt: row.scraped_at,
|
|
169
|
+
engineVersion: row.ha_pri_engine_version
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Debug output may include:
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"ha_pri_v2": {
|
|
178
|
+
"status": "valid",
|
|
179
|
+
"checked_at": "2026-06-11T12:00:00.000Z",
|
|
180
|
+
"payload_version": "FRESHCONTEXT_HA_PRI_V2",
|
|
181
|
+
"canonical_content_sha256": "sha256...",
|
|
182
|
+
"semantic_fingerprint_sha256": "sha256..."
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Safe public output should be smaller:
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"provenance": {
|
|
192
|
+
"ha_pri_v2_status": "valid"
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Do not expose signing payloads or debug hashes in broad public outputs unless there is a clear user need.
|
|
198
|
+
|
|
199
|
+
Suggested staged behavior:
|
|
200
|
+
|
|
201
|
+
- Phase 1: report-only verification in internal/debug output.
|
|
202
|
+
- Phase 2: warning in read/debug path when invalid.
|
|
203
|
+
- Phase 3: optional strict mode for private deployments.
|
|
204
|
+
- Phase 4: possible reject/block policy only after replay data and operational evidence.
|
|
205
|
+
|
|
206
|
+
Invalid should not become automatic rejection first. A migration bug, canonicalization mismatch, or schema rollout issue could otherwise hide useful rows during rollout.
|
|
207
|
+
|
|
208
|
+
## 6. Compatibility And Backfill
|
|
209
|
+
|
|
210
|
+
Old rows must remain readable.
|
|
211
|
+
|
|
212
|
+
Compatibility rules:
|
|
213
|
+
|
|
214
|
+
- v1-only rows verify as `unknown` for v2.
|
|
215
|
+
- Rows with missing v2 fields verify as `unknown`.
|
|
216
|
+
- Rows with malformed v2 signatures verify as `invalid`.
|
|
217
|
+
- Rows with present but mismatched v2 signatures verify as `invalid`.
|
|
218
|
+
- Missing `ha_pri_sig_v2` is not the same as tampering.
|
|
219
|
+
- Existing `ha_pri_sig` remains readable for historical continuity.
|
|
220
|
+
|
|
221
|
+
Backfill rules:
|
|
222
|
+
|
|
223
|
+
- Backfilled provenance must be marked as `backfilled` or `unknown_origin`.
|
|
224
|
+
- Backfill must not imply the row was v2-stamped at original write time.
|
|
225
|
+
- Backfill should preserve original row timestamps.
|
|
226
|
+
- Backfill should record when verification/backfill happened.
|
|
227
|
+
- Backfill should be reversible or repeatable where practical.
|
|
228
|
+
|
|
229
|
+
Possible backfill process:
|
|
230
|
+
|
|
231
|
+
1. Select rows missing `ha_pri_sig_v2`.
|
|
232
|
+
2. Reconstruct v2 input from stored row fields.
|
|
233
|
+
3. If required material is complete, calculate v2 fields.
|
|
234
|
+
4. Store v2 fields with `ha_pri_backfill_status = "backfilled"`.
|
|
235
|
+
5. If required material is incomplete, store `ha_pri_verification_status = "unknown"` and `ha_pri_backfill_status = "unknown_origin"`.
|
|
236
|
+
6. Report counts for backfilled, unknown, invalid, and failed rows.
|
|
237
|
+
|
|
238
|
+
## 7. Security Boundary
|
|
239
|
+
|
|
240
|
+
Plain SHA-256 gives deterministic integrity and audit checks.
|
|
241
|
+
|
|
242
|
+
Plain SHA-256 does not prove private origin authentication. Anyone with all payload fields can recompute a plain SHA-256 signature.
|
|
243
|
+
|
|
244
|
+
Ha-Pri v2 helps detect:
|
|
245
|
+
|
|
246
|
+
- accidental row corruption
|
|
247
|
+
- changed content after write
|
|
248
|
+
- changed semantic fingerprint material
|
|
249
|
+
- changed adapter/timestamp/version fields included in the signing payload
|
|
250
|
+
- malformed stored signatures
|
|
251
|
+
|
|
252
|
+
Ha-Pri v2 does not solve:
|
|
253
|
+
|
|
254
|
+
- truth certification
|
|
255
|
+
- legal, medical, tax, employment, academic, or investment correctness
|
|
256
|
+
- private origin authentication without a secret or private key
|
|
257
|
+
- compromise of the write path before signing
|
|
258
|
+
- compromise of all row fields plus signature under plain SHA-256
|
|
259
|
+
|
|
260
|
+
Recommendation:
|
|
261
|
+
|
|
262
|
+
Do not add HMAC/private signing immediately to the open package. Keep the open package deterministic and stateless.
|
|
263
|
+
|
|
264
|
+
Consider HMAC or private-key signing later for:
|
|
265
|
+
|
|
266
|
+
- hosted FreshContext endpoints
|
|
267
|
+
- private production deployments
|
|
268
|
+
- paid/tenant-specific infrastructure
|
|
269
|
+
- environments where the verifier must know the row was stamped by a trusted FreshContext deployment
|
|
270
|
+
|
|
271
|
+
If HMAC/private signing is added later, it requires:
|
|
272
|
+
|
|
273
|
+
- secret storage outside the repo
|
|
274
|
+
- key ids
|
|
275
|
+
- key rotation
|
|
276
|
+
- old-key verification policy
|
|
277
|
+
- signer/verifier boundary documentation
|
|
278
|
+
- tests proving secrets are never logged or returned
|
|
279
|
+
|
|
280
|
+
## 8. Threat Model
|
|
281
|
+
|
|
282
|
+
Threats considered:
|
|
283
|
+
|
|
284
|
+
### Accidental row corruption
|
|
285
|
+
|
|
286
|
+
Ha-Pri v2 helps by recomputing the expected signature and surfacing `invalid`.
|
|
287
|
+
|
|
288
|
+
### Stale or partial provenance
|
|
289
|
+
|
|
290
|
+
Ha-Pri v2 helps by returning `unknown` when required material is missing. The system should not pretend such rows are valid.
|
|
291
|
+
|
|
292
|
+
### Tampered D1 rows
|
|
293
|
+
|
|
294
|
+
Ha-Pri v2 helps if an attacker changes stored content or bound fields without also updating all matching v2 fields.
|
|
295
|
+
|
|
296
|
+
Plain SHA-256 does not help if an attacker can rewrite all row fields and recompute the public signature.
|
|
297
|
+
|
|
298
|
+
### Malformed signatures
|
|
299
|
+
|
|
300
|
+
Malformed, blank, or nonmatching signatures should produce `invalid` or `unknown` according to current helper behavior. They should not crash reads.
|
|
301
|
+
|
|
302
|
+
### Recomputed public SHA-256 signatures
|
|
303
|
+
|
|
304
|
+
Because v2 currently uses plain SHA-256, a party with all fields can recompute a matching signature. HMAC/private signing is the later answer if origin authentication becomes necessary.
|
|
305
|
+
|
|
306
|
+
### Debug endpoint leakage
|
|
307
|
+
|
|
308
|
+
Debug routes should remain authenticated. Public outputs should avoid exposing full signing payloads or internal row material unless deliberately needed.
|
|
309
|
+
|
|
310
|
+
### Secret exposure if HMAC is added later
|
|
311
|
+
|
|
312
|
+
HMAC/private signing introduces secret-management risk. Secrets must live in deployment configuration, never in docs, fixtures, npm package output, or client-visible responses.
|
|
313
|
+
|
|
314
|
+
## 9. Tests Needed Before Implementation
|
|
315
|
+
|
|
316
|
+
Future implementation should add tests before production rollout:
|
|
317
|
+
|
|
318
|
+
- D1 migration tests if the migration harness supports them.
|
|
319
|
+
- Write-path stamping tests for new rows.
|
|
320
|
+
- Dual-stamp tests proving v1 remains unchanged.
|
|
321
|
+
- Read-path verification tests for `valid`, `invalid`, and `unknown`.
|
|
322
|
+
- Old-row tests proving missing v2 fields are `unknown`, not invalid.
|
|
323
|
+
- Tampered-row tests for changed content, semantic fingerprint, adapter, timestamps, and engine version.
|
|
324
|
+
- Malformed signature tests.
|
|
325
|
+
- Debug output safety tests.
|
|
326
|
+
- Public output minimization tests.
|
|
327
|
+
- Backfill tests with complete and incomplete rows.
|
|
328
|
+
- Worker dry-run validation.
|
|
329
|
+
- HMAC/private signing tests if that later lands.
|
|
330
|
+
|
|
331
|
+
Do not add fake production-enforcement tests before implementation exists.
|
|
332
|
+
|
|
333
|
+
## 10. Rollout Phases
|
|
334
|
+
|
|
335
|
+
### Phase 0: Core helper and golden vectors
|
|
336
|
+
|
|
337
|
+
Done.
|
|
338
|
+
|
|
339
|
+
Includes:
|
|
340
|
+
|
|
341
|
+
- pure Core Ha-Pri v2 helper
|
|
342
|
+
- deterministic golden vectors
|
|
343
|
+
- valid / invalid / unknown verification behavior
|
|
344
|
+
|
|
345
|
+
### Phase 1: Storage schema design
|
|
346
|
+
|
|
347
|
+
This document.
|
|
348
|
+
|
|
349
|
+
No migration yet.
|
|
350
|
+
|
|
351
|
+
### Phase 2: Write-path dual-stamp v1 + v2
|
|
352
|
+
|
|
353
|
+
Add D1 columns and write v2 fields for new rows only. Keep v1 intact.
|
|
354
|
+
|
|
355
|
+
### Phase 3: Report-only read/debug verification
|
|
356
|
+
|
|
357
|
+
Recompute v2 on read/debug paths and report status. Do not reject rows yet.
|
|
358
|
+
|
|
359
|
+
### Phase 4: Backfill tooling
|
|
360
|
+
|
|
361
|
+
Backfill historical rows only with explicit `backfilled` or `unknown_origin` markers.
|
|
362
|
+
|
|
363
|
+
### Phase 5: Optional strict mode
|
|
364
|
+
|
|
365
|
+
Private deployments may opt into warnings or blocking for invalid rows after enough evidence.
|
|
366
|
+
|
|
367
|
+
### Phase 6: Hosted/private HMAC signing
|
|
368
|
+
|
|
369
|
+
Add origin-authenticated signing only if hosted/private use cases require it.
|
|
370
|
+
|
|
371
|
+
## 11. Non-Goals
|
|
372
|
+
|
|
373
|
+
This pass does not implement:
|
|
374
|
+
|
|
375
|
+
- D1 migration
|
|
376
|
+
- Worker enforcement
|
|
377
|
+
- read-path rejection
|
|
378
|
+
- debug endpoint changes
|
|
379
|
+
- HMAC/private signing
|
|
380
|
+
- backfill script
|
|
381
|
+
- npm publish
|
|
382
|
+
- version bump
|
|
383
|
+
- Cloudflare deploy
|
|
384
|
+
- public security claim upgrade
|
|
385
|
+
- new MCP tools
|
|
386
|
+
- ranking/scoring changes
|
|
387
|
+
- Operator/retrieve behavior
|
|
388
|
+
|
|
389
|
+
## Release Gates For Future Implementation
|
|
390
|
+
|
|
391
|
+
Before any implementation pass can claim production enforcement:
|
|
392
|
+
|
|
393
|
+
- migrations must be reviewed and dry-run
|
|
394
|
+
- new rows must dual-stamp v1 and v2
|
|
395
|
+
- v1 compatibility tests must pass
|
|
396
|
+
- v2 read verification tests must pass
|
|
397
|
+
- old-row `unknown` behavior must be proven
|
|
398
|
+
- tampered-row `invalid` behavior must be proven
|
|
399
|
+
- debug output must avoid leaking secrets or excessive internals
|
|
400
|
+
- Worker dry-run must pass
|
|
401
|
+
- Trust gate must pass with effective fail 0
|
|
402
|
+
- public docs must say exactly what is implemented
|
|
403
|
+
|
|
404
|
+
## Product Interpretation
|
|
405
|
+
|
|
406
|
+
Ha-Pri v2 is a provenance hardening lane for stored FreshContext rows. It supports the larger product story only when it stays honest:
|
|
407
|
+
|
|
408
|
+
```txt
|
|
409
|
+
candidate context in
|
|
410
|
+
decision-ready context out
|
|
411
|
+
optional provenance verification for stored rows
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
It is not a truth engine and not a substitute for authentication, authorization, or hosted tenant isolation.
|
|
@@ -22,6 +22,7 @@ This document describes release hardening practices for future FreshContext pack
|
|
|
22
22
|
- Confirm fresh consumer `npm audit --omit=dev` is clean.
|
|
23
23
|
- Run a stale-claim scan across public docs and package-facing files.
|
|
24
24
|
- Run a secret scan before sharing archives, diligence folders, or package artifacts.
|
|
25
|
+
- Keep operational demo runbooks, buyer scripts, outreach plans, diligence checklists, and private commercial materials outside the public npm package.
|
|
25
26
|
|
|
26
27
|
## Package Exclusion Checks
|
|
27
28
|
|
|
@@ -34,6 +35,7 @@ Confirm release artifacts do not include:
|
|
|
34
35
|
- Local database snapshots or SQL dumps.
|
|
35
36
|
- Private sale, buyer, target, outreach, or diligence documents.
|
|
36
37
|
- Private data-room folders.
|
|
38
|
+
- Operational demo runbooks intended for buyer calls or internal screen-share rehearsal.
|
|
37
39
|
- Local logs.
|
|
38
40
|
- Old package tarballs.
|
|
39
41
|
|
package/docs/RELEASE_NOTES.md
CHANGED
|
@@ -1,8 +1,25 @@
|
|
|
1
1
|
# FreshContext Release Notes
|
|
2
2
|
|
|
3
|
+
## 0.3.19
|
|
4
|
+
|
|
5
|
+
FreshContext 0.3.19 syncs the public MCP package with the new generic `evaluate_context` interface.
|
|
6
|
+
|
|
7
|
+
### Context Evaluation Front Door
|
|
8
|
+
|
|
9
|
+
- Adds `evaluate_context` as the primary MCP tool for caller-provided candidate context.
|
|
10
|
+
- Returns decision-first output for agents and users: decision, meaning, action, warnings, source, freshness, rank score, utility, confidence, and explanation.
|
|
11
|
+
- Keeps the boundary explicit: `evaluate_context` does not fetch, crawl, scrape, browse, read folders, or call adapters.
|
|
12
|
+
- Updates stdio smoke and Trust Scanner claim checks to expect 22 MCP tools: `evaluate_context` plus 21 read-only reference adapters.
|
|
13
|
+
|
|
14
|
+
### Public Framing
|
|
15
|
+
|
|
16
|
+
- Reframes the MCP package around FreshContext as context integrity infrastructure, not a 21-tool toolbox.
|
|
17
|
+
- Keeps the 21 adapter tools as read-only reference adapters and proof surfaces.
|
|
18
|
+
- Updates package-facing docs/spec language to point first at `candidate context -> FreshContext Core -> decision-ready context`.
|
|
19
|
+
|
|
3
20
|
## 0.3.18
|
|
4
21
|
|
|
5
|
-
FreshContext 0.3.18
|
|
22
|
+
FreshContext 0.3.18 made the MCP/Core package easier to install, validate, and explain without changing the deployed Worker runtime.
|
|
6
23
|
|
|
7
24
|
### Core and Context Evaluation
|
|
8
25
|
|
|
@@ -32,7 +49,7 @@ FreshContext 0.3.18 prepares the next npm package release without changing the d
|
|
|
32
49
|
|
|
33
50
|
### Boundaries
|
|
34
51
|
|
|
35
|
-
- No
|
|
36
|
-
- No
|
|
37
|
-
- No
|
|
38
|
-
-
|
|
52
|
+
- No Worker deploy is part of the npm package release.
|
|
53
|
+
- No hosted dashboard, billing system, Operator mode, browser crawling, or local file scanning is included.
|
|
54
|
+
- No Worker, REST handler, MCP tool schema, or existing adapter behavior changes are included in the package release itself.
|
|
55
|
+
- Future work is tracked in [`FUTURE_LANES.md`](./FUTURE_LANES.md).
|