peaks-loop 4.1.20 → 4.1.21

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 (26) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +89 -0
  3. package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
  4. package/dist/cli/commands/observability-commands-baseline.js +74 -0
  5. package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
  6. package/dist/cli/commands/observability-commands-queries.js +8 -1
  7. package/dist/cli/commands/observability-commands.d.ts +7 -1
  8. package/dist/cli/commands/observability-commands.js +19 -3
  9. package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
  10. package/dist/services/artifacts/repair-cycle-service.js +23 -0
  11. package/dist/services/observability/aggregation-helpers.d.ts +12 -8
  12. package/dist/services/observability/aggregation-helpers.js +12 -25
  13. package/dist/services/observability/aggregation-types.d.ts +40 -0
  14. package/dist/services/observability/aggregation.d.ts +2 -1
  15. package/dist/services/observability/aggregation.js +16 -25
  16. package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
  17. package/dist/services/observability/repair-cycle-metric.js +223 -0
  18. package/dist/services/observability/report-formatter.d.ts +1 -1
  19. package/dist/services/observability/report-formatter.js +16 -4
  20. package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
  21. package/dist/services/observability/results-baseline-artifact.js +80 -0
  22. package/dist/services/observability/results-baseline-rows.d.ts +33 -0
  23. package/dist/services/observability/results-baseline-rows.js +127 -0
  24. package/dist/services/observability/results-baseline.d.ts +115 -0
  25. package/dist/services/observability/results-baseline.js +101 -0
  26. package/package.json +7 -5
