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.
@@ -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
+
@@ -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
 
@@ -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 prepares the next npm package release without changing the deployed Worker or publishing automatically.
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 npm publish in this preparation pass.
36
- - No git tag in this preparation pass.
37
- - No deployment in this preparation pass.
38
- - No Worker, REST handler, Core runtime, MCP tool schema, or adapter behavior changes are included in the version bump itself.
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).