@lmzhen/dsh-evolution-activity 0.44.0 → 0.45.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,182 @@
1
+ /**
2
+ * Replay/A-B evaluation for evolution plans.
3
+ *
4
+ * The pure scoring functions remain deterministic and runtime-free. The DSH
5
+ * driver records every `evolution/plan-applied` process event (payload v2,
6
+ * with sessionId) into an in-memory leaderboard and exposes `/evolution
7
+ * replay` (via the `/evolution` command family) for comparison, so a human can
8
+ * A/B review policy/prompt changes against real plan outcomes.
9
+ *
10
+ * V24-13 (v24): the in-memory leaderboard is BACKFILLED at mount from the
11
+ * `evolution-activity` sidecar (`$DSH_HOME/evolution/activity.json`) — the
12
+ * header previously claimed "durability across restarts is the
13
+ * evolution-activity store's job" while nothing ever read the sidecar, so a
14
+ * restart emptied `/evolution replay` and the persisted history sat unread.
15
+ * Records are fed in sidecar order (oldest first); the driver's `maxPlans`
16
+ * window keeps the newest. Best-effort: a missing/unreadable sidecar starts
17
+ * the leaderboard empty, exactly as before.
18
+ * @module @lmzhen/dsh-evolution-replay
19
+ */
20
+ import type { Context } from '@deepseek-ai/cordis';
21
+ import z from '@deepseek-ai/schemastery';
22
+ import type { EvolutionPlanAppliedEvent } from '@lmzhen/dsh-evolution-core';
23
+ export interface ReplayPlan {
24
+ policyId: string;
25
+ acceptedOps: number;
26
+ rejectedOps: number;
27
+ memoryOps: number;
28
+ skillOps: number;
29
+ evidenceQuotes: number;
30
+ estimatedInputChars: number;
31
+ /** R-03: ops skipped because the session never read the named skill — a plan
32
+ * whose ops were all skipped must not read as a clean "0/0" either. */
33
+ skippedUnread?: number | undefined;
34
+ /** V6-10 (0.3.36): execution-layer failures — a plan must not read as a
35
+ * clean "0/0" when its ops all failed at execution (V5-19 payload). */
36
+ executionFailures?: number | undefined;
37
+ executionError?: string | undefined;
38
+ }
39
+ export interface ReplayResult {
40
+ winner: string | null;
41
+ /** v28 G4.4 (RPL-01): `null` when fewer than two plans were recorded — a
42
+ * single plan has no runner-up, and reporting its FULL score as a "margin"
43
+ * read as "won by N points" over nothing. Consumers must null-check. */
44
+ margin: number | null;
45
+ plans: ReplayPlan[];
46
+ report: string;
47
+ /** FLOW6-6 (v43): the activity sidecar could not be read as the current
48
+ * format at the most recent backfill read — `plans` is then NOT the
49
+ * recorded history, and the report says so. PLAN S5.1 (2026-09-16): the
50
+ * flag tracks the CURRENT read state, so a later clean read (the sidecar
51
+ * was repaired and an io reload re-read it) clears the qualification —
52
+ * it never outlives the condition it describes. */
53
+ sourceCorrupt?: boolean | undefined;
54
+ /** 0.18.1 (S3): the most recent backfill READ threw (io error, or a state the
55
+ * reader could not produce at all) — no verdict was reached, which is a
56
+ * different fact from `sourceCorrupt` (the bytes WERE read and are not an
57
+ * activity envelope). Carries the failure's message; a later ANSWERED read
58
+ * clears it (see {@link EvolutionReplayDriver.markSourceReadFailed}). */
59
+ sourceReadFailure?: string | undefined;
60
+ }
61
+ export interface ReplayWeights {
62
+ accepted: number;
63
+ rejectedPenalty: number;
64
+ evidence: number;
65
+ cost: number;
66
+ }
67
+ export declare const DEFAULT_WEIGHTS: ReplayWeights;
68
+ export interface Config {
69
+ maxPlans?: number;
70
+ weights?: ReplayWeights;
71
+ }
72
+ export declare const Config: z<Config>;
73
+ /**
74
+ * Clamp a weights object to its per-field domain (G3.1). `accepted`,
75
+ * `rejectedPenalty` and `evidence` are positive multipliers (min 1 — a zero or
76
+ * negative weight would silently drop a scoring term or reverse its sign);
77
+ * `cost` may be 0 (0 means "no cost penalty"), so its min is 0. NaN, ±Infinity
78
+ * and out-of-range values fall back to the default for that field.
79
+ */
80
+ export declare function clampReplayWeights(weights: ReplayWeights | undefined, fallback?: ReplayWeights): ReplayWeights;
81
+ export declare function comparePlans(plans: ReplayPlan[], weights?: ReplayWeights): ReplayResult;
82
+ declare module '@deepseek-ai/cordis' {
83
+ interface Context {
84
+ evolutionReplay: EvolutionReplayDriver;
85
+ }
86
+ }
87
+ export declare class EvolutionReplayDriver {
88
+ private readonly plans;
89
+ private readonly maxPlans;
90
+ /** V25-01 (v25): backfill-once latch — see {@link EvolutionReplayDriver.backfill}. */
91
+ private backfilled;
92
+ /** FLOW6-6 (v43): the backfill source was unreadable (newer format or corrupt
93
+ * bytes) — carried into every comparison so an empty leaderboard is never
94
+ * presented as "nothing was recorded". PLAN S5.1 (2026-09-16): this holds the
95
+ * most recent READ's verdict, not the first one — {@link EvolutionReplayDriver.markSourceReadable}
96
+ * clears it on a later clean read, so the qualification reflects the present
97
+ * instead of latching for the driver lifetime. */
98
+ private sourceCorrupt;
99
+ /** 0.18.1 (S3): the backfill READ itself failed — held as its message. A
100
+ * thrown read used to skip both markers, so `sourceCorrupt` kept whatever
101
+ * the previous read said and a failed read presented as a clean one. Cleared
102
+ * by any ANSWERED read; never sets `sourceCorrupt` (a failed read is not
103
+ * evidence that the bytes are corrupt). */
104
+ private sourceReadFailure;
105
+ /** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
106
+ * plan-applied landing inside the one-shot `loadActivityState` read window is
107
+ * recorded live AND persisted into the sidecar the backfill is reading —
108
+ * `backfill()` drops those ids so the event is not counted twice.
109
+ *
110
+ * V27 INS-05: the set is BOUNDED. `backfill()` is the only place that cleared
111
+ * it, so a sidecar load that never succeeded (the inject callback's catch
112
+ * warns and does not retry until the io dependency is replaced) let every
113
+ * live plan id accumulate for the process lifetime. Past
114
+ * PRE_BACKFILL_ID_CAP the oldest ids are dropped: the dedupe window is then
115
+ * finite, and a dropped duplicate can at worst repeat an entry inside the
116
+ * `maxPlans` window instead of growing memory without bound. */
117
+ private readonly preBackfillIds;
118
+ /** Upper bound on {@link EvolutionReplayDriver.preBackfillIds} (V27 INS-05). */
119
+ private static readonly PRE_BACKFILL_ID_CAP;
120
+ private readonly weights;
121
+ constructor(config?: Config, warn?: (message: string) => void);
122
+ record(plan: EvolutionPlanAppliedEvent): void;
123
+ /**
124
+ * v29 RPL-02: the activity/event record → scored-plan mapping, extracted
125
+ * from `record` so `backfill` can place sidecar plans at the CHRONOLOGICAL
126
+ * head of the window instead of appending them after this boot's live plans
127
+ * (the old order made the FIFO evict the freshest live plan first).
128
+ */
129
+ private toPlan;
130
+ /**
131
+ * V25-01 (v25): backfill the leaderboard from the activity sidecar — once
132
+ * per driver instance, and only for a load that carried records (an empty
133
+ * read is not evidence, see below). The inject callback that loads the sidecar re-runs
134
+ * whenever the `evolutionIo` dependency is replaced (cordis derived-fiber
135
+ * reload — plugin restart / HMR) while THIS driver survives at the apply
136
+ * scope, so the dedupe guard must live here, not in the callback: without
137
+ * it, every io reload doubled the leaderboard entries.
138
+ * @param items - activity records in sidecar order (oldest first).
139
+ */
140
+ backfill(items: ReadonlyArray<import('@lmzhen/dsh-evolution-activity').EvolutionActivityRecord>): void;
141
+ /**
142
+ * F-11: test-support API — no production consumer reads the raw
143
+ * plan list (the leaderboard path goes through `compare()`); tests use this
144
+ * as a read/inspection window. Kept by declaration (same posture as the
145
+ * skill-usage `invalidate()` V6-44 declaration), so it is documented intent
146
+ * rather than undeclared dead code.
147
+ * @internal Exported for this package's own tests only.
148
+ */
149
+ plansSnapshot(): ReplayPlan[];
150
+ /**
151
+ * FLOW6-6 (v43): mark the backfill source unreadable. Set by `apply()` when
152
+ * the activity sidecar carries bytes this build cannot read; the qualification
153
+ * then travels with every comparison — until a later read says otherwise
154
+ * (see {@link EvolutionReplayDriver.markSourceReadable}).
155
+ */
156
+ markSourceUnreadable(): void;
157
+ /**
158
+ * PLAN S5.1 (2026-09-16, audit P2-18): the counterpart clear — `apply()` calls
159
+ * this on every successful read whose bytes ARE the current format
160
+ * (`loadActivityState` answered `corrupt: false`), so the
161
+ * {@link ReplayResult.sourceCorrupt} qualification follows the CURRENT read
162
+ * state. Before this the flag latched for the driver lifetime: a repaired
163
+ * sidecar plus an io reload (HMR / plugin restart) backfilled the full
164
+ * history while `compare()` kept asserting "NOT the recorded history" — a
165
+ * permanent report claim contrary to fact. The corruption verdict is
166
+ * per-read; the past corruption itself stays observable through the warn
167
+ * `apply()` emits at mark time.
168
+ */
169
+ markSourceReadable(): void;
170
+ /**
171
+ * 0.18.1 (S3): the backfill read THREW (io error, or a state the reader could
172
+ * not produce at all). Neither verdict applies — the bytes were never judged.
173
+ * Before this the throw skipped both markers and `compare()` returned an
174
+ * unqualified leaderboard, presenting a failed read as an answered one.
175
+ * @param reason - the failure's message, as thrown.
176
+ */
177
+ markSourceReadFailed(reason: string): void;
178
+ compare(weights?: ReplayWeights): ReplayResult;
179
+ }
180
+ export declare const name = "evolution-replay";
181
+ export declare function apply(ctx: Context, rawConfig?: Config): void;
182
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,404 @@
1
+ /**
2
+ * Replay/A-B evaluation for evolution plans.
3
+ *
4
+ * The pure scoring functions remain deterministic and runtime-free. The DSH
5
+ * driver records every `evolution/plan-applied` process event (payload v2,
6
+ * with sessionId) into an in-memory leaderboard and exposes `/evolution
7
+ * replay` (via the `/evolution` command family) for comparison, so a human can
8
+ * A/B review policy/prompt changes against real plan outcomes.
9
+ *
10
+ * V24-13 (v24): the in-memory leaderboard is BACKFILLED at mount from the
11
+ * `evolution-activity` sidecar (`$DSH_HOME/evolution/activity.json`) — the
12
+ * header previously claimed "durability across restarts is the
13
+ * evolution-activity store's job" while nothing ever read the sidecar, so a
14
+ * restart emptied `/evolution replay` and the persisted history sat unread.
15
+ * Records are fed in sidecar order (oldest first); the driver's `maxPlans`
16
+ * window keeps the newest. Best-effort: a missing/unreadable sidecar starts
17
+ * the leaderboard empty, exactly as before.
18
+ * @module @lmzhen/dsh-evolution-replay
19
+ */
20
+ import z from '@deepseek-ai/schemastery';
21
+ import { clampedNumber, evolutionHome, evolutionIoAdapter } from '@lmzhen/dsh-evolution-core';
22
+ import { loadActivityState } from "../index.js";
23
+ export const DEFAULT_WEIGHTS = {
24
+ accepted: 10,
25
+ rejectedPenalty: 15,
26
+ evidence: 2,
27
+ cost: 0.001,
28
+ };
29
+ /** The four clampable weight fields, in report order (V4-40 warn). */
30
+ const WEIGHT_FIELDS = ['accepted', 'rejectedPenalty', 'evidence', 'cost'];
31
+ export const Config = z.object({
32
+ maxPlans: z.number().min(1).default(50),
33
+ weights: z.object({
34
+ accepted: z.number().min(1).default(10),
35
+ rejectedPenalty: z.number().min(1).default(15),
36
+ evidence: z.number().min(1).default(2),
37
+ cost: z.number().min(0).default(0.001),
38
+ }).default(DEFAULT_WEIGHTS),
39
+ });
40
+ /**
41
+ * Clamp a weights object to its per-field domain (G3.1). `accepted`,
42
+ * `rejectedPenalty` and `evidence` are positive multipliers (min 1 — a zero or
43
+ * negative weight would silently drop a scoring term or reverse its sign);
44
+ * `cost` may be 0 (0 means "no cost penalty"), so its min is 0. NaN, ±Infinity
45
+ * and out-of-range values fall back to the default for that field.
46
+ */
47
+ export function clampReplayWeights(weights, fallback = DEFAULT_WEIGHTS) {
48
+ return {
49
+ accepted: clampedNumber(weights?.accepted, fallback.accepted, { min: 1 }),
50
+ rejectedPenalty: clampedNumber(weights?.rejectedPenalty, fallback.rejectedPenalty, { min: 1 }),
51
+ evidence: clampedNumber(weights?.evidence, fallback.evidence, { min: 1 }),
52
+ cost: clampedNumber(weights?.cost, fallback.cost, { min: 0 }),
53
+ };
54
+ }
55
+ function scorePlan(plan, weights = DEFAULT_WEIGHTS) {
56
+ return plan.acceptedOps * weights.accepted
57
+ - plan.rejectedOps * weights.rejectedPenalty
58
+ + plan.evidenceQuotes * weights.evidence
59
+ - plan.estimatedInputChars * weights.cost;
60
+ }
61
+ export function comparePlans(plans, weights = DEFAULT_WEIGHTS) {
62
+ if (plans.length === 0)
63
+ return { winner: null, margin: null, plans, report: '没有可比较的计划。' };
64
+ const scored = plans.map(plan => ({ plan, score: scorePlan(plan, weights) })).sort((a, b) => b.score - a.score);
65
+ const winner = scored[0];
66
+ if (!winner)
67
+ return { winner: null, margin: null, plans, report: '没有可比较的计划。' };
68
+ const runnerUp = scored[1];
69
+ // v28 G4.4 (RPL-01): one plan recorded → no comparison happened; the old
70
+ // `margin = winner.score` published the absolute score in a field whose
71
+ // only other meaning is a DIFFERENCE. Null it and say so in the report.
72
+ const margin = runnerUp ? winner.score - runnerUp.score : null;
73
+ const singleNote = runnerUp ? '' : '\n(single plan recorded — margin is not a comparison)';
74
+ return {
75
+ winner: winner.plan.policyId,
76
+ margin,
77
+ plans,
78
+ 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 !== undefined ? `: ${plan.executionError}` : ''}` : ''})`).join('\n') + singleNote,
79
+ };
80
+ }
81
+ export class EvolutionReplayDriver {
82
+ plans = [];
83
+ maxPlans;
84
+ /** V25-01 (v25): backfill-once latch — see {@link EvolutionReplayDriver.backfill}. */
85
+ backfilled = false;
86
+ /** FLOW6-6 (v43): the backfill source was unreadable (newer format or corrupt
87
+ * bytes) — carried into every comparison so an empty leaderboard is never
88
+ * presented as "nothing was recorded". PLAN S5.1 (2026-09-16): this holds the
89
+ * most recent READ's verdict, not the first one — {@link EvolutionReplayDriver.markSourceReadable}
90
+ * clears it on a later clean read, so the qualification reflects the present
91
+ * instead of latching for the driver lifetime. */
92
+ sourceCorrupt = false;
93
+ /** 0.18.1 (S3): the backfill READ itself failed — held as its message. A
94
+ * thrown read used to skip both markers, so `sourceCorrupt` kept whatever
95
+ * the previous read said and a failed read presented as a clean one. Cleared
96
+ * by any ANSWERED read; never sets `sourceCorrupt` (a failed read is not
97
+ * evidence that the bytes are corrupt). */
98
+ sourceReadFailure = null;
99
+ /** V26-05 (v25): plan ids recorded live BEFORE the backfill settled. A
100
+ * plan-applied landing inside the one-shot `loadActivityState` read window is
101
+ * recorded live AND persisted into the sidecar the backfill is reading —
102
+ * `backfill()` drops those ids so the event is not counted twice.
103
+ *
104
+ * V27 INS-05: the set is BOUNDED. `backfill()` is the only place that cleared
105
+ * it, so a sidecar load that never succeeded (the inject callback's catch
106
+ * warns and does not retry until the io dependency is replaced) let every
107
+ * live plan id accumulate for the process lifetime. Past
108
+ * PRE_BACKFILL_ID_CAP the oldest ids are dropped: the dedupe window is then
109
+ * finite, and a dropped duplicate can at worst repeat an entry inside the
110
+ * `maxPlans` window instead of growing memory without bound. */
111
+ preBackfillIds = new Set();
112
+ /** Upper bound on {@link EvolutionReplayDriver.preBackfillIds} (V27 INS-05). */
113
+ static PRE_BACKFILL_ID_CAP = 4096;
114
+ weights;
115
+ constructor(config = {}, warn = () => { }) {
116
+ // G3.1 (0.3.23): clamp maxPlans and weights. A 0/negative/NaN/±Infinity
117
+ // maxPlans would break the size bound; the weights clamp keeps every term
118
+ // in its valid domain. The schema `.min(1)` rejects 0/negative; these
119
+ // clamps also cover NaN/±Infinity (the number schema lets them through).
120
+ const maxPlans = clampedNumber(config.maxPlans ?? 50, 50, { min: 1 });
121
+ this.maxPlans = maxPlans;
122
+ if (config.maxPlans !== undefined && maxPlans !== config.maxPlans) {
123
+ warn(`evolution-replay: maxPlans=${String(config.maxPlans)} is invalid; falling back to the default 50`);
124
+ }
125
+ // V4-40: clamp the weights the same way, but surface a single warn when any
126
+ // field had to be corrected — the maxPlans clamp already warns, and a silent
127
+ // weights clamp would hide a mis-scored A/B comparison. cost's 0 is legal
128
+ // (no cost penalty), so it is only flagged when actually out of range.
129
+ const rawWeights = config.weights;
130
+ this.weights = clampReplayWeights(rawWeights);
131
+ if (rawWeights !== undefined) {
132
+ // Only flag fields the caller EXPLICITLY provided that had to be clamped —
133
+ // an absent field defaults legitimately and must not warn.
134
+ const clampedFields = WEIGHT_FIELDS.filter(field => field in rawWeights && this.weights[field] !== rawWeights[field]);
135
+ if (clampedFields.length > 0) {
136
+ warn(`evolution-replay: weights ${clampedFields.join(', ')} provided an invalid value; falling back to the default`);
137
+ }
138
+ }
139
+ }
140
+ record(plan) {
141
+ // V26-05 (v25): while the one-shot backfill is in flight, live plan ids
142
+ // are tracked so `backfill()` can drop the same events arriving from the
143
+ // sidecar (the activity store persists them concurrently with the read).
144
+ if (!this.backfilled) {
145
+ this.preBackfillIds.add(plan.planId);
146
+ // V27 INS-05: FIFO eviction (Set iteration order is insertion order), so
147
+ // the tracking set cannot grow without bound while a backfill is pending.
148
+ while (this.preBackfillIds.size > EvolutionReplayDriver.PRE_BACKFILL_ID_CAP) {
149
+ const oldest = this.preBackfillIds.keys().next().value;
150
+ if (oldest === undefined)
151
+ break;
152
+ this.preBackfillIds.delete(oldest);
153
+ }
154
+ }
155
+ // P3-23 (v14): the op counters arrive from a persisted session event, so a
156
+ // malformed log entry (missing/NaN/non-number) used to poison `acceptedOps`
157
+ // with NaN and every score derived from it. Same finite-number discipline
158
+ // as the other guarded fields below.
159
+ // P2-2 (v15): the guard now covers ALL SIX numeric fields — the first cut
160
+ // left `evidenceQuotes`/`estimatedInputChars`/`executionFailures` on bare
161
+ // `typeof` checks, and `typeof NaN === 'number'` let them straight into
162
+ // `scorePlan` (evidence is a scored dimension) — the exact poisoning the
163
+ // fix claimed to close. `count` also refuses negatives: a counter cannot
164
+ // be negative and a negative value distorts the ranking.
165
+ this.plans.push(this.toPlan(plan));
166
+ if (this.plans.length > this.maxPlans)
167
+ this.plans.shift();
168
+ }
169
+ /**
170
+ * v29 RPL-02: the activity/event record → scored-plan mapping, extracted
171
+ * from `record` so `backfill` can place sidecar plans at the CHRONOLOGICAL
172
+ * head of the window instead of appending them after this boot's live plans
173
+ * (the old order made the FIFO evict the freshest live plan first).
174
+ */
175
+ toPlan(plan) {
176
+ // P3-23 (v14): the op counters arrive from a persisted session event, so a
177
+ // malformed log entry (missing/NaN/non-number) used to poison `acceptedOps`
178
+ // with NaN and every score derived from it. Same finite-number discipline
179
+ // as the other guarded fields below.
180
+ // P2-2 (v15): the guard now covers ALL SIX numeric fields — the first cut
181
+ // left `evidenceQuotes`/`estimatedInputChars`/`executionFailures` on bare
182
+ // `typeof` checks, and `typeof NaN === 'number'` let them straight into
183
+ // `scorePlan` (evidence is a scored dimension) — the exact poisoning the
184
+ // fix claimed to close. `count` also refuses negatives: a counter cannot
185
+ // be negative and a negative value distorts the ranking.
186
+ const count = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0);
187
+ const countOr = (value, fallback) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback);
188
+ const memoryApplied = count(plan.memoryApplied);
189
+ const skillApplied = count(plan.skillApplied);
190
+ return ({
191
+ // 0.3.17 (E-76): an EMPTY policyFingerprint counts as missing — the
192
+ // leaderboard used to show a nameless "" entry (empty-string checks pass
193
+ // through typeof).
194
+ policyId: typeof plan.policyFingerprint === 'string' && plan.policyFingerprint.length > 0 ? plan.policyFingerprint : plan.planId,
195
+ acceptedOps: memoryApplied + skillApplied,
196
+ rejectedOps: count(plan.rejectedOps),
197
+ memoryOps: memoryApplied,
198
+ skillOps: skillApplied,
199
+ // A missing evidenceQuotes keeps the E-76-era heuristic (≈ applied ops);
200
+ // a malformed one (NaN/∞/negative) is treated the same way instead of
201
+ // poisoning the scored dimension.
202
+ evidenceQuotes: countOr(plan.evidenceQuotes, memoryApplied + skillApplied),
203
+ estimatedInputChars: count(plan.estimatedInputChars),
204
+ // R-03: report-only like executionFailures (E4/P1-10) — the skips are a
205
+ // refusal cause the score does not weigh, but the text must show them.
206
+ skippedUnread: count(plan.skippedUnread),
207
+ // V6-10 (0.3.36): keep the failure dimension for the leaderboard —
208
+ // a plan whose ops all failed must not score as a clean empty plan.
209
+ // E4 (P1-10, v11): the failure dimension is a REPORT-ONLY field (shown
210
+ // in the leaderboard text); scorePlan intentionally weighs only
211
+ // accepted/rejected/evidence/cost — execution failures and validation
212
+ // rejections score differently BY DESIGN (the operational layers differ:
213
+ // rejected ops were prevented, failed ops were attempted). The V6-10
214
+ // comment above was the only place claiming a score equality it does
215
+ // not implement; the score function below is the authority.
216
+ executionFailures: count(plan.executionFailures),
217
+ ...typeof plan.executionError === 'string' ? { executionError: plan.executionError } : {},
218
+ });
219
+ }
220
+ /**
221
+ * V25-01 (v25): backfill the leaderboard from the activity sidecar — once
222
+ * per driver instance, and only for a load that carried records (an empty
223
+ * read is not evidence, see below). The inject callback that loads the sidecar re-runs
224
+ * whenever the `evolutionIo` dependency is replaced (cordis derived-fiber
225
+ * reload — plugin restart / HMR) while THIS driver survives at the apply
226
+ * scope, so the dedupe guard must live here, not in the callback: without
227
+ * it, every io reload doubled the leaderboard entries.
228
+ * @param items - activity records in sidecar order (oldest first).
229
+ */
230
+ backfill(items) {
231
+ if (this.backfilled)
232
+ return;
233
+ // P2-15: an EMPTY list does not prove the sidecar was read — a quarantined
234
+ // activity.json loads as [] too. Latching on it would lock the leaderboard
235
+ // empty for the process lifetime, so the latch commits on the first load
236
+ // that actually carried records; repeating backfill([]) duplicates nothing.
237
+ if (items.length === 0)
238
+ return;
239
+ this.backfilled = true;
240
+ // V26-05 (v25): drop the sidecar copies of plans that were already
241
+ // recorded live inside the read window (same planId — ids are unique per
242
+ // plan), then retire the tracking set.
243
+ const fresh = items.filter(item => !this.preBackfillIds.has(item.planId));
244
+ this.preBackfillIds.clear();
245
+ // v29 RPL-02: sidecar records are OLDER than this boot's live plans
246
+ // (live events recorded between listener registration and this async load
247
+ // landed at the tail first). Inserting them at the CHRONOLOGICAL head —
248
+ // oldest first — keeps the array time-ordered, so the maxPlans FIFO
249
+ // evicts the oldest record instead of the freshest live plan (the old
250
+ // append-after-live order shifted out exactly the plans a human A/B
251
+ // review most wants).
252
+ const freshPlans = fresh.map(item => this.toPlan(item));
253
+ this.plans.unshift(...freshPlans);
254
+ if (this.plans.length > this.maxPlans)
255
+ this.plans.splice(0, this.plans.length - this.maxPlans);
256
+ }
257
+ /**
258
+ * F-11: test-support API — no production consumer reads the raw
259
+ * plan list (the leaderboard path goes through `compare()`); tests use this
260
+ * as a read/inspection window. Kept by declaration (same posture as the
261
+ * skill-usage `invalidate()` V6-44 declaration), so it is documented intent
262
+ * rather than undeclared dead code.
263
+ * @internal Exported for this package's own tests only.
264
+ */
265
+ plansSnapshot() {
266
+ return [...this.plans];
267
+ }
268
+ /**
269
+ * FLOW6-6 (v43): mark the backfill source unreadable. Set by `apply()` when
270
+ * the activity sidecar carries bytes this build cannot read; the qualification
271
+ * then travels with every comparison — until a later read says otherwise
272
+ * (see {@link EvolutionReplayDriver.markSourceReadable}).
273
+ */
274
+ markSourceUnreadable() {
275
+ this.sourceCorrupt = true;
276
+ // 0.18.1 (S3): an ANSWERED read — even a corrupt verdict — retires a
277
+ // previous read FAILURE; only the current read's state may qualify.
278
+ this.sourceReadFailure = null;
279
+ }
280
+ /**
281
+ * PLAN S5.1 (2026-09-16, audit P2-18): the counterpart clear — `apply()` calls
282
+ * this on every successful read whose bytes ARE the current format
283
+ * (`loadActivityState` answered `corrupt: false`), so the
284
+ * {@link ReplayResult.sourceCorrupt} qualification follows the CURRENT read
285
+ * state. Before this the flag latched for the driver lifetime: a repaired
286
+ * sidecar plus an io reload (HMR / plugin restart) backfilled the full
287
+ * history while `compare()` kept asserting "NOT the recorded history" — a
288
+ * permanent report claim contrary to fact. The corruption verdict is
289
+ * per-read; the past corruption itself stays observable through the warn
290
+ * `apply()` emits at mark time.
291
+ */
292
+ markSourceReadable() {
293
+ this.sourceCorrupt = false;
294
+ this.sourceReadFailure = null;
295
+ }
296
+ /**
297
+ * 0.18.1 (S3): the backfill read THREW (io error, or a state the reader could
298
+ * not produce at all). Neither verdict applies — the bytes were never judged.
299
+ * Before this the throw skipped both markers and `compare()` returned an
300
+ * unqualified leaderboard, presenting a failed read as an answered one.
301
+ * @param reason - the failure's message, as thrown.
302
+ */
303
+ markSourceReadFailed(reason) {
304
+ this.sourceReadFailure = reason;
305
+ }
306
+ compare(weights = this.weights) {
307
+ // P3 (v15): sort on a COPY — `comparePlans` sorts its argument in place,
308
+ // and `this.plans` used to be handed over by reference, so a consumer
309
+ // sorting/reordering `result.plans` mutated the driver's live leaderboard
310
+ // (inconsistent with `plansSnapshot()`'s deliberate copy).
311
+ // C-11 (v18): compare() is public; the constructor clamps its config,
312
+ // but a caller-supplied weights object must be clamped here too (NaN/negative
313
+ // weights would produce NaN scores/margins).
314
+ const result = comparePlans([...this.plans], clampReplayWeights(weights, this.weights));
315
+ // 0.18.1 (S3): a read FAILURE carries its own qualification. The two are
316
+ // composed rather than folded together because they are different facts
317
+ // (never judged vs judged corrupt).
318
+ const failure = this.sourceReadFailure === null
319
+ ? ''
320
+ : `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`;
321
+ if (!this.sourceCorrupt && this.sourceReadFailure === null)
322
+ return { ...result, sourceCorrupt: false };
323
+ return {
324
+ ...result,
325
+ sourceCorrupt: this.sourceCorrupt,
326
+ ...this.sourceReadFailure === null ? {} : { sourceReadFailure: this.sourceReadFailure },
327
+ report: failure + (this.sourceCorrupt
328
+ // T4-08/A50: the parenthetical used to say "corrupt bytes or a newer writer" — a newer writer's
329
+ // envelope is READ (its records are the history), so only unreadable bytes reach this sentence.
330
+ ? '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'
331
+ : '') + result.report,
332
+ };
333
+ }
334
+ }
335
+ export const name = 'evolution-replay';
336
+ export function apply(ctx, rawConfig = {}) {
337
+ const driver = new EvolutionReplayDriver(rawConfig, (message) => {
338
+ ctx.logger.warn(message);
339
+ });
340
+ ctx.provide('evolutionReplay', driver);
341
+ ctx.on('evolution/plan-applied', (event) => {
342
+ driver.record(event);
343
+ });
344
+ // V24-13 (v24): backfill the leaderboard from the activity sidecar the
345
+ // evolution-activity package persists on every plan outcome. Deferred
346
+ // binding (same pattern as activity's own persistence listener): subscribe
347
+ // only once the evolution IO provider mounts. Records feed in file order
348
+ // (oldest first) through the same `record()` gate the live path uses, so
349
+ // the maxPlans window keeps the newest and every numeric guard applies.
350
+ // The activity record is payload v2 of `evolution/plan-applied` plus an
351
+ // `at` timestamp — structurally the event the leaderboard consumes.
352
+ ctx.inject(['evolutionIo'], (ioCtx) => {
353
+ const ioRegistry = ioCtx.evolutionIo;
354
+ const io = evolutionIoAdapter(() => ioRegistry.provider());
355
+ const root = evolutionHome();
356
+ void loadActivityState(root, io)
357
+ .then((loaded) => {
358
+ // FLOW6-6 (v43): an unreadable sidecar is not "no history". Say so once
359
+ // and qualify every comparison, instead of showing an empty leaderboard
360
+ // that reads as "nothing was ever recorded".
361
+ if (loaded.corrupt) {
362
+ // T4-08/A50: ONLY this state means the records are missing — the bytes were not an activity
363
+ // envelope at all, so there is nothing to backfill and the comparison is qualified.
364
+ 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');
365
+ driver.markSourceUnreadable();
366
+ }
367
+ else {
368
+ // ...while a NEWER writer's envelope is NOT that: its items were read as-is (the pinned
369
+ // behaviour), so this is the recorded history for every field this build knows. Calling it
370
+ // "NOT the recorded history" while the leaderboard showed its records was the contradiction.
371
+ if (loaded.foreignVersion) {
372
+ 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');
373
+ }
374
+ // PLAN S5.1 (2026-09-16, audit P2-18): a clean read is also a verdict —
375
+ // clear a stale flag so the compare() qualification follows the current
376
+ // read (a repaired sidecar reaching us through an io reload must stop
377
+ // qualifying the report as "NOT the recorded history"). A read that
378
+ // THREW no longer skips both branches silently: the chain's own
379
+ // `.catch` below marks the failure (0.18.1 / S3), so `compare()`
380
+ // qualifies the result instead of presenting it as an answered read.
381
+ driver.markSourceReadable();
382
+ }
383
+ // V25-01 (v25): backfill() is once-per-driver — this callback re-runs
384
+ // on every evolutionIo dependency replacement while the driver
385
+ // survives, so a plain record loop here would double the entries.
386
+ driver.backfill(loaded.records);
387
+ })
388
+ .then(undefined, (error) => {
389
+ // 0.18.1 (S3): a THROWN read is a state, not a silence — the leaderboard
390
+ // must stop presenting as an answered read. Review P2-4: ONLY the read's
391
+ // own rejection reaches this handler (two-argument then), so a failure in
392
+ // the body above can no longer be misattributed as "the read failed".
393
+ const reason = error instanceof Error ? error.message : String(error);
394
+ driver.markSourceReadFailed(reason);
395
+ 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"`);
396
+ })
397
+ .catch((error) => {
398
+ // The read ANSWERED; something in the body failed. The source verdict is
399
+ // unaffected — only the log says so (no fabricated read-failure state).
400
+ 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`);
401
+ });
402
+ });
403
+ }
404
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Write-time threat guard for evolution tools.
3
+ * @module @lmzhen/dsh-evolution-threat
4
+ */
5
+ import type { Context as CordisContext } from '@deepseek-ai/cordis';
6
+ import type { Context as HostContext } from '@deepseek-ai/cordis/src/context.ts';
7
+ type Context = CordisContext & HostContext;
8
+ import z from '@deepseek-ai/schemastery';
9
+ import type { ScanOptions } from '@lmzhen/dsh-evolution-core';
10
+ export declare const name = "evolution-threat";
11
+ export interface Config {
12
+ enabled?: boolean;
13
+ /** Maximum normalized characters scanned per write field. */
14
+ maxScanChars?: number;
15
+ /** Pattern labels the deployment knows to be benign. P2-4 (v14): without
16
+ * this the guard blocked payloads the SkillLibrary/MemoryStore gates already
17
+ * exempted, while its message advertised an exemption that did not exist on
18
+ * this channel. Same `excludeLabels` contract as the store gates. */
19
+ threatExemptLabels?: string[];
20
+ }
21
+ export declare const Config: z<Config>;
22
+ /** Scan one tool invocation for threat-shaped payload text. Exported so the
23
+ * guard contract is testable directly (0.3.17). `options.excludeLabels` carries
24
+ * the deployment's benign-label allowlist so this channel agrees with the
25
+ * SkillLibrary/MemoryStore write gates (P2-4, v14). */
26
+ export declare function scanToolArgs(toolName: string, args: unknown, maxScanChars: number, options?: ScanOptions): string | null;
27
+ /** Resolve the effective `maxScanChars`, clamping invalid values to the
28
+ * default (G3.1: 0/negative/NaN/±Infinity → DEFAULT_THREAT_MAX_SCAN_CHARS; V6-05: a value below
29
+ * PATTERN_OVERLAP + 1 is out of the coverage-guarantee domain → default).
30
+ * Exported so the clamp is directly testable; `apply` warns when a
31
+ * user-supplied value was corrected. */
32
+ export declare function resolveMaxScanChars(config: Config): number;
33
+ export declare function apply(ctx: Context, rawConfig?: Config): void;
34
+ export {};
35
+ //# sourceMappingURL=index.d.ts.map