@hyperspell/openclaw-hyperspell 0.20.0 → 0.21.0

package/README.md

@@ -149,6 +149,7 @@ files back to Hyperspell.
 | `knowledgeGraph.enabled` | boolean | `false` | Memory Network: extract entities (people, projects, organizations, topics) from memories into `memory/` markdown files. See [Memory Network](#memory-network). |
 | `knowledgeGraph.scanIntervalMinutes` | number | `60` | Extraction cadence the setup wizard bakes into the cron job it creates. The cron job is the runtime source of truth — to change cadence after setup, edit the cron job (and keep this field in sync). |
 | `knowledgeGraph.batchSize` | number | `20` | Memories per extraction scan batch |
+| `coverageLog` | boolean | `false` | **Opt-in.** Append a local-only JSONL event whenever auto-context finds no relevant memories, so capture gaps can be told apart from ranking misses. Events include prompt text — see [Coverage log](#coverage-log). |
 | `debug` | boolean | `false` | Enable diagnostic logging. One-line diagnostics (auto-context ranked/cut/injection summaries, orientation and emotional-context injection counts) are emitted at **info** level, so they appear in `gateway.log` at default host log levels — no host `logging.level` change needed. Verbose output (per-request/response dumps, per-candidate score lines) stays at debug level. |
 | `dreaming.enabled` | boolean | `false` | Allow `memory-core` to sidecar-load so Dreaming can consolidate local session transcripts into `workspace/MEMORY.md`. See [Running alongside Dreaming](#running-alongside-dreaming). |
 
@@ -271,6 +272,61 @@ composite = relevance
 Chatter is additionally capped at `chatterQuota` results per injection,
 regardless of score.
 
+Provenance is a signal too: an optional `sourceWeights` map multiplies a
+result's **base relevance** (before the kind boosts/penalties are added) by a
+per-source factor, so "a journaled Notion page is more intentional memory than
+a titled Slack aside on the same topic" is expressible. Any source not listed
+— including sources that don't exist yet — is neutral (`1.0`); the shipped
+default is `{}`, a strict no-op. It weights sources already in the result set;
+to *exclude* a source, use the `sources` filter instead (weights of 0 are
+rejected at load with exactly that pointer). Suggested starting points, priors
+to seed your own tuning rather than measured truth: authored systems slightly
+up (`notion` 1.15, drive/box/dropbox 1.1), conversational exhaust slightly
+down (`slack`/`microsoft_teams` 0.85, `trace` 0.8) — magnitudes small enough
+to break ties, never to override a real relevance gap. Typos in weight keys
+are not schema errors (new backend sources must not fail validation); with
+`debug: true` unknown keys are flagged once at startup in `gateway.log`.
+
+Selected results are also checked against each other for **near-duplicates**:
+when the same memory exists in several forms (a re-synced doc section, a
+`remember` note quoting it, a curated copy of a hot-buffer row), every copy
+clears the threshold, none is chatter, and pre-dedup they filled multiple
+injection slots with one piece of information. Each candidate's lead text is
+compared against already-selected results by token overlap; above
+`dedupThreshold` (0.8) the copy is skipped and its slot passes to the
+next-ranked *different* memory. Skipped copies never consume the chatter
+quota. Set `dedupThreshold: 0` to disable. Paraphrased duplicates (same fact,
+different words) are beyond a string measure and out of scope.
+
+Within each selected memory, the second excerpt earns its place: a result
+renders up to two highlight bullets, and the runner-up rides along only when
+its score is within 0.15 of the top one's — a .95/.40 pair renders one bullet
+(the distant second is usually a weaker paraphrase), a .95/.85 pair renders
+both. The top highlight is always kept, so a selected memory never disappears
+from the injection because of this rule.
+
+An optional **elbow cutoff** (`ranking.elbow`, **off by default**) stops
+injecting at a natural score cliff instead of always filling `maxResults`: a
+narrow query backed by 3 genuinely relevant memories no longer pads the
+context with a plateau of marginal ones that happen to clear the threshold.
+It is strictly conservative — it only ever cuts *earlier*, never later, never
+below `minResults` (default 3), and when no clear cliff exists (gradual
+decline, flat plateau) selection is identical to today. A cliff means the
+drop from the last accepted result is both large against the decline seen so
+far (`gapRatio` × mean gap, default 2.5×) *and* material in absolute terms
+(`minGap`, default 0.05). Before enabling, run
+`node --experimental-strip-types docs/elbow-scan.mjs` against your real data
+to check firing rate and cut depth (with `debug: true` the live verdict shows
+in `gateway.log` as `auto-context: elbow stopped at k (ceiling N)`).
+
+Age matters too, gently: results accrue a small **recency penalty** that grows
+with age (exponential decay, 90-day half-life by default) and is hard-capped at
+`recencyMaxPenalty` (0.1) so it can break near-ties toward current information
+but never bury a strong old match. Deliberately-kept memory (curated/story)
+ages at half rate (`recencyCuratedFactor`) — an old truth you chose to keep
+still beats a fresh shallow echo. Results without a timestamp are never
+penalized. Set `recencyHalfLifeDays: 0` to disable.
+
 **`storyBoost` does nothing until you set `storyTerms`.** The default is `[]`,
 so no result ever classifies as "story". Set it to the distinctive proper nouns
 of your active work — the title, character names, a project codename, invented
@@ -313,7 +369,7 @@ Tips:
   The `hyperspell_search` tool and `/getcontext` return raw relevance order —
   don't test `storyTerms` there and conclude it's broken.
 - To verify it's working, enable `debug: true` and watch `gateway.log` for the
-  per-search tally (`auto-context: ranked {...} candidates → selected {...}`) —
+  per-search tally (`auto-context: ranked {...} candidates → selected {...}`) and the cut tally (threshold / max-results / elbow / near-duplicate / chatter-quota) —
   it appears at default host log levels. The per-candidate lines
   (`[story] 0.47→0.82 The Lighthouse Keeper — Chapter 3`), which show story
   matches even when they lose to the threshold, are debug-level and also need
@@ -329,10 +385,34 @@ Full knobs and defaults:
   "storyBoost": 0.15,       // extra lift for storyTerms matches (stacks with curationBoost)
   "storyTerms": [],         // REQUIRED for storyBoost to do anything
   "candidateMultiplier": 3, // fetch this × maxResults candidates before re-ranking
-  "chatterQuota": 2         // hard cap on chatter results per injection
+  "chatterQuota": 2,        // hard cap on chatter results per injection
+  "recencyHalfLifeDays": 90,  // age at which half the recency penalty has accrued (0 = off)
+  "recencyMaxPenalty": 0.1,   // ceiling on the recency penalty — a tiebreaker, never a burial
+  "recencyCuratedFactor": 0.5, // kept memory (curated/story) ages at this fraction of the rate
+  "sourceWeights": {},        // per-source multiplier on base relevance; unlisted = 1.0
+  "dedupThreshold": 0.8,      // token-overlap ratio that skips a near-duplicate (0 = off)
+  "elbow": {                  // stop early at a natural score cliff (opt-in)
+    "enabled": false,
+    "minResults": 3,          // never cut below this many accepted results
+    "gapRatio": 2.5,          // cliff = drop >= this multiple of the mean gap so far...
+    "minGap": 0.05            // ...AND at least this big on the raw composite scale
+  }
 }
 ```
 
+### Coverage log
+
+No ranking tweak can surface a memory that was never captured — and by default nothing distinguishes "ranking failed" from "it was never stored." With `coverageLog: true`, every auto-context turn that injects **no** memory sections appends one line to `<workspaceDir>/.hyperspell-coverage.jsonl`:
+
+- `outcome: "empty"` — the search succeeded but returned zero candidates (a capture question: was this ever stored?)
+- `outcome: "below_threshold"` — candidates existed but none cleared `relevanceThreshold`; `topScore` vs `threshold` says how near the miss was (a ranking question)
+
+Failed searches never produce events — backend-unavailable is not "no memories." In multi-user mode there is one event per turn with per-lane detail, and a lane whose search failed is recorded as `status: "error"`, never as zero candidates.
+
+**Local-only guarantee:** the log is written only to the workspace directory and is never sent to Hyperspell or anywhere remote. Because each event carries the triggering prompt (truncated to 500 chars), the feature is **off by default** — prompt text reaches disk only if you explicitly opt in. The file is capped at 5 MB with one `.old` rotation generation (~10 MB total), so content ages out instead of accumulating.
+
+Review with `jq`, e.g.: `jq -r '[.ts, .outcome, .topScore, .prompt] | @tsv' ~/.openclaw/workspace/.hyperspell-coverage.jsonl` — after a week or two of labeling (capture gap / ranking near-miss / correct absence), the tallies say whether the next investment belongs in capture or ranking. Delete the file when done.
+
 ### `excludeChannels` is forward-only
 
 Adding a channel to `excludeChannels` stops all future injection/writes/tools for that conversation, but does **not** remove content that was synced before the channel was quarantined.

package/dist/commands/setup.js

@@ -293,6 +293,7 @@ async function runSetup() {
                 maxResults: 10,
                 relevanceThreshold: 0.6,
                 ranking: DEFAULT_RANKING,
+                coverageLog: false,
                 debug: false,
                 knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
                 startupOrientation: {

package/dist/config.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DEFAULT_RANKING } from "./lib/ranking.js";
+import { DEFAULT_ELBOW, DEFAULT_RANKING, } from "./lib/ranking.js";
 /**
  * Convert user-facing scope names (which may contain hyphens) to SDK-safe
  * metadata values (alphanumeric + underscore only). Must be applied at every
@@ -27,12 +27,13 @@ const ALLOWED_KEYS = [
     "maxResults",
     "relevanceThreshold",
     "ranking",
+    "coverageLog",
     "debug",
     "knowledgeGraph",
     "multiUser",
     "dreaming",
 ];
-const VALID_SOURCES = [
+export const VALID_SOURCES = [
     "reddit",
     "notion",
     "slack",
@@ -95,6 +96,27 @@ function parseWatchPaths(raw) {
         };
     });
 }
+/** Per-source multipliers: non-numeric values silently skip (num()'s
+ * convention); explicit non-positive values throw (a 0 weight is a filtering
+ * decision wearing a weighting costume — the sources filter is the right
+ * tool, and the error says so). Keys lowercase but are NOT validated against
+ * VALID_SOURCES: the backend adds sources independently of plugin releases,
+ * and an unmatched key is a harmless neutral no-op (startup diag logs it). */
+function parseSourceWeights(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "number")
+            continue;
+        if (!Number.isFinite(v) || v <= 0) {
+            throw new Error(`ranking.sourceWeights.${k} must be a positive number (got ${v}); ` +
+                `to exclude a source entirely, use the "sources" filter instead`);
+        }
+        out[k.trim().toLowerCase()] = v;
+    }
+    return out;
+}
 function parseRanking(raw) {
     const r = (raw ?? {});
     const num = (v, d) => (typeof v === "number" ? v : d);
@@ -116,6 +138,24 @@ function parseRanking(raw) {
             : DEFAULT_RANKING.storyTerms,
         candidateMultiplier: Math.max(1, num(r.candidateMultiplier, DEFAULT_RANKING.candidateMultiplier)),
         chatterQuota: Math.max(0, num(r.chatterQuota, DEFAULT_RANKING.chatterQuota)),
+        recencyHalfLifeDays: Math.max(0, num(r.recencyHalfLifeDays, DEFAULT_RANKING.recencyHalfLifeDays)),
+        recencyMaxPenalty: Math.max(0, num(r.recencyMaxPenalty, DEFAULT_RANKING.recencyMaxPenalty)),
+        recencyCuratedFactor: Math.min(1, Math.max(0, num(r.recencyCuratedFactor, DEFAULT_RANKING.recencyCuratedFactor))),
+        sourceWeights: parseSourceWeights(r.sourceWeights),
+        dedupThreshold: Math.min(1, Math.max(0, num(r.dedupThreshold, DEFAULT_RANKING.dedupThreshold))),
+        elbow: parseElbow(r.elbow),
+    };
+}
+function parseElbow(raw) {
+    const e = (raw ?? {});
+    const num = (v, d) => (typeof v === "number" ? v : d);
+    return {
+        enabled: e.enabled ?? DEFAULT_ELBOW.enabled,
+        // >= 2: at least one gap must exist before meanGap is defined (the
+        // first accepted result never records a gap).
+        minResults: Math.max(2, num(e.minResults, DEFAULT_ELBOW.minResults)),
+        gapRatio: Math.max(1, num(e.gapRatio, DEFAULT_ELBOW.gapRatio)),
+        minGap: Math.max(0, num(e.minGap, DEFAULT_ELBOW.minGap)),
     };
 }
 function parseSources(raw) {
@@ -376,6 +416,10 @@ export function parseConfig(raw) {
         maxResults: cfg.maxResults ?? 10,
         relevanceThreshold: cfg.relevanceThreshold ?? 0.6,
         ranking: parseRanking(cfg.ranking),
+        // Default OFF (deviates from proposal 15 §6 by maintainer decision):
+        // coverage events carry prompt text, so nothing is written to disk
+        // unless the operator explicitly opts in.
+        coverageLog: cfg.coverageLog ?? false,
         debug: cfg.debug ?? false,
         knowledgeGraph: {
             enabled: kgRaw.enabled ?? false,

package/dist/hooks/auto-context.js

@@ -2,6 +2,7 @@ import { appendFileSync } from "node:fs";
 import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
 import { excludeFilterFor, mergeWithExclude } from "../lib/filters.js";
 import { explainSelection, kindTally, rerank, } from "../lib/ranking.js";
+import { recordCoverageEvent, } from "../lib/coverage-log.js";
 import { classifySearchError, logSearchError } from "../lib/search-error.js";
 import { resolveCurrentSessionId } from "../lib/session.js";
 import { recordSender, senderIdFromCtx } from "../lib/speaker-tracker.js";
@@ -54,22 +55,38 @@ function formatHighlightBullets(results, maxResults, threshold) {
         return null;
     return sections.join("\n\n");
 }
+// A second highlight rides along only when it is within this much of the top
+// one's score — a distant second is dilution inside a correct pick (proposal
+// 12). Absolute difference (not a ratio) to match every other score rule in
+// this pipeline; 0.15 is "one storyBoost's worth" on the composite scale.
+// Deliberately a constant, not config: a formatting heuristic two levels
+// below anything a user reasons about — promote to ranking.highlightGap only
+// if live tuning proves deployments actually differ.
+const HIGHLIGHT_GAP = 0.15;
 /**
  * Format already-SELECTED composite-ranked results (threshold + chatter quota
  * applied upstream by selectRanked). Highlights are floored at the lower of
  * (threshold, the result's own base relevance), so we don't hide the very lines
- * that define a boosted-but-quiet memory.
+ * that define a boosted-but-quiet memory. Exported for direct testing.
  */
-function formatSelected(selected, threshold) {
+export function formatSelected(selected, threshold) {
     const sections = [];
     for (const r of selected) {
         const hiFloor = Math.min(threshold, r._base);
-        const chosen = [...r.highlights]
+        const passing = [...r.highlights]
             .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
-            .filter((h) => (h.score ?? 0) >= hiFloor)
-            .slice(0, 2);
-        if (chosen.length === 0)
+            .filter((h) => (h.score ?? 0) >= hiFloor);
+        if (passing.length === 0)
             continue;
+        // Floor first (is this highlight relevant at all?), gap second (is the
+        // runner-up close enough to the winner to be worth its tokens?). The TOP
+        // highlight is always kept — the lowered hiFloor exists to protect
+        // boosted-but-quiet memories, and the gap rule must never re-hide them; a
+        // selected result can never format to fewer sections than today.
+        const [top, second] = passing;
+        const chosen = second && (top.score ?? 0) - (second.score ?? 0) <= HIGHLIGHT_GAP
+            ? [top, second]
+            : [top];
         const title = r.title ?? `[${r.source}]`;
         const bullets = chosen
             .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round((h.score ?? 0) * 100)}%]`)
@@ -168,7 +185,12 @@ export function dropCurrentSession(results, currentSessionId) {
     }
     return kept;
 }
