@lmzhen/dsh-evolution-activity 0.44.0 → 0.46.0

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.
Files changed (47) hide show
  1. package/lib/feedback/index.js +690 -0
  2. package/lib/index.js +23 -18
  3. package/lib/learning-graph/index.js +538 -0
  4. package/lib/replay/index.js +286 -0
  5. package/lib/threat/index.js +70 -0
  6. package/lib/types/feedback/index.d.ts +179 -0
  7. package/lib/types/feedback/index.js +899 -0
  8. package/lib/types/index.js +335 -0
  9. package/lib/types/learning-graph/index.d.ts +178 -0
  10. package/lib/types/learning-graph/index.js +712 -0
  11. package/lib/types/replay/index.d.ts +182 -0
  12. package/lib/types/replay/index.js +404 -0
  13. package/lib/types/threat/index.d.ts +35 -0
  14. package/lib/types/threat/index.js +119 -0
  15. package/locale/feedback/de.json +6 -0
  16. package/locale/feedback/en.json +6 -0
  17. package/locale/feedback/es.json +6 -0
  18. package/locale/feedback/fr.json +6 -0
  19. package/locale/feedback/ja.json +6 -0
  20. package/locale/feedback/pt.json +6 -0
  21. package/locale/feedback/ru.json +6 -0
  22. package/locale/feedback/zh.json +6 -0
  23. package/locale/learning-graph/de.json +6 -0
  24. package/locale/learning-graph/en.json +6 -0
  25. package/locale/learning-graph/es.json +6 -0
  26. package/locale/learning-graph/fr.json +6 -0
  27. package/locale/learning-graph/ja.json +6 -0
  28. package/locale/learning-graph/pt.json +6 -0
  29. package/locale/learning-graph/ru.json +6 -0
  30. package/locale/learning-graph/zh.json +6 -0
  31. package/locale/replay/de.json +6 -0
  32. package/locale/replay/en.json +6 -0
  33. package/locale/replay/es.json +6 -0
  34. package/locale/replay/fr.json +6 -0
  35. package/locale/replay/ja.json +6 -0
  36. package/locale/replay/pt.json +6 -0
  37. package/locale/replay/ru.json +6 -0
  38. package/locale/replay/zh.json +6 -0
  39. package/locale/threat/de.json +6 -0
  40. package/locale/threat/en.json +6 -0
  41. package/locale/threat/es.json +6 -0
  42. package/locale/threat/fr.json +6 -0
  43. package/locale/threat/ja.json +6 -0
  44. package/locale/threat/pt.json +6 -0
  45. package/locale/threat/ru.json +6 -0
  46. package/locale/threat/zh.json +6 -0
  47. package/package.json +30 -8