@@ -0,0 +1,67 @@
1
+ /**
2
+ * `src/services/observability/repair-cycle-metric.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the measured defect that forced the metric to
5
+ * change.
6
+ *
7
+ * The repair-cycle counter that used to live in `aggregation-helpers.ts`
8
+ * counted every slice-transition event whose `detail.artifactRole === 'qa'`.
9
+ * That is not a repair-cycle count: it counts QA's OWN internal state
10
+ * transitions, and it counts every transition TWICE because
11
+ * `peaks request transition` emits one event without `detail.from` and a
12
+ * second one with it. Measured over this repo's own recorded history
13
+ * (10 session dirs, 108 slices, 1102 slice-transition events) the old
14
+ * counter put 82 of the 108 slices at or over the cap of 3, while exactly
15
+ * ONE slice ever really reworked — and it reworked FIVE times.
16
+ * The other 81 alarms were a measurement artifact, not rework.
17
+ *
18
+ * So the metric is VERSIONED. Version 1 is the qa-event count — it is kept,
19
+ * under the name `legacyQaEventCount`, so the old number and the new number
20
+ * can be read side by side instead of being compared by accident. Version 2
21
+ * is the repair-cycle count computed here.
22
+ *
23
+ * THE v2 DEFINITION. A repair cycle = the slice's artifact RETURNS to an RD
24
+ * work state (`draft` | `spec-locked` | `implemented`) after it had entered a
25
+ * QA phase (`running` | `verdict-issued`). The state vocabulary is the one
26
+ * `ALLOWED_STATES_PER_ROLE` declares in
27
+ * `src/services/artifacts/request-artifact-state-helpers.ts`: `qa-handoff`
28
+ * is an RD state, so the normal closing hops `verdict-issued → qa-handoff` and
29
+ * `qa-handoff → handed-off` are the happy path, not rework.
30
+ *
31
+ * This is NOT the same measurement as
32
+ * `src/services/artifacts/repair-cycle-service.ts`, which counts the
33
+ * `QA return-to-rd cycle N` notes inside a request artifact. That one is the
34
+ * artifact contract's own record; this one is reconstructed from the
35
+ * observability event stream. The two are reported separately and are never
36
+ * merged.
37
+ */
38
+ import { type RepairCycleReport } from './aggregation-types.js';
39
+ import type { ObservabilityEvent } from './observability-service.js';
40
+ /**
41
+ * Version 1 was never versioned — it silently counted qa-role events.
42
+ * Version 2 is the repair-cycle count. A consumer that reads
43
+ * `metricVersion` can therefore tell which convention produced the numbers
44
+ * printed next to it.
45
+ */
46
+ export declare const REPAIR_CYCLE_METRIC_VERSION = 2;
47
+ /** What the v2 number counts, in one sentence, for every consumer that prints it. */
48
+ export declare const REPAIR_CYCLE_METRIC_DEFINITION: string;
49
+ /** What the v1 number counts, and why it must never be read as a repair-cycle count. */
50
+ export declare const LEGACY_QA_EVENT_COUNT_NOTE: string;
51
+ /** The three numbers one slice carries. */
52
+ export type SliceRepairMetrics = {
53
+ /** v2: how many times the slice came back to an RD work state after a QA phase. */
54
+ repairCycles: number;
55
+ /** v2: how many QA phases the slice entered. */
56
+ qaRounds: number;
57
+ /** v1: how many qa-role slice-transition events the slice emitted. */
58
+ legacyQaEventCount: number;
59
+ };
60
+ /** The three numbers, per slice, over the whole event stream. */
61
+ export declare function computeSliceRepairMetrics(events: readonly ObservabilityEvent[]): Map<string, SliceRepairMetrics>;
62
+ /**
63
+ * The repair-cycle report. `capHitCount` is computed from the v2 metric; the
64
+ * v1 count rides along under its own name so the two conventions can be
65
+ * compared rather than confused.
66
+ */
67
+ export declare function buildRepairCycleReport(events: readonly ObservabilityEvent[]): RepairCycleReport;
@@ -0,0 +1,223 @@
1
+ /**
2
+ * `src/services/observability/repair-cycle-metric.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the measured defect that forced the metric to
5
+ * change.
6
+ *
7
+ * The repair-cycle counter that used to live in `aggregation-helpers.ts`
8
+ * counted every slice-transition event whose `detail.artifactRole === 'qa'`.
9
+ * That is not a repair-cycle count: it counts QA's OWN internal state
10
+ * transitions, and it counts every transition TWICE because
11
+ * `peaks request transition` emits one event without `detail.from` and a
12
+ * second one with it. Measured over this repo's own recorded history
13
+ * (10 session dirs, 108 slices, 1102 slice-transition events) the old
14
+ * counter put 82 of the 108 slices at or over the cap of 3, while exactly
15
+ * ONE slice ever really reworked — and it reworked FIVE times.
16
+ * The other 81 alarms were a measurement artifact, not rework.
17
+ *
18
+ * So the metric is VERSIONED. Version 1 is the qa-event count — it is kept,
19
+ * under the name `legacyQaEventCount`, so the old number and the new number
20
+ * can be read side by side instead of being compared by accident. Version 2
21
+ * is the repair-cycle count computed here.
22
+ *
23
+ * THE v2 DEFINITION. A repair cycle = the slice's artifact RETURNS to an RD
24
+ * work state (`draft` | `spec-locked` | `implemented`) after it had entered a
25
+ * QA phase (`running` | `verdict-issued`). The state vocabulary is the one
26
+ * `ALLOWED_STATES_PER_ROLE` declares in
27
+ * `src/services/artifacts/request-artifact-state-helpers.ts`: `qa-handoff`
28
+ * is an RD state, so the normal closing hops `verdict-issued → qa-handoff` and
29
+ * `qa-handoff → handed-off` are the happy path, not rework.
30
+ *
31
+ * This is NOT the same measurement as
32
+ * `src/services/artifacts/repair-cycle-service.ts`, which counts the
33
+ * `QA return-to-rd cycle N` notes inside a request artifact. That one is the
34
+ * artifact contract's own record; this one is reconstructed from the
35
+ * observability event stream. The two are reported separately and are never
36
+ * merged.
37
+ */
38
+ import { artifactRole, isSliceTransition, transitionTo } from './aggregation-helpers.js';
39
+ import { REPAIR_CYCLE_CAP } from './aggregation-types.js';
40
+ /**
41
+ * Version 1 was never versioned — it silently counted qa-role events.
42
+ * Version 2 is the repair-cycle count. A consumer that reads
43
+ * `metricVersion` can therefore tell which convention produced the numbers
44
+ * printed next to it.
45
+ */
46
+ export const REPAIR_CYCLE_METRIC_VERSION = 2;
47
+ /** What the v2 number counts, in one sentence, for every consumer that prints it. */
48
+ export const REPAIR_CYCLE_METRIC_DEFINITION = 'A repair cycle = the slice returns to an RD work state (draft | spec-locked | implemented) ' +
49
+ 'after it had entered a QA phase (running | verdict-issued). One rework excursion counts once.';
50
+ /** What the v1 number counts, and why it must never be read as a repair-cycle count. */
51
+ export const LEGACY_QA_EVENT_COUNT_NOTE = 'Counts slice-transition events whose detail.artifactRole === "qa" — QA\'s own internal state ' +
52
+ 'transitions, NOT repair loops. Kept so the v1 and v2 numbers can be compared side by side.';
53
+ /**
54
+ * RD work states. A return to one of these after a QA phase is rework; a
55
+ * return to `qa-handoff` / `handed-off` is a forward or terminal hop.
56
+ */
57
+ const RD_WORK_STATES = new Set(['draft', 'spec-locked', 'implemented']);
58
+ /**
59
+ * QA work states — the `qa` role's `ALLOWED_STATES_PER_ROLE` entries minus
60
+ * `draft` (the initial state) and `blocked` (a terminal failure). Entering
61
+ * one of them opens a QA phase.
62
+ */
63
+ const QA_WORK_STATES = new Set(['running', 'verdict-issued']);
64
+ function eventTs(event) {
65
+ return typeof event.ts === 'string' ? event.ts : '';
66
+ }
67
+ /**
68
+ * The de-duplicated transition sequence of every slice.
69
+ *
70
+ * `detail.from` is never read: it is present on only 55% of the recorded
71
+ * events and contradicts the event order on 395 of those, so a metric that
72
+ * trusts it reads a field that does not mean what its name says. The
73
+ * sequence is rebuilt from `detail.to` + `detail.artifactRole` only.
74
+ */
75
+ function sliceSteps(events) {
76
+ const bySlice = new Map();
77
+ for (const event of events) {
78
+ if (!isSliceTransition(event))
79
+ continue;
80
+ const bucket = bySlice.get(event.sliceRid);
81
+ if (bucket === undefined)
82
+ bySlice.set(event.sliceRid, [event]);
83
+ else
84
+ bucket.push(event);
85
+ }
86
+ const steps = new Map();
87
+ for (const [rid, bucket] of bySlice) {
88
+ const ordered = [...bucket].sort((a, b) => eventTs(a).localeCompare(eventTs(b)));
89
+ const collapsed = [];
90
+ for (const event of ordered) {
91
+ const to = transitionTo(event);
92
+ if (to === null)
93
+ continue;
94
+ const role = artifactRole(event);
95
+ const last = collapsed[collapsed.length - 1];
96
+ // The same transition is emitted twice — once without `detail.from` and
97
+ // once with it. Both carry the same `to` and the same role, so the
98
+ // second one is dropped and the pair counts once.
99
+ if (last !== undefined && last.to === to && last.role === role)
100
+ continue;
101
+ collapsed.push({ to, role });
102
+ }
103
+ steps.set(rid, collapsed);
104
+ }
105
+ return steps;
106
+ }
107
+ /**
108
+ * Score one de-duplicated sequence.
109
+ *
110
+ * `qaPhaseOpen` is the "a rework is pending" latch: it is set when the slice
111
+ * enters QA work and cleared when the slice returns to an RD work state (one
112
+ * cycle, counted once) or leaves for a forward / terminal hop. `qaExcursionOpen`
113
+ * separates "a new QA phase" from "the same phase seen twice".
114
+ */
115
+ function scoreSteps(steps) {
116
+ let repairCycles = 0;
117
+ let qaRounds = 0;
118
+ let qaPhaseOpen = false;
119
+ let qaExcursionOpen = false;
120
+ for (const step of steps) {
121
+ const isQaWork = QA_WORK_STATES.has(step.to) && step.role === 'qa';
122
+ const isRdWork = RD_WORK_STATES.has(step.to) && step.role === 'rd';
123
+ if (isQaWork) {
124
+ if (!qaExcursionOpen) {
125
+ qaRounds += 1;
126
+ qaExcursionOpen = true;
127
+ }
128
+ qaPhaseOpen = true;
129
+ continue;
130
+ }
131
+ qaExcursionOpen = false;
132
+ if (isRdWork) {
133
+ if (qaPhaseOpen) {
134
+ repairCycles += 1;
135
+ qaPhaseOpen = false;
136
+ }
137
+ continue;
138
+ }
139
+ // A forward / terminal hop (`qa-handoff`, `handed-off`, `blocked`, ...):
140
+ // the QA phase is over and no rework is pending.
141
+ qaPhaseOpen = false;
142
+ }
143
+ return { repairCycles, qaRounds };
144
+ }
145
+ /** The v1 count: every qa-role slice-transition event, duplicates included. */
146
+ function legacyQaEventCounts(events) {
147
+ const counts = new Map();
148
+ for (const event of events) {
149
+ if (!isSliceTransition(event))
150
+ continue;
151
+ if (artifactRole(event) !== 'qa')
152
+ continue;
153
+ counts.set(event.sliceRid, (counts.get(event.sliceRid) ?? 0) + 1);
154
+ }
155
+ return counts;
156
+ }
157
+ /** The three numbers, per slice, over the whole event stream. */
158
+ export function computeSliceRepairMetrics(events) {
159
+ const steps = sliceSteps(events);
160
+ const legacy = legacyQaEventCounts(events);
161
+ const metrics = new Map();
162
+ for (const [rid, slice] of steps) {
163
+ const scored = scoreSteps(slice);
164
+ metrics.set(rid, {
165
+ repairCycles: scored.repairCycles,
166
+ qaRounds: scored.qaRounds,
167
+ legacyQaEventCount: legacy.get(rid) ?? 0
168
+ });
169
+ }
170
+ return metrics;
171
+ }
172
+ /**
173
+ * The repair-cycle report. `capHitCount` is computed from the v2 metric; the
174
+ * v1 count rides along under its own name so the two conventions can be
175
+ * compared rather than confused.
176
+ */
177
+ export function buildRepairCycleReport(events) {
178
+ const metrics = computeSliceRepairMetrics(events);
179
+ const rids = Array.from(metrics.keys()).sort((a, b) => a.localeCompare(b));
180
+ const perSlice = rids.map((rid) => ({
181
+ sliceRid: rid,
182
+ cycleCount: metrics.get(rid)?.repairCycles ?? 0
183
+ }));
184
+ const legacyPerSlice = rids.map((rid) => ({
185
+ sliceRid: rid,
186
+ eventCount: metrics.get(rid)?.legacyQaEventCount ?? 0
187
+ }));
188
+ const qaRoundPerSlice = rids.map((rid) => ({
189
+ sliceRid: rid,
190
+ roundCount: metrics.get(rid)?.qaRounds ?? 0
191
+ }));
192
+ const totalCycles = perSlice.reduce((sum, row) => sum + row.cycleCount, 0);
193
+ const capHitCount = perSlice.filter((row) => row.cycleCount >= REPAIR_CYCLE_CAP).length;
194
+ const legacyTotal = legacyPerSlice.reduce((sum, row) => sum + row.eventCount, 0);
195
+ const legacyCapHitCount = legacyPerSlice.filter((row) => row.eventCount >= REPAIR_CYCLE_CAP).length;
196
+ const qaRounds = {
197
+ metric: 'qa-rounds',
198
+ total: qaRoundPerSlice.reduce((sum, row) => sum + row.roundCount, 0),
199
+ peak: qaRoundPerSlice.reduce((peak, row) => Math.max(peak, row.roundCount), 0),
200
+ perSlice: qaRoundPerSlice
201
+ };
202
+ const legacyQaEventCount = {
203
+ metric: 'qa-role-transition-event-count',
204
+ metricVersion: 1,
205
+ note: LEGACY_QA_EVENT_COUNT_NOTE,
206
+ total: legacyTotal,
207
+ peak: legacyPerSlice.reduce((peak, row) => Math.max(peak, row.eventCount), 0),
208
+ capHitCount: legacyCapHitCount,
209
+ perSlice: legacyPerSlice
210
+ };
211
+ return {
212
+ metric: 'repair-cycles',
213
+ metricVersion: REPAIR_CYCLE_METRIC_VERSION,
214
+ definition: REPAIR_CYCLE_METRIC_DEFINITION,
215
+ totalCycles,
216
+ cap: REPAIR_CYCLE_CAP,
217
+ capHit: capHitCount > 0,
218
+ capHitCount,
219
+ perSlice,
220
+ qaRounds,
221
+ legacyQaEventCount
222
+ };
223
+ }
@@ -12,7 +12,7 @@
12
12
  * - Repair-cycle table: sliceRid | cycleCount