-export function buildAutoContextHandler(client, cfg) {
+/** Highest raw relevance among candidates — `topScore 0.54` vs `threshold 0.6`
+ * is a ranking near-miss; `0.12` means the vault has nothing close (capture). */
+function topScoreOf(results) {
+    return results.length ? Math.max(...results.map((r) => r.score ?? 0)) : null;
+}
+export function buildAutoContextHandler(client, cfg, opts) {
     return async (event, ctx) => {
         const prompt = event.prompt;
         if (!prompt || prompt.length < 5)
@@ -184,7 +206,7 @@ export function buildAutoContextHandler(client, cfg) {
         // Multi-user path
         if (cfg.multiUser) {
             const resolved = resolveUser(ctx, cfg);
-            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId);
+            return multiUserSearch(client, cfg, prompt, resolved, currentSessionId, opts?.stateRoot);
         }
         // Single-user path — preserves main's highlights + threshold behavior
         log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
@@ -195,13 +217,19 @@ export function buildAutoContextHandler(client, cfg) {
             const limit = ranking.enabled
                 ? cfg.maxResults * ranking.candidateMultiplier
                 : cfg.maxResults;
-            const results = dropCurrentSession(await client.search(prompt, { limit, filter: excludeFilterFor(cfg) }), currentSessionId);
+            // Kept as two steps so the coverage event below can report the pre-drop
+            // fetch count (a session-echo-dominated pool must be visible as such).
+            const rawResults = await client.search(prompt, {
+                limit,
+                filter: excludeFilterFor(cfg),
+            });
+            const results = dropCurrentSession(rawResults, currentSessionId);
             let formatted;
             if (ranking.enabled) {
                 const ranked = rerank(results, ranking);
                 // Threshold + chatter quota applied here, so a high-similarity echo can
                 // inform but never flood (the quota bounds count; the penalty bounds rank).
-                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota);
+                const explained = explainSelection(ranked, cfg.maxResults, cfg.relevanceThreshold, ranking.chatterQuota, ranking.dedupThreshold, ranking.elbow);
                 logScoreSamples(prompt, currentSessionId, "single", explained, cfg.relevanceThreshold);
                 const selected = explained.filter((e) => e.selected).map((e) => e.result);
                 // Candidates → selected kind tally, logged UNCONDITIONALLY (unlike the
@@ -217,6 +245,11 @@ export function buildAutoContextHandler(client, cfg) {
                 // nothing is injected (e.g. chatterQuota 0 with only chatter clearing
                 // the threshold). Stable "auto-context: cut" prefix for log greps.
                 // flatMap (not filter) so TS narrows to the cut member of the union.
+                // Elbow verdict — the live-validation instrument for proposal 13's
+                // rollout: firing rate + cut depth come straight from this line.
+                if (ranking.elbow.enabled && explained.some((e) => e.cut === "elbow")) {
+                    log.diag(`auto-context: elbow stopped at ${selected.length} (ceiling ${cfg.maxResults})`);
+                }
                 const cuts = explained.flatMap((e) => (e.selected ? [] : [e]));
                 if (cuts.length > 0) {
                     const cutTally = cuts.reduce((acc, e) => ((acc[e.cut] = (acc[e.cut] ?? 0) + 1), acc), {});
@@ -241,6 +274,23 @@ export function buildAutoContextHandler(client, cfg) {
             // every-turn banner (which reads as framing and trains search-as-ritual).
             if (!formatted) {
                 log.debug("auto-context: no relevant memories found");
+                // Coverage signal (proposal 15): search SUCCEEDED but injected nothing —
+                // durably distinguish "never captured" (empty) from "captured but ranked
+                // out" (below_threshold). Thrown searches never reach here (the catch
+                // below owns them), so availability blips can't pollute the log.
+                if (cfg.coverageLog) {
+                    recordCoverageEvent({
+                        outcome: results.length > 0 ? "below_threshold" : "empty",
+                        prompt,
+                        fetched: rawResults.length,
+                        candidates: results.length,
+                        droppedCurrentSession: rawResults.length - results.length,
+                        topScore: topScoreOf(results),
+                        threshold: cfg.relevanceThreshold,
+                        ranking: ranking.enabled,
+                        sessionId: currentSessionId,
+                    }, opts?.stateRoot);
+                }
                 return;
             }
             return { prependContext: wrapContext(formatted) };
@@ -259,7 +309,7 @@ export function buildAutoContextHandler(client, cfg) {
 // single-user path only: this path never runs rerank/explainSelection, so
 // there is no composite score to attribute. If ranking ever lands here, call
 // logScoreSamples with scope "personal" / "shared" per search.
-async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId) {
+async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId, stateRoot) {
     const multiUser = cfg.multiUser;
     const isKnownSender = !!resolved?.resolved;
     const includeShared = multiUser.includeSharedInSearch;
@@ -297,9 +347,18 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     let idx = 0;
     let personalResults = [];
     let sharedResults = [];
+    // Per-lane fulfillment + pre-drop counts feed the coverage event below: a
+    // lane that REJECTED must never be recorded as "zero candidates" (#39's
+    // unavailable-is-not-empty distinction, kept intact in the log schema).
+    let personalOk = false;
+    let sharedOk = false;
+    let rawPersonalCount = 0;
+    let rawSharedCount = 0;
     if (personalSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            personalOk = true;
+            rawPersonalCount = r.value.length;
             personalResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -309,6 +368,8 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     if (sharedSearch) {
         const r = settled[idx++];
         if (r.status === "fulfilled") {
+            sharedOk = true;
+            rawSharedCount = r.value.length;
             sharedResults = dropCurrentSession(r.value, currentSessionId);
         }
         else {
@@ -342,6 +403,49 @@ async function multiUserSearch(client, cfg, prompt, resolved, currentSessionId)
     const haveMemorySections = sections.some((s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"));
     if (!haveMemorySections) {
         log.debug("auto-context: no relevant memories found");
+        // Coverage signal (proposal 15): one event per turn (not per lane), with
+        // per-lane detail so "personal lane was down" is never misread as
+        // "personal memory is empty". Written only when at least one lane
+        // fulfilled — every-lane-failed is an availability event (#39), already
+        // logged by logSearchError above, and "unknown" is not "zero".
+        if (cfg.coverageLog) {
+            const lanes = [];
+            if (personalSearch)
+                lanes.push(personalOk
+                    ? {
+                        lane: "personal",
+                        status: "ok",
+                        candidates: personalResults.length,
+                        topScore: topScoreOf(personalResults),
+                    }
+                    : { lane: "personal", status: "error" });
+            if (sharedSearch)
+                lanes.push(sharedOk
+                    ? {
+                        lane: "shared",
+                        status: "ok",
+                        candidates: sharedResults.length,
+                        topScore: topScoreOf(sharedResults),
+                    }
+                    : { lane: "shared", status: "error" });
+            if (lanes.some((l) => l.status === "ok")) {
+                const candidates = personalResults.length + sharedResults.length;
+                const fetched = rawPersonalCount + rawSharedCount;
+                recordCoverageEvent({
+                    outcome: candidates > 0 ? "below_threshold" : "empty",
+                    prompt,
+                    fetched,
+                    candidates,
+                    droppedCurrentSession: fetched - candidates,
+                    topScore: topScoreOf([...personalResults, ...sharedResults]),
+                    threshold: cfg.relevanceThreshold,
+                    ranking: cfg.ranking.enabled,
+                    sessionId: currentSessionId,
+                    userId: resolved?.userId,
+                    lanes,
+                }, stateRoot);
+            }
+        }
         if (isKnownSender && resolved) {
             const contextLine = resolved.context ? ` ${resolved.context}` : "";
             return {

package/dist/index.js

@@ -1,7 +1,7 @@
 import { HyperspellClient } from "./client.js";
 import { registerCommands } from "./commands/slash.js";
 import { registerCliCommands } from "./commands/setup.js";
-import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.js";
+import { parseConfig, hyperspellConfigSchema, getWorkspaceDir, VALID_SOURCES } from "./config.js";
 import { buildAutoContextHandler } from "./hooks/auto-context.js";
 import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
 import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
@@ -79,6 +79,13 @@ export default {
         }
         const cfg = parseConfig(api.pluginConfig);
         initLogger(api.logger, cfg.debug);
+        // sourceWeights keys are deliberately not schema-validated (new backend
+        // sources must not fail manifest validation), so a typo is a silent
+        // neutral no-op — surface it once at startup instead.
+        const unknownWeightKeys = Object.keys(cfg.ranking.sourceWeights).filter((k) => !VALID_SOURCES.includes(k));
+        if (unknownWeightKeys.length > 0) {
+            log.diag(`ranking.sourceWeights keys not in the known source list (typo? they weight nothing): ${unknownWeightKeys.join(", ")}`);
+        }
         const client = new HyperspellClient(cfg);
         // Channel quarantine (cfg.excludeChannels): excluded conversations get no
         // memory surface in either direction. Guard the shared choke points here —

package/dist/lib/coverage-log.js

@@ -0,0 +1,47 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getWorkspaceDir } from "../config.js";
+import { log } from "../logger.js";
+export const COVERAGE_LOG_NAME = ".hyperspell-coverage.jsonl";
+// Truncation bounds line size and what sits on disk; 500 chars is enough to
+// judge "should this have found something" without full-prompt fidelity.
+const MAX_PROMPT_CHARS = 500;
+// One-generation rotation caps the total footprint at ~2× this (current + .old).
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+/**
+ * Append one coverage event to the LOCAL-ONLY coverage log
+ * (`<workspaceDir>/.hyperspell-coverage.jsonl`). Never sent to the backend —
+ * same trust domain as the hot-buffer state files already living there.
+ * Prompt text is sensitive plaintext, so writes happen only behind the
+ * explicit `coverageLog: true` opt-in (checked at call sites, default OFF).
+ * Best-effort by contract: any failure is swallowed (debug-logged) — a
+ * coverage write must never throw into, block, or delay the turn.
+ */
+export function recordCoverageEvent(event, stateRoot) {
+    try {
+        const dir = stateRoot ?? getWorkspaceDir();
+        const p = path.join(dir, COVERAGE_LOG_NAME);
+        rotateIfOversized(p);
+        const line = JSON.stringify({
+            v: 1,
+            ts: new Date().toISOString(),
+            ...event,
+            prompt: event.prompt.slice(0, MAX_PROMPT_CHARS),
+        });
+        fs.appendFileSync(p, `${line}\n`);
+    }
+    catch (err) {
+        log.debug(`coverage-log: append failed — ${String(err)}`);
+    }
+}
+/** One-generation rotation: current file > cap → rename to .old (replacing the
+ * previous .old), start fresh. Total footprint bounded at ~2× MAX_LOG_BYTES. */
+function rotateIfOversized(p) {
+    try {
+        if (fs.statSync(p).size > MAX_LOG_BYTES)
+            fs.renameSync(p, `${p}.old`);
+    }
+    catch {
+        /* missing file or rename race — appendFileSync creates/handles it */
+    }
+}