@@ -0,0 +1,286 @@
1
+ import { loadActivityState } from "../index.js";
2
+ import z from "@deepseek-ai/schemastery";
3
+ import { clampedNumber, evolutionHome, evolutionIoAdapter } from "@lmzhen/dsh-evolution-core";
4
+ //#region lib/types/replay/index.js
5
+ /**
6
+ * Replay/A-B evaluation for evolution plans.
7
+ *
8
+ * The pure scoring functions remain deterministic and runtime-free. The DSH
9
+ * driver records every `evolution/plan-applied` process event (payload v2,
10
+ * with sessionId) into an in-memory leaderboard and exposes `/evolution
11
+ * replay` (via the `/evolution` command family) for comparison, so a human can
12
+ * A/B review policy/prompt changes against real plan outcomes.
13
+ *
14
+ * V24-13 (v24): the in-memory leaderboard is BACKFILLED at mount from the
15
+ * `evolution-activity` sidecar (`$DSH_HOME/evolution/activity.json`) — the
16
+ * header previously claimed "durability across restarts is the
17
+ * evolution-activity store's job" while nothing ever read the sidecar, so a
18
+ * restart emptied `/evolution replay` and the persisted history sat unread.
19
+ * Records are fed in sidecar order (oldest first); the driver's `maxPlans`
20
+ * window keeps the newest. Best-effort: a missing/unreadable sidecar starts
21
+ * the leaderboard empty, exactly as before.
22
+ * @module @lmzhen/dsh-evolution-replay
23
+ */
24
+ const DEFAULT_WEIGHTS = {
25
+ accepted: 10,
26
+ rejectedPenalty: 15,
27
+ evidence: 2,
28
+ cost: .001
29
+ };
30
+ /** The four clampable weight fields, in report order (V4-40 warn). */
31
+ const WEIGHT_FIELDS = [
32
+ "accepted",
33
+ "rejectedPenalty",
34
+ "evidence",
35
+ "cost"
36
+ ];
37
+ const Config = z.object({
38
+ maxPlans: z.number().min(1).default(50),
39
+ weights: z.object({
40
+ accepted: z.number().min(1).default(10),
41
+ rejectedPenalty: z.number().min(1).default(15),
42
+ evidence: z.number().min(1).default(2),
43
+ cost: z.number().min(0).default(.001)
44
+ }).default(DEFAULT_WEIGHTS)
45
+ });
46
+ /**
47
+ * Clamp a weights object to its per-field domain (G3.1). `accepted`,
48
+ * `rejectedPenalty` and `evidence` are positive multipliers (min 1 — a zero or
49
+ * negative weight would silently drop a scoring term or reverse its sign);
50
+ * `cost` may be 0 (0 means "no cost penalty"), so its min is 0. NaN, ±Infinity
51
+ * and out-of-range values fall back to the default for that field.
52
+ */
53
+ function clampReplayWeights(weights, fallback = DEFAULT_WEIGHTS) {
54
+ return {
55
+ accepted: clampedNumber(weights?.accepted, fallback.accepted, { min: 1 }),
56
+ rejectedPenalty: clampedNumber(weights?.rejectedPenalty, fallback.rejectedPenalty, { min: 1 }),
57
+ evidence: clampedNumber(weights?.evidence, fallback.evidence, { min: 1 }),
58
+ cost: clampedNumber(weights?.cost, fallback.cost, { min: 0 })
59
+ };
60
+ }
61
+ function scorePlan(plan, weights = DEFAULT_WEIGHTS) {
62
+ return plan.acceptedOps * weights.accepted - plan.rejectedOps * weights.rejectedPenalty + plan.evidenceQuotes * weights.evidence - plan.estimatedInputChars * weights.cost;
63
+ }
64
+ function comparePlans(plans, weights = DEFAULT_WEIGHTS) {
65
+ if (plans.length === 0) return {
66
+ winner: null,
67
+ margin: null,
68
+ plans,
69
+ report: "没有可比较的计划。"
70
+ };
71
+ const scored = plans.map((plan) => ({
72
+ plan,
73
+ score: scorePlan(plan, weights)
74
+ })).sort((a, b) => b.score - a.score);
75
+ const winner = scored[0];
76
+ if (!winner) return {
77
+ winner: null,
78
+ margin: null,
79
+ plans,
80
+ report: "没有可比较的计划。"
81
+ };
82
+ const runnerUp = scored[1];
83
+ const margin = runnerUp ? winner.score - runnerUp.score : null;
84
+ const singleNote = runnerUp ? "" : "\n(single plan recorded — margin is not a comparison)";
85
+ return {
86
+ winner: winner.plan.policyId,
87
+ margin,
88
+ plans,
89
+ report: scored.map(({ plan, score }) => `${plan.policyId}: ${score.toFixed(1)} (${plan.acceptedOps} accepted, ${plan.rejectedOps} rejected${(plan.skippedUnread ?? 0) > 0 ? `, ${plan.skippedUnread} op(s) skipped (skill not read this session)` : ""}${(plan.executionFailures ?? 0) > 0 ? `, ${plan.executionFailures} failed${plan.executionError !== void 0 ? `: ${plan.executionError}` : ""}` : ""})`).join("\n") + singleNote
90
+ };
91
+ }
92
+ var EvolutionReplayDriver = class EvolutionReplayDriver {
93
+ plans = [];
94
+ maxPlans;
95
+ /** V25-01 (v25): backfill-once latch — see {@link EvolutionReplayDriver.backfill}. */
96
+ backfilled = false;
97
+ /** FLOW6-6 (v43): the backfill source was unreadable (newer format or corrupt
98
+ * bytes) — carried into every comparison so an empty leaderboard is never
99
+ * presented as "nothing was recorded". PLAN S5.1 (2026-09-16): this holds the
100
+ * most recent READ's verdict, not the first one — {@link EvolutionReplayDriver.markSourceReadable}
101
+ * clears it on a later clean read, so the qualification reflects the present
102
+ * instead of latching for the driver lifetime. */
103
+ sourceCorrupt = false;
104
+ /** 0.18.1 (S3): the backfill READ itself failed — held as its message. A
105
+ * thrown read used to skip both markers, so `sourceCorrupt` kept whatever
106
+ * the previous read said and a failed read presented as a clean one. Cleared
107
+ * by any ANSWERED read; never sets `sourceCorrupt` (a failed read is not
108
+ * evidence that the bytes are corrupt). */
109
+ sourceReadFailure = null;
110
+ /** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
111
+ * plan-applied landing inside the one-shot `loadActivityState` read window is
112
+ * recorded live AND persisted into the sidecar the backfill is reading —
113
+ * `backfill()` drops those ids so the event is not counted twice.
114
+ *
115
+ * V27 INS-05: the set is BOUNDED. `backfill()` is the only place that cleared
116
+ * it, so a sidecar load that never succeeded (the inject callback's catch
117
+ * warns and does not retry until the io dependency is replaced) let every
118
+ * live plan id accumulate for the process lifetime. Past
119
+ * PRE_BACKFILL_ID_CAP the oldest ids are dropped: the dedupe window is then
120
+ * finite, and a dropped duplicate can at worst repeat an entry inside the
121
+ * `maxPlans` window instead of growing memory without bound. */
122
+ preBackfillIds = /* @__PURE__ */ new Set();
123
+ /** Upper bound on {@link EvolutionReplayDriver.preBackfillIds} (V27 INS-05). */
124
+ static PRE_BACKFILL_ID_CAP = 4096;
125
+ weights;
126
+ constructor(config = {}, warn = () => {}) {
127
+ const maxPlans = clampedNumber(config.maxPlans ?? 50, 50, { min: 1 });
128
+ this.maxPlans = maxPlans;
129
+ if (config.maxPlans !== void 0 && maxPlans !== config.maxPlans) warn(`evolution-replay: maxPlans=${String(config.maxPlans)} is invalid; falling back to the default 50`);
130
+ const rawWeights = config.weights;
131
+ this.weights = clampReplayWeights(rawWeights);
132
+ if (rawWeights !== void 0) {
133
+ const clampedFields = WEIGHT_FIELDS.filter((field) => field in rawWeights && this.weights[field] !== rawWeights[field]);
134
+ if (clampedFields.length > 0) warn(`evolution-replay: weights ${clampedFields.join(", ")} provided an invalid value; falling back to the default`);
135
+ }
136
+ }
137
+ record(plan) {
138
+ if (!this.backfilled) {
139
+ this.preBackfillIds.add(plan.planId);
140
+ while (this.preBackfillIds.size > EvolutionReplayDriver.PRE_BACKFILL_ID_CAP) {
141
+ const oldest = this.preBackfillIds.keys().next().value;
142
+ if (oldest === void 0) break;
143
+ this.preBackfillIds.delete(oldest);
144
+ }
145
+ }
146
+ this.plans.push(this.toPlan(plan));
147
+ if (this.plans.length > this.maxPlans) this.plans.shift();
148
+ }
149
+ /**
150
+ * v29 RPL-02: the activity/event record → scored-plan mapping, extracted
151
+ * from `record` so `backfill` can place sidecar plans at the CHRONOLOGICAL
152
+ * head of the window instead of appending them after this boot's live plans
153
+ * (the old order made the FIFO evict the freshest live plan first).
154
+ */
155
+ toPlan(plan) {
156
+ const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
157
+ const countOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
158
+ const memoryApplied = count(plan.memoryApplied);
159
+ const skillApplied = count(plan.skillApplied);
160
+ return {
161
+ policyId: typeof plan.policyFingerprint === "string" && plan.policyFingerprint.length > 0 ? plan.policyFingerprint : plan.planId,
162
+ acceptedOps: memoryApplied + skillApplied,
163
+ rejectedOps: count(plan.rejectedOps),
164
+ memoryOps: memoryApplied,
165
+ skillOps: skillApplied,
166
+ evidenceQuotes: countOr(plan.evidenceQuotes, memoryApplied + skillApplied),
167
+ estimatedInputChars: count(plan.estimatedInputChars),
168
+ skippedUnread: count(plan.skippedUnread),
169
+ executionFailures: count(plan.executionFailures),
170
+ ...typeof plan.executionError === "string" ? { executionError: plan.executionError } : {}
171
+ };
172
+ }
173
+ /**
174
+ * V25-01 (v25): backfill the leaderboard from the activity sidecar — once
175
+ * per driver instance, and only for a load that carried records (an empty
176
+ * read is not evidence, see below). The inject callback that loads the sidecar re-runs
177
+ * whenever the `evolutionIo` dependency is replaced (cordis derived-fiber
178
+ * reload — plugin restart / HMR) while THIS driver survives at the apply
179
+ * scope, so the dedupe guard must live here, not in the callback: without
180
+ * it, every io reload doubled the leaderboard entries.
181
+ * @param items - activity records in sidecar order (oldest first).
182
+ */
183
+ backfill(items) {
184
+ if (this.backfilled) return;
185
+ if (items.length === 0) return;
186
+ this.backfilled = true;
187
+ const fresh = items.filter((item) => !this.preBackfillIds.has(item.planId));
188
+ this.preBackfillIds.clear();
189
+ const freshPlans = fresh.map((item) => this.toPlan(item));
190
+ this.plans.unshift(...freshPlans);
191
+ if (this.plans.length > this.maxPlans) this.plans.splice(0, this.plans.length - this.maxPlans);
192
+ }
193
+ /**
194
+ * F-11: test-support API — no production consumer reads the raw
195
+ * plan list (the leaderboard path goes through `compare()`); tests use this
196
+ * as a read/inspection window. Kept by declaration (same posture as the
197
+ * skill-usage `invalidate()` V6-44 declaration), so it is documented intent
198
+ * rather than undeclared dead code.
199
+ * @internal Exported for this package's own tests only.
200
+ */
201
+ plansSnapshot() {
202
+ return [...this.plans];
203
+ }
204
+ /**
205
+ * FLOW6-6 (v43): mark the backfill source unreadable. Set by `apply()` when
206
+ * the activity sidecar carries bytes this build cannot read; the qualification
207
+ * then travels with every comparison — until a later read says otherwise
208
+ * (see {@link EvolutionReplayDriver.markSourceReadable}).
209
+ */
210
+ markSourceUnreadable() {
211
+ this.sourceCorrupt = true;
212
+ this.sourceReadFailure = null;
213
+ }
214
+ /**
215
+ * PLAN S5.1 (2026-09-16, audit P2-18): the counterpart clear — `apply()` calls
216
+ * this on every successful read whose bytes ARE the current format
217
+ * (`loadActivityState` answered `corrupt: false`), so the
218
+ * {@link ReplayResult.sourceCorrupt} qualification follows the CURRENT read
219
+ * state. Before this the flag latched for the driver lifetime: a repaired
220
+ * sidecar plus an io reload (HMR / plugin restart) backfilled the full
221
+ * history while `compare()` kept asserting "NOT the recorded history" — a
222
+ * permanent report claim contrary to fact. The corruption verdict is
223
+ * per-read; the past corruption itself stays observable through the warn
224
+ * `apply()` emits at mark time.
225
+ */
226
+ markSourceReadable() {
227
+ this.sourceCorrupt = false;
228
+ this.sourceReadFailure = null;
229
+ }
230
+ /**
231
+ * 0.18.1 (S3): the backfill read THREW (io error, or a state the reader could
232
+ * not produce at all). Neither verdict applies — the bytes were never judged.
233
+ * Before this the throw skipped both markers and `compare()` returned an
234
+ * unqualified leaderboard, presenting a failed read as an answered one.
235
+ * @param reason - the failure's message, as thrown.
236
+ */
237
+ markSourceReadFailed(reason) {
238
+ this.sourceReadFailure = reason;
239
+ }
240
+ compare(weights = this.weights) {
241
+ const result = comparePlans([...this.plans], clampReplayWeights(weights, this.weights));
242
+ const failure = this.sourceReadFailure === null ? "" : `The activity sidecar read FAILED (${this.sourceReadFailure}) — this leaderboard carries no history from the sidecar, and a failed read is NOT "nothing was recorded".\n`;
243
+ if (!this.sourceCorrupt && this.sourceReadFailure === null) return {
244
+ ...result,
245
+ sourceCorrupt: false
246
+ };
247
+ return {
248
+ ...result,
249
+ sourceCorrupt: this.sourceCorrupt,
250
+ ...this.sourceReadFailure === null ? {} : { sourceReadFailure: this.sourceReadFailure },
251
+ report: failure + (this.sourceCorrupt ? "The activity sidecar could not be read as an activity envelope (unparsable bytes, or no items array) — this leaderboard is NOT the recorded history, and an empty list does not mean nothing happened.\n" : "") + result.report
252
+ };
253
+ }
254
+ };
255
+ const name = "evolution-replay";
256
+ function apply(ctx, rawConfig = {}) {
257
+ const driver = new EvolutionReplayDriver(rawConfig, (message) => {
258
+ ctx.logger.warn(message);
259
+ });
260
+ ctx.provide("evolutionReplay", driver);
261
+ ctx.on("evolution/plan-applied", (event) => {
262
+ driver.record(event);
263
+ });
264
+ ctx.inject(["evolutionIo"], (ioCtx) => {
265
+ const ioRegistry = ioCtx.evolutionIo;
266
+ const io = evolutionIoAdapter(() => ioRegistry.provider());
267
+ loadActivityState(evolutionHome(), io).then((loaded) => {
268
+ if (loaded.corrupt) {
269
+ ioCtx.logger.warn("evolution-replay: the activity sidecar could not be read as an activity envelope (unparsable bytes, or no items array) — there is NO history to backfill; the writer quarantines those bytes on its next append");
270
+ driver.markSourceUnreadable();
271
+ } else {
272
+ if (loaded.foreignVersion) ioCtx.logger.warn("evolution-replay: the activity sidecar was written by a NEWER activity format than this build reads — its records were read as-is and unknown fields ignored, so the leaderboard is complete for the fields this build knows; the writer quarantines those bytes on its next append");
273
+ driver.markSourceReadable();
274
+ }
275
+ driver.backfill(loaded.records);
276
+ }).then(void 0, (error) => {
277
+ const reason = error instanceof Error ? error.message : String(error);
278
+ driver.markSourceReadFailed(reason);
279
+ ioCtx.logger.warn(`evolution-replay: activity sidecar backfill skipped (${reason}) — this leaderboard carries no history from the sidecar, and a failed read is not "nothing was recorded"`);
280
+ }).catch((error) => {
281
+ ioCtx.logger.warn(`evolution-replay: activity sidecar backfill failed after a successful read (${error instanceof Error ? error.message : String(error)}) — the source verdict is unaffected`);
282
+ });
283
+ });
284
+ }
285
+ //#endregion
286
+ export { Config, DEFAULT_WEIGHTS, EvolutionReplayDriver, apply, clampReplayWeights, comparePlans, name };
@@ -0,0 +1,70 @@
1
+ import z from "@deepseek-ai/schemastery";
2
+ import { DEFAULT_THREAT_MAX_SCAN_CHARS, EVOLUTION_WRITE_TOOLS, PATTERN_OVERLAP, asRecord, clampedNumber, scanContentThreats, scanMemoryThreats } from "@lmzhen/dsh-evolution-core";
3
+ import { toolsPort } from "@lmzhen/dsh-evolution-core/platform";
4
+ //#region lib/types/threat/index.js
5
+ /**
6
+ * Write-time threat guard for evolution tools.
7
+ * @module @lmzhen/dsh-evolution-threat
8
+ */
9
+ const name = "evolution-threat";
10
+ const Config = z.object({
11
+ enabled: z.boolean().default(true),
12
+ maxScanChars: z.number().min(PATTERN_OVERLAP + 1).default(DEFAULT_THREAT_MAX_SCAN_CHARS),
13
+ threatExemptLabels: z.array(z.string()).default([])
14
+ });
15
+ /** Scan one tool invocation for threat-shaped payload text. Exported so the
16
+ * guard contract is testable directly (0.3.17). `options.excludeLabels` carries
17
+ * the deployment's benign-label allowlist so this channel agrees with the
18
+ * SkillLibrary/MemoryStore write gates (P2-4, v14). */
19
+ function scanToolArgs(toolName, args, maxScanChars, options = {}) {
20
+ if (!EVOLUTION_WRITE_TOOLS.includes(toolName)) return null;
21
+ const record = asRecord(args);
22
+ if (record === void 0) return null;
23
+ if (toolName === "memory") {
24
+ for (const text of [record.facts, record.content]) if (typeof text === "string") {
25
+ const hit = scanMemoryThreats(text, maxScanChars, options);
26
+ if (hit) return hit;
27
+ }
28
+ if (Array.isArray(record.operations)) for (const op of record.operations) {
29
+ const inner = asRecord(op);
30
+ if (inner === void 0) continue;
31
+ for (const text of [inner.facts, inner.content]) if (typeof text === "string") {
32
+ const hit = scanMemoryThreats(text, maxScanChars, options);
33
+ if (hit) return hit;
34
+ }
35
+ }
36
+ return null;
37
+ }
38
+ for (const text of [
39
+ record.content,
40
+ record.file_content,
41
+ record.new_string
42
+ ]) if (typeof text === "string") {
43
+ const hit = scanContentThreats(text, maxScanChars, options);
44
+ if (hit) return hit;
45
+ }
46
+ return null;
47
+ }
48
+ /** Resolve the effective `maxScanChars`, clamping invalid values to the
49
+ * default (G3.1: 0/negative/NaN/±Infinity → DEFAULT_THREAT_MAX_SCAN_CHARS; V6-05: a value below
50
+ * PATTERN_OVERLAP + 1 is out of the coverage-guarantee domain → default).
51
+ * Exported so the clamp is directly testable; `apply` warns when a
52
+ * user-supplied value was corrected. */
53
+ function resolveMaxScanChars(config) {
54
+ return clampedNumber(config.maxScanChars ?? DEFAULT_THREAT_MAX_SCAN_CHARS, DEFAULT_THREAT_MAX_SCAN_CHARS, { min: PATTERN_OVERLAP + 1 });
55
+ }
56
+ function apply(ctx, rawConfig = {}) {
57
+ if (!(rawConfig.enabled ?? true)) return;
58
+ const maxScanChars = resolveMaxScanChars(rawConfig);
59
+ if (maxScanChars !== (rawConfig.maxScanChars ?? DEFAULT_THREAT_MAX_SCAN_CHARS)) ctx.logger.warn(`evolution-threat: maxScanChars=${String(rawConfig.maxScanChars)} is invalid; falling back to the default ${DEFAULT_THREAT_MAX_SCAN_CHARS}`);
60
+ const scanOptions = { excludeLabels: rawConfig.threatExemptLabels ?? [] };
61
+ ctx.inject(["tools"], (toolCtx) => {
62
+ const tools = toolsPort(toolCtx);
63
+ if (tools === void 0) return;
64
+ toolCtx.effect(() => tools.guard((exec) => {
65
+ return scanToolArgs(exec.name, exec.arguments, maxScanChars, scanOptions) ?? void 0;
66
+ }), "evolution-threat.tools-guard");
67
+ });
68
+ }
69
+ //#endregion
70
+ export { Config, apply, name, resolveMaxScanChars, scanToolArgs };
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Feedback-to-quality scoring for self-evolution.
3
+ *
4
+ * Feedback is durable through `ctx.evolutionIo` (when mounted) and skill
5
+ * feedback feeds the FEEDBACK-OWNED `feedback_score` / `feedback_warn` pair on
6
+ * the usage record. P1-1 (v15): this package used to write
7
+ * `quality_score`/`quality_warn` — but the curator's six-factor `scoreTree`
8
+ * overwrote those fields on every run BEFORE the lifecycle engine read them,
9
+ * so the advertised "curator decisions consume feedback deterministically"
10
+ * channel was dead. The lifecycle engine and the scope view now read the
11
+ * union `quality_warn || feedback_warn`, and the curator never writes the
12
+ * feedback pair (field-ownership contract on `UsageRecord` in
13
+ * evolution-core/usage.ts).
14
+ *
15
+ * Persistence (rc.68): the EVENTS LOG (`evolution/events.json`, via
16
+ * `evolution-core/evolution-events.ts`) is the single source of truth —
17
+ * every increment appends one event under the write lock. `feedback.json` is
18
+ * a rebuildable BOOT CACHE (`{ version: 2, lastSeq, skills, sessions }`),
19
+ * never the truth; the in-memory state is the optimistic aggregate.
20
+ * @module @lmzhen/dsh-evolution-feedback
21
+ */
22
+ import type { Context as CordisContext } from '@deepseek-ai/cordis';
23
+ import type { Context as HostContext } from '@deepseek-ai/cordis/src/context.ts';
24
+ type Context = CordisContext & HostContext;
25
+ import z from '@deepseek-ai/schemastery';
26
+ import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
27
+ declare module '@deepseek-ai/cordis' {
28
+ interface Context {
29
+ evolutionFeedback: EvolutionFeedback;
30
+ }
31
+ }
32
+ export interface FeedbackRecord {
33
+ positive: number;
34
+ negative: number;
35
+ lastNote?: string | undefined;
36
+ }
37
+ export interface FeedbackState {
38
+ skills: Record<string, FeedbackRecord>;
39
+ sessions: Record<string, FeedbackRecord>;
40
+ }
41
+ type IoLike = EvolutionIoLike;
42
+ export declare class EvolutionFeedback {
43
+ private state;
44
+ private chain;
45
+ private readonly path?;
46
+ private readonly eventsPath?;
47
+ private io;
48
+ private warn;
49
+ /** V4-41 (F-324): the last note per target CONFIRMED on the event log. The
50
+ * in-memory `lastNote` is optimistic; a failed append must roll back to this,
51
+ * never to the in-memory `previousNote` (an earlier failed call can leave an
52
+ * unpersisted note there, and reverting to it resurrects a value the log
53
+ * never held). Seeded from the fold truth, updated on successful appends. */
54
+ private readonly durableNote;
55
+ /** PLAN S1.4 (2026-09-16): targets with a feedback append still IN FLIGHT,
56
+ * split by table, as a COUNT per target. record() increments before queueing
57
+ * the append and the append task decrements when it settles (landed or rolled
58
+ * back, finally), dropping the entry only at ZERO — the count covers exactly
59
+ * the optimistic window rc.66 meant to protect, including two appends for the
60
+ * same target in flight at once (review C-P2-1: a per-target boolean marker
61
+ * was cleared by the first settle, so a merge between the two appends folded
62
+ * the second append's increment away). restore() lets memory win ONLY for these targets — a settled
63
+ * target folds from the log truth, so another process's feedback for the
64
+ * same target (audit P1-3) is never overwritten by this process's stale
65
+ * record. */
66
+ private readonly pendingAppends;
67
+ /** P2-32 (v11): process-level bound — every feedbacked session would
68
+ * otherwise keep one entry for the whole process lifetime (a name + note
69
+ * string per session); cap this map and drop the earliest-INSERTED entry on
70
+ * overflow (Map iteration order is insertion order, and re-setting an
71
+ * existing key does not refresh its position, so the eviction is FIFO rather
72
+ * than least-recently-used). `warnedMessages` carries the same bound through
73
+ * `WARNED_CAP` below. */
74
+ private static readonly NOTE_CAP;
75
+ /** V5-32 (0.3.31): fire-and-forget append failures are warn-once per unique
76
+ * message — a persistent refusal (e.g. a future-version log) must not spam
77
+ * the log on every user feedback entry (family posture: process-level once).
78
+ * Bounded like `durableNote`, with the same FIFO eviction. */
79
+ private readonly warnedMessages;
80
+ private readonly WARNED_CAP;
81
+ /** V5-29 (0.3.31): invoked after a FAILED append rolled back, so a caller
82
+ * holding derived state (skillUsage quality score) can re-push it instead of
83
+ * keeping an optimistic value that never landed. */
84
+ onRollback?: (target: string, kind: 'skill' | 'session') => void;
85
+ private readonly fence;
86
+ constructor(io?: IoLike, home?: string, pathOverride?: string, warn?: (message: string) => void, fence?: {
87
+ run<T>(body: () => Promise<T>): Promise<T>;
88
+ });
89
+ /** Bind the evolution IO backend after construction (S6.4 deferred binding). */
90
+ attachIo(io: IoLike): void;
91
+ /** PLAN S4.6 (2026-09-16): whether a durable backend is attached — the
92
+ * plugin's quality push (`apply`) consults this before writing the
93
+ * feedback pair into the skill-usage sidecar. Same no-io posture as
94
+ * `record`/`refold`: without `ctx.evolutionIo` (when mounted) nothing may
95
+ * turn the optimistic in-memory aggregate into a durable side effect. */
96
+ get durable(): boolean;
97
+ /** V5-32 posture applied to the read side (C-events-dispatch-1, v43): an
98
+ * event a repeated read keeps reporting must not warn on each read —
99
+ * `refold()` calls `restore()` before every quality push. Shares the bounded
100
+ * `warnedMessages` set (and its FIFO eviction) with the append-failure warn.
101
+ * @param message - the warn text; identical text warns once per process.
102
+ */
103
+ private warnOnce;
104
+ /** Durable-note map key (V4-41): a target shares one record per mode. */
105
+ private noteKey;
106
+ private mutate;
107
+ restore(io: IoLike): Promise<void>;
108
+ /** External-producer contract (审计 B-4, v18): nothing inside the family
109
+ * calls `record` — the upstream `/feedback` command only appends a
110
+ * `feedback/record` session event carrying free text, which cannot be mapped
111
+ * to a (target, rating) pair without inventing semantics. A host that wants
112
+ * feedback-driven curation wires its own command/event to this method; the
113
+ * curator's union read (`feedback_warn`) then shortens the stale window.
114
+ * `feedback.spec.ts` pins that channel end to end.
115
+ * @param target - skill name or session id the rating belongs to.
116
+ * @param rating - `positive` or `negative`; other values are refused.
117
+ * @param note - optional free-text note carried into the durable event.
118
+ * @param kind - `skill` (default `session`) selects the score table.
119
+ */
120
+ /**
121
+ * v30 FB-01: refold the shared event log into the in-process aggregate.
122
+ * The aggregate only folds at mount, so a long-lived process computed the
123
+ * ABSOLUTE feedback pair from a stale aggregate and overwrote the decision
124
+ * relevant `feedback_warn` another process had recorded. The log is the
125
+ * truth — re-reading it before each quality push shrinks the staleness
126
+ * window to the refold-vs-append race (near-zero, serialized by mutate).
127
+ */
128
+ refold(): Promise<void>;
129
+ record(target: string, rating: 'positive' | 'negative', note?: string, kind?: 'skill' | 'session'): void;
130
+ score(target: string, kind?: 'skill' | 'session'): number;
131
+ /**
132
+ * Deep-copy view of the live aggregate.
133
+ *
134
+ * OPT-26 (2026-09): `@internal` — test-support API, NO production consumer
135
+ * in the family (mirrors the explicit posture of evolution-replay's
136
+ * `plansSnapshot()`). External consumers should read the rendered
137
+ * score/warn surfaces instead of relying on this shape.
138
+ */
139
+ snapshot(): FeedbackState;
140
+ /** Await the pending record-task chain (unload safety; rc.66). */
141
+ waitIdle(): Promise<unknown>;
142
+ /** Snapshot the boot cache from the log truth (rc.68/rc.72); best-effort. */
143
+ private writeCacheNow;
144
+ /** Rebuild the boot cache from the log truth (rc.68); best-effort, queued
145
+ * on the record chain so it runs after the pending appends. */
146
+ persistCache(): Promise<void>;
147
+ }
148
+ /**
149
+ * Merge a legacy aggregate into the event log (rc.69): the expected synthetic
150
+ * sequence is APPENDED (seq-shifted) when the log does not already contain it
151
+ * — so a concurrent first writer's events AND the legacy history both
152
+ * survive; when the sequence is already present the migration was completed
153
+ * (by a first writer or by this path) and nothing is re-appended. Idempotent
154
+ * and race-safe (the search runs inside the same transact). Exported for the
155
+ * migration-race regression test.
156
+ */
157
+ export declare function migrateFeedbackEvents(io: IoLike, eventsPath: string, aggregate: FeedbackState, warn?: (message: string) => void, fence?: {
158
+ run<T>(body: () => Promise<T>): Promise<T>;
159
+ }): Promise<void>;
160
+ export declare const name = "evolution-feedback";
161
+ export interface Config {
162
+ /** Score below which the FEEDBACK pair flips to warned (P1-1, v15: written
163
+ * to `feedback_score`/`feedback_warn`; the lifecycle engine reads the union
164
+ * with the curator-owned `quality_warn`). */
165
+ qualityWarnThreshold?: number;
166
+ /** Explicit boot-cache file path; empty derives $DSH_HOME/evolution/feedback.json.
167
+ * The event log always stays at $DSH_HOME/evolution/events.json (derived from
168
+ * home, never from this override). */
169
+ path?: string;
170
+ }
171
+ export declare const Config: z<Config>;
172
+ /** Resolve the effective quality warn threshold, clamped to its [-1, 1] domain
173
+ * (G3.1). 0 and negative values are legal (a lower threshold is stricter); NaN,
174
+ * ±Infinity and out-of-range values fall back to the default -0.25. Exported so
175
+ * the clamp is directly testable; `apply` warns when a value was corrected. */
176
+ export declare function resolveQualityWarnThreshold(config: Config): number;
177
+ export declare function apply(ctx: Context, rawConfig?: Config): void;
178
+ export {};
179
+ //# sourceMappingURL=index.d.ts.map