13
13
  * - Top-N slowest slices: same as slice table, sorted by durationMs desc
14
14
  */
15
- import type { FanoutBreakdown, Period, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation.js';
15
+ import { type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation.js';
16
16
  export type ReportInput = {
17
17
  scope: 'session' | 'all-sessions';
18
18
  scopeId: string;
@@ -12,6 +12,7 @@
12
12
  * - Repair-cycle table: sliceRid | cycleCount
13
13
  * - Top-N slowest slices: same as slice table, sorted by durationMs desc
14
14
  */
15
+ import { REPAIR_CYCLE_METRIC_VERSION } from './aggregation.js';
15
16
  const SLOWEST_TOP_N = 5;
16
17
  function pad(value, width) {
17
18
  const str = String(value);
@@ -47,7 +48,7 @@ function markdownStatusSummary(status) {
47
48
  lines.push(`| total slices | ${status.totalSlices} |`);
48
49
  lines.push(`| success count | ${status.successCount} |`);
49
50
  lines.push(`| fail count | ${status.failCount} |`);
50
- lines.push(`| repair-cycle peak | ${status.repairCyclePeak} |`);
51
+ lines.push(`| repair-cycle peak (v${REPAIR_CYCLE_METRIC_VERSION} metric) | ${status.repairCyclePeak} |`);
51
52
  lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
52
53
  lines.push('');
53
54
  return lines.join('\n');
@@ -93,20 +94,31 @@ function markdownRepairCycleTable(repairCycles) {
93
94
  const lines = [];
94
95
  lines.push('## Repair cycles');
95
96
  lines.push('');
97
+ // The version marker and the definition travel with the numbers: a reader
98
+ // must not be able to see a v2 cap-hit count next to a v1 count without the
99
+ // report saying that the two are different measurements.
100
+ lines.push(`- **metric**: \`${repairCycles.metric}\` (version ${repairCycles.metricVersion})`);
101
+ lines.push(`- **definition**: ${repairCycles.definition}`);
102
+ lines.push('');
96
103
  if (repairCycles.perSlice.length === 0) {
97
- lines.push('_No repair cycles recorded for this period._');
104
+ lines.push('_No slice transitions recorded for this period._');
98
105
  lines.push('');
99
106
  return lines.join('\n');
100
107
  }
101
- lines.push('| slice rid | cycle count |');
108
+ lines.push('| slice rid | repair cycles |');
102
109
  lines.push('|---|---|');
103
110
  for (const row of repairCycles.perSlice) {
104
111
  lines.push(`| ${row.sliceRid} | ${row.cycleCount} |`);
105
112
  }
106
113
  lines.push('');
114
+ lines.push(`- **total repair cycles (v${repairCycles.metricVersion})**: ${repairCycles.totalCycles}`);
107
115
  lines.push(`- **cap**: ${repairCycles.cap}`);
108
116
  lines.push(`- **cap hit**: ${repairCycles.capHit ? 'yes' : 'no'}`);
109
- lines.push(`- **slices at cap**: ${repairCycles.capHitCount}`);
117
+ lines.push(`- **slices at cap (v${repairCycles.metricVersion})**: ${repairCycles.capHitCount}`);
118
+ lines.push(`- **QA rounds (a separate metric — a QA phase, NOT a repair cycle)**: total ${repairCycles.qaRounds.total}, peak ${repairCycles.qaRounds.peak}`);
119
+ const legacy = repairCycles.legacyQaEventCount;
120
+ lines.push(`- **legacy v${legacy.metricVersion} \`${legacy.metric}\` (NOT a repair-cycle count)**: total ${legacy.total}, peak ${legacy.peak}, slices at cap ${legacy.capHitCount}`);
121
+ lines.push(`- **legacy note**: ${legacy.note}`);
110
122
  lines.push('');
111
123
  return lines.join('\n');
112
124
  }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-artifact.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the tracked artifact and the comparison against it
5
+ * are separated from the computation, so the question "what does the baseline
6
+ * say?" and the question "what does the machine measure right now?" can be
7
+ * answered by different modules.
8
+ *
9
+ * The tracked artifact lives at `.peaks/observability/results-baseline.json`.
10
+ * It is NOT CI-enforceable: its source data is gitignored session state
11
+ * (`.peaks/_runtime/<sessionId>/metrics/slices.jsonl`), so a CI runner has
12
+ * nothing to compare against. This module never wires the artifact into a
13
+ * gate; it only reads it, writes it, and reports drift against it.
14
+ */
15
+ import { type BaselineDrift, type BaselineRowKind, type BaselineTolerance, type ResultsBaseline } from './results-baseline.js';
16
+ /** Absolute path of the tracked artifact for a project root. */
17
+ export declare function resultsBaselinePath(projectRoot: string): string;
18
+ /** The tracked artifact, or null when this project has none yet. */
19
+ export declare function readTrackedResultsBaseline(projectRoot: string): ResultsBaseline | null;
20
+ /** Regenerate the tracked artifact and return the path it was written to. */
21
+ export declare function writeResultsBaseline(projectRoot: string, baseline: ResultsBaseline): string;
22
+ /** The tolerance that applies to a row kind, read from the tracked artifact. */
23
+ export declare function toleranceFor(tolerance: BaselineTolerance, kind: BaselineRowKind): number;
24
+ /**
25
+ * Compare a freshly computed baseline with the tracked one. A missing row or
26
+ * a metric-version mismatch is drift; so is a value that moved further than
27
+ * the tolerance its kind allows.
28
+ */
29
+ export declare function compareResultsBaseline(computed: ResultsBaseline, tracked: ResultsBaseline): BaselineDrift[];
@@ -0,0 +1,80 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-artifact.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the tracked artifact and the comparison against it
5
+ * are separated from the computation, so the question "what does the baseline
6
+ * say?" and the question "what does the machine measure right now?" can be
7
+ * answered by different modules.
8
+ *
9
+ * The tracked artifact lives at `.peaks/observability/results-baseline.json`.
10
+ * It is NOT CI-enforceable: its source data is gitignored session state
11
+ * (`.peaks/_runtime/<sessionId>/metrics/slices.jsonl`), so a CI runner has
12
+ * nothing to compare against. This module never wires the artifact into a
13
+ * gate; it only reads it, writes it, and reports drift against it.
14
+ */
15
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
16
+ import { dirname, join } from 'node:path';
17
+ /** Absolute path of the tracked artifact for a project root. */
18
+ export function resultsBaselinePath(projectRoot) {
19
+ return join(projectRoot, '.peaks', 'observability', 'results-baseline.json');
20
+ }
21
+ /** The tracked artifact, or null when this project has none yet. */
22
+ export function readTrackedResultsBaseline(projectRoot) {
23
+ const path = resultsBaselinePath(projectRoot);
24
+ if (!existsSync(path))
25
+ return null;
26
+ return JSON.parse(readFileSync(path, 'utf8'));
27
+ }
28
+ /** Regenerate the tracked artifact and return the path it was written to. */
29
+ export function writeResultsBaseline(projectRoot, baseline) {
30
+ const path = resultsBaselinePath(projectRoot);
31
+ mkdirSync(dirname(path), { recursive: true });
32
+ writeFileSync(path, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8');
33
+ return path;
34
+ }
35
+ /** The tolerance that applies to a row kind, read from the tracked artifact. */
36
+ export function toleranceFor(tolerance, kind) {
37
+ return tolerance[kind];
38
+ }
39
+ /**
40
+ * Compare a freshly computed baseline with the tracked one. A missing row or
41
+ * a metric-version mismatch is drift; so is a value that moved further than
42
+ * the tolerance its kind allows.
43
+ */
44
+ export function compareResultsBaseline(computed, tracked) {
45
+ const drifts = [];
46
+ if (computed.metricVersion !== tracked.metricVersion) {
47
+ drifts.push({
48
+ rowId: 'metric-version',
49
+ kind: 'metric-version-mismatch',
50
+ tracked: tracked.metricVersion,
51
+ computed: computed.metricVersion,
52
+ tolerance: null
53
+ });
54
+ }
55
+ const trackedRows = new Map(tracked.baselineRows.map((row) => [row.id, row]));
56
+ for (const row of computed.baselineRows) {
57
+ const prior = trackedRows.get(row.id);
58
+ if (prior === undefined) {
59
+ drifts.push({
60
+ rowId: row.id,
61
+ kind: 'row-missing',
62
+ tracked: null,
63
+ computed: row.value,
64
+ tolerance: null
65
+ });
66
+ continue;
67
+ }
68
+ const tolerance = toleranceFor(tracked.tolerance, row.kind);
69
+ if (Math.abs(row.value - prior.value) > tolerance) {
70
+ drifts.push({
71
+ rowId: row.id,
72
+ kind: 'value-drift',
73
+ tracked: prior.value,
74
+ computed: row.value,
75
+ tolerance
76
+ });
77
+ }
78
+ }
79
+ return drifts;
80
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-rows.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. The published rows and the old-vs-new metric
5
+ * comparison are the two parts of the results baseline that decide what a
6
+ * reader is shown, and both are big enough to push the computation module
7
+ * over the repository's 300 raw-line file-size cap.
8
+ *
9
+ * THE RULE THE ROWS OBEY. Every published row is a RATE or a PEAK. A raw
10
+ * count that grows with the number of slices ever recorded is a population
11
+ * descriptor, not a baseline row — those live in their own block of the
12
+ * artifact, and a reader must never mistake one for the other.
13
+ *
14
+ * THE RULE THE COMPARISON OBEY. Version 1 of the repair-cycle metric counted
15
+ * qa-role slice-transition events — QA's own internal state transitions,
16
+ * doubled by the duplicate emission — and was never a repair-cycle count.
17
+ * Version 2 counts repair cycles. The two are recorded side by side so the
18
+ * historical numbers are read as a DIFFERENT MEASUREMENT, not as a
19
+ * regression.
20
+ */
21
+ import type { RepairCycleReport, StatusAggregate } from './aggregation-types.js';
22
+ import type { BaselineRow, ResultsBaseline } from './results-baseline.js';
23
+ /**
24
+ * The published rows. Every one of them is a RATE or a PEAK: a raw count that
25
+ * grows with the number of slices ever recorded is a population descriptor,
26
+ * not a baseline row.
27
+ */
28
+ export declare function baselineRows(status: StatusAggregate, cycles: RepairCycleReport, slices: number): BaselineRow[];
29
+ /**
30
+ * The old-vs-new comparison, recorded so a reader sees that the historical
31
+ * numbers were a DIFFERENT MEASUREMENT and not a regression.
32
+ */
33
+ export declare function metricComparison(cycles: RepairCycleReport, slices: number): ResultsBaseline['metricComparison'];
@@ -0,0 +1,127 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-rows.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. The published rows and the old-vs-new metric
5
+ * comparison are the two parts of the results baseline that decide what a
6
+ * reader is shown, and both are big enough to push the computation module
7
+ * over the repository's 300 raw-line file-size cap.
8
+ *
9
+ * THE RULE THE ROWS OBEY. Every published row is a RATE or a PEAK. A raw
10
+ * count that grows with the number of slices ever recorded is a population
11
+ * descriptor, not a baseline row — those live in their own block of the
12
+ * artifact, and a reader must never mistake one for the other.
13
+ *
14
+ * THE RULE THE COMPARISON OBEY. Version 1 of the repair-cycle metric counted
15
+ * qa-role slice-transition events — QA's own internal state transitions,
16
+ * doubled by the duplicate emission — and was never a repair-cycle count.
17
+ * Version 2 counts repair cycles. The two are recorded side by side so the
18
+ * historical numbers are read as a DIFFERENT MEASUREMENT, not as a
19
+ * regression.
20
+ */
21
+ function ratio(numerator, denominator) {
22
+ if (denominator <= 0)
23
+ return 0;
24
+ return numerator / denominator;
25
+ }
26
+ /** Decimal base of the rounding helper. */
27
+ const DECIMAL_BASE = 10;
28
+ /** How many decimal places a published rate carries. */
29
+ const RATE_DIGITS = 6;
30
+ function round(value, digits) {
31
+ const factor = DECIMAL_BASE ** digits;
32
+ return Math.round(value * factor) / factor;
33
+ }
34
+ /** How many slices hold each value — the measured distribution of one metric. */
35
+ function distributionOf(values) {
36
+ const counts = new Map();
37
+ for (const value of values)
38
+ counts.set(value, (counts.get(value) ?? 0) + 1);
39
+ const out = {};
40
+ for (const key of [...counts.keys()].sort((a, b) => a - b)) {
41
+ out[String(key)] = counts.get(key) ?? 0;
42
+ }
43
+ return out;
44
+ }
45
+ /**
46
+ * The published rows. Every one of them is a RATE or a PEAK: a raw count that
47
+ * grows with the number of slices ever recorded is a population descriptor,
48
+ * not a baseline row.
49
+ */
50
+ export function baselineRows(status, cycles, slices) {
51
+ return [
52
+ {
53
+ id: 'repair-cycle-cap-hit-rate',
54
+ kind: 'rate',
55
+ value: round(ratio(cycles.capHitCount, slices), RATE_DIGITS),
56
+ unit: 'slices at or over the cap / slices',
57
+ description: 'Share of slices at or over the RD/QA repair cap. Version 2 metric.'
58
+ },
59
+ {
60
+ id: 'repair-cycle-peak',
61
+ kind: 'peak',
62
+ value: status.repairCyclePeak,
63
+ unit: 'repair cycles in one slice',
64
+ description: 'Highest repair-cycle count held by a single slice. Version 2 metric.'
65
+ },
66
+ {
67
+ id: 'qa-round-peak',
68
+ kind: 'peak',
69
+ value: cycles.qaRounds.peak,
70
+ unit: 'QA phases in one slice',
71
+ description: 'Highest number of QA phases in one slice. A QA phase is NOT a repair cycle.'
72
+ },
73
+ {
74
+ id: 'slice-success-rate',
75
+ kind: 'rate',
76
+ value: round(ratio(status.successCount, slices), RATE_DIGITS),
77
+ unit: 'successful slices / slices',
78
+ description: 'Share of slices whose final state is a terminal happy state.'
79
+ },
80
+ {
81
+ id: 'slice-failure-rate',
82
+ kind: 'rate',
83
+ value: round(ratio(status.failCount, slices), RATE_DIGITS),
84
+ unit: 'failed slices / slices',
85
+ description: 'Share of slices whose final state is blocked.'
86
+ },
87
+ {
88
+ id: 'fanout-cost-per-slice',
89
+ kind: 'mean',
90
+ value: round(ratio(status.fanoutCostTotal, slices), RATE_DIGITS),
91
+ unit: 'dispatch events / slice',
92
+ description: 'Mean sub-agent dispatch cost per slice.'
93
+ }
94
+ ];
95
+ }
96
+ /**
97
+ * The old-vs-new comparison, recorded so a reader sees that the historical
98
+ * numbers were a DIFFERENT MEASUREMENT and not a regression.
99
+ */
100
+ export function metricComparison(cycles, slices) {
101
+ const legacyValues = cycles.legacyQaEventCount.perSlice.map((row) => row.eventCount);
102
+ const cycleValues = cycles.perSlice.map((row) => row.cycleCount);
103
+ return {
104
+ note: "Version 1 counted qa-role slice-transition events (QA's own internal state transitions, " +
105
+ 'doubled by the duplicate emission) and was never a repair-cycle count. Version 2 counts ' +
106
+ 'repair cycles. The historical numbers below are a different measurement, not a regression — ' +
107
+ 'do not compare a v1 number with a v2 number.',
108
+ v1QaEventCount: {
109
+ metric: cycles.legacyQaEventCount.metric,
110
+ metricVersion: cycles.legacyQaEventCount.metricVersion,
111
+ total: cycles.legacyQaEventCount.total,
112
+ peak: cycles.legacyQaEventCount.peak,
113
+ slicesMeasured: slices,
114
+ slicesAtOrOverCap: cycles.legacyQaEventCount.capHitCount,
115
+ distribution: distributionOf(legacyValues)
116
+ },
117
+ v2RepairCycles: {
118
+ metric: cycles.metric,
119
+ metricVersion: cycles.metricVersion,
120
+ total: cycles.totalCycles,
121
+ peak: cycles.perSlice.reduce((peak, row) => Math.max(peak, row.cycleCount), 0),
122
+ slicesMeasured: slices,
123
+ slicesAtOrOverCap: cycles.capHitCount,
124
+ distribution: distributionOf(cycleValues)
125
+ }
126
+ };
127
+ }