peaks-loop 4.1.22 → 4.1.23
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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +82 -0
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands.js +79 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
- package/dist/services/artifacts/prerequisite-path-census.js +79 -0
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +26 -2
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +212 -0
- package/dist/services/observability/hotspot-shared.js +122 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +132 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +196 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +144 -0
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/package.json +5 -5
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/report-formatter-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* The near-miss section of the markdown report.
|
|
5
|
+
*
|
|
6
|
+
* WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
|
|
7
|
+
* 300-line cap, and this section does not fit beside the rest of it. The
|
|
8
|
+
* split follows the precedent in this directory: the hotspot section lives
|
|
9
|
+
* in `report-formatter-hotspots.ts` for the same reason.
|
|
10
|
+
*
|
|
11
|
+
* WHY THE RATE NEVER APPEARS ALONE. The report is what leaves the terminal
|
|
12
|
+
* — it gets pasted into a PR description — so a number in it has to be read
|
|
13
|
+
* the way it was measured. The near-miss rate is measured over the reason
|
|
14
|
+
* classes the scope had events for, and a scope can hold events for ONE of
|
|
15
|
+
* the three classes: the `gate` emitter postdates every session in this
|
|
16
|
+
* repository's recorded history, so two of the three classes have no events
|
|
17
|
+
* at all there.
|
|
18
|
+
*
|
|
19
|
+
* A rate printed on its own is therefore ambiguous between "there were no
|
|
20
|
+
* near-misses" and "the classes that could have shown a near-miss were never
|
|
21
|
+
* observed" — and the second reading is an ABSENCE read as a RESULT, which
|
|
22
|
+
* is the exact failure this whole programme exists to close. So the rate line
|
|
23
|
+
* carries its coverage with it: how many of the reason classes the rate was
|
|
24
|
+
* measured over, and that the rest is an absence of data rather than a
|
|
25
|
+
* result. A reader who sees ONLY the rate line still cannot draw the wrong
|
|
26
|
+
* conclusion.
|
|
27
|
+
*
|
|
28
|
+
* WHY THE COVERAGE IS A TABLE. Each class's rate divides by the slices THAT
|
|
29
|
+
* CLASS REACHED, not by every passing slice, so the class's own population
|
|
30
|
+
* has to travel with its number. The table says, per class: whether the class
|
|
31
|
+
* was observable at all, how many events it had, how many slices it reached,
|
|
32
|
+
* how many it flagged, and the rate it supports — or `not measured`, which is
|
|
33
|
+
* what a class with no events gets instead of a zero. It also says how many
|
|
34
|
+
* slices said NOTHING about the class: those slices could not be judged on it,
|
|
35
|
+
* and they are the ones a skipped check would hide in.
|
|
36
|
+
*
|
|
37
|
+
* WHY THE FLAGGED SLICES ARE LISTED. The count has to have a referent: a
|
|
38
|
+
* reader who is told that one slice passed with a check unsatisfied has to
|
|
39
|
+
* be able to see WHICH slice and WHICH check.
|
|
40
|
+
*/
|
|
41
|
+
/** How many decimals the rate's fraction is rounded to. */
|
|
42
|
+
const RATE_DECIMALS = 3;
|
|
43
|
+
/** How many decimals the rate's percentage is rounded to. */
|
|
44
|
+
const PERCENT_DECIMALS = 1;
|
|
45
|
+
/** The rate as a fraction and as a percentage — the two readings of one number. */
|
|
46
|
+
function formatRate(rate) {
|
|
47
|
+
const fraction = Number(rate.toFixed(RATE_DECIMALS));
|
|
48
|
+
const percent = Number((rate * 100).toFixed(PERCENT_DECIMALS));
|
|
49
|
+
return `${fraction} (${percent}%)`;
|
|
50
|
+
}
|
|
51
|
+
/** A rate as a percentage alone — the coverage table's cell. */
|
|
52
|
+
function formatPercent(rate) {
|
|
53
|
+
return `${Number((rate * 100).toFixed(PERCENT_DECIMALS))}%`;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* The line that states the rate AND what the rate was measured over.
|
|
57
|
+
*
|
|
58
|
+
* The qualifier is on the rate's own line, not on a line further down, so a
|
|
59
|
+
* reader who reads nothing else still cannot take a zero for a finding.
|
|
60
|
+
*/
|
|
61
|
+
function rateLine(nearMiss) {
|
|
62
|
+
const observableCount = nearMiss.coverage.filter((item) => item.observable).length;
|
|
63
|
+
const unobservedCount = nearMiss.unobservedClasses.length;
|
|
64
|
+
const coverage = unobservedCount === 0
|
|
65
|
+
? `measured over all ${nearMiss.coverage.length} reason classes, every one of which was ` +
|
|
66
|
+
'OBSERVABLE in this scope'
|
|
67
|
+
: `measured over the ${observableCount} of ${nearMiss.coverage.length} reason classes that ` +
|
|
68
|
+
`were OBSERVABLE in this scope; the other ${unobservedCount} class(es) had no events to ` +
|
|
69
|
+
'observe, so their share of the rate is an absence of data, not a result';
|
|
70
|
+
return (`- **rate**: ${formatRate(nearMiss.nearMissRate)} — ` +
|
|
71
|
+
`${nearMiss.nearMissSliceCount} of ${nearMiss.passedSliceCount} passed slice(s) were ` +
|
|
72
|
+
`near-misses. The rate is ${coverage}.`);
|
|
73
|
+
}
|
|
74
|
+
/** The line that states the denominator and the definition it counts by. */
|
|
75
|
+
function denominatorLine(nearMiss) {
|
|
76
|
+
const denominator = nearMiss.denominator;
|
|
77
|
+
return `- **denominator**: ${denominator.sliceCount} slice(s) — ${denominator.definition}`;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The line that reconciles the denominator with the status summary's count.
|
|
81
|
+
*
|
|
82
|
+
* "Passed" has two definitions in this repository and they do not count the
|
|
83
|
+
* same slices, so the difference is stated rather than smoothed over.
|
|
84
|
+
*/
|
|
85
|
+
function statusLine(nearMiss) {
|
|
86
|
+
const denominator = nearMiss.denominator;
|
|
87
|
+
if (denominator.difference === null) {
|
|
88
|
+
return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
|
|
89
|
+
'"passed" definitions agree over this scope.');
|
|
90
|
+
}
|
|
91
|
+
return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
|
|
92
|
+
'"passed" definitions do NOT count the same slices; the gap is stated below.');
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* The lines that say which gates the stream did not decide.
|
|
96
|
+
*
|
|
97
|
+
* The count covers TWO kinds, and the wording names both: a gate whose
|
|
98
|
+
* LIVENESS the stream did not decide (no usable phase), and a gate whose
|
|
99
|
+
* VERDICT the stream did not decide (an outcome or a gate id this build does
|
|
100
|
+
* not know). A count that said only "liveness" would misdescribe the two of
|
|
101
|
+
* the three kinds it carries.
|
|
102
|
+
*/
|
|
103
|
+
function undeterminedLines(nearMiss) {
|
|
104
|
+
const lines = [
|
|
105
|
+
`- **undetermined**: ${nearMiss.undetermined.length} gate(s) whose liveness or verdict the ` +
|
|
106
|
+
'recorded stream did not decide.'
|
|
107
|
+
];
|
|
108
|
+
for (const item of nearMiss.undetermined) {
|
|
109
|
+
lines.push(` - \`${item.sliceRid}\` / \`${item.gateId}\` — ${item.reason}`);
|
|
110
|
+
}
|
|
111
|
+
return lines;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* The lines that say which slices could not be MEASURED at all.
|
|
115
|
+
*
|
|
116
|
+
* A slice whose `verdict-issued` attempt records a prereq verdict this build
|
|
117
|
+
* cannot read is neither a pass nor a non-pass, so it is in neither the
|
|
118
|
+
* numerator nor the denominator. It is listed here because a slice that
|
|
119
|
+
* vanishes from the accounting reads as "no passing slices" — an absence read
|
|
120
|
+
* as a result.
|
|
121
|
+
*/
|
|
122
|
+
function unmeasuredLines(nearMiss) {
|
|
123
|
+
const lines = [
|
|
124
|
+
`- **unmeasured**: ${nearMiss.unmeasured.length} slice(s) whose pass verdict could not be READ, ` +
|
|
125
|
+
'so they are in neither the numerator nor the denominator.'
|
|
126
|
+
];
|
|
127
|
+
for (const item of nearMiss.unmeasured) {
|
|
128
|
+
lines.push(` - \`${item.sliceRid}\` — ${item.reason}`);
|
|
129
|
+
}
|
|
130
|
+
return lines;
|
|
131
|
+
}
|
|
132
|
+
/** The coverage table: what each reason class could and could not be observed for. */
|
|
133
|
+
function coverageTable(coverage) {
|
|
134
|
+
const lines = [];
|
|
135
|
+
lines.push('### Coverage');
|
|
136
|
+
lines.push('');
|
|
137
|
+
lines.push("Each class's rate is over the slices that class REACHED — a class that saw five slices " +
|
|
138
|
+
'out of a hundred reports one in five, not one in a hundred. A class with no events was ' +
|
|
139
|
+
'NOT observed, so it has no rate. The slices that recorded NOTHING about the class could ' +
|
|
140
|
+
'not be judged on it at all, so their count is stated beside the rate, as is the count of ' +
|
|
141
|
+
'the slices whose verdict could not be READ at all — they are in neither the numerator ' +
|
|
142
|
+
'nor the denominator.');
|
|
143
|
+
lines.push('');
|
|
144
|
+
lines.push('| reason class | observable | events | slices observed | slices with no events | ' +
|
|
145
|
+
'slices unreadable | slices flagged | rate |');
|
|
146
|
+
lines.push('|---|---|---|---|---|---|---|---|');
|
|
147
|
+
for (const item of coverage) {
|
|
148
|
+
lines.push(`| ${item.reason} | ${item.observable ? 'yes' : 'no'} | ${item.scopeEventCount} | ` +
|
|
149
|
+
`${item.observedSliceCount} | ${item.unobservedSliceCount} | ${item.unreadableSliceCount} | ` +
|
|
150
|
+
`${item.nearMissSliceCount} | ` +
|
|
151
|
+
`${item.rate === null ? 'not measured' : formatPercent(item.rate)} |`);
|
|
152
|
+
}
|
|
153
|
+
lines.push('');
|
|
154
|
+
return lines.join('\n');
|
|
155
|
+
}
|
|
156
|
+
/** The line that names the classes the rate does not measure. */
|
|
157
|
+
function unobservedLine(nearMiss) {
|
|
158
|
+
const unobserved = nearMiss.unobservedClasses;
|
|
159
|
+
if (unobserved.length === 0) {
|
|
160
|
+
return '- **unobserved classes**: none — every reason class had events to observe in this scope.';
|
|
161
|
+
}
|
|
162
|
+
const names = unobserved.map((reason) => `\`${reason}\``).join(', ');
|
|
163
|
+
return (`- **unobserved classes**: ${names} — these classes had NO events in this scope, so the ` +
|
|
164
|
+
'rate above does not measure them. A zero over an unobserved class is an absence of data, ' +
|
|
165
|
+
'not a result.');
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* The table of the slices the metric flagged, so the count has a referent.
|
|
169
|
+
*
|
|
170
|
+
* WHY EACH KEY CARRIES ITS STATE AT THE PASS MOMENT. "The check was
|
|
171
|
+
* unsatisfied" covers two materially different findings, and a reader has to
|
|
172
|
+
* be able to tell them apart:
|
|
173
|
+
*
|
|
174
|
+
* - `refused` — the check WAS running at the pass moment and said no. The
|
|
175
|
+
* gate was live, it fired, and the slice passed anyway.
|
|
176
|
+
* - `unattempted` — the check had NOT been run at the pass moment. The
|
|
177
|
+
* role that owns it had not yet attempted its transition.
|
|
178
|
+
*
|
|
179
|
+
* On this repository's recorded history one of the twelve findings is the
|
|
180
|
+
* first and eleven are the second — and the second is the more alarming of
|
|
181
|
+
* the two, because it means the pass was declared before the owning role had
|
|
182
|
+
* even tried. A table that said only "unsatisfied" would hide which of the
|
|
183
|
+
* two a reader is looking at.
|
|
184
|
+
*/
|
|
185
|
+
function flaggedSlices(nearMiss) {
|
|
186
|
+
const lines = [];
|
|
187
|
+
lines.push('### Flagged slices');
|
|
188
|
+
lines.push('');
|
|
189
|
+
if (nearMiss.records.length === 0) {
|
|
190
|
+
lines.push('_No slice passed with a required check still unsatisfied._');
|
|
191
|
+
lines.push('');
|
|
192
|
+
return lines.join('\n');
|
|
193
|
+
}
|
|
194
|
+
lines.push('| slice | reasons | passed at | unsatisfied checks |');
|
|
195
|
+
lines.push('|---|---|---|---|');
|
|
196
|
+
for (const record of nearMiss.records) {
|
|
197
|
+
const checks = record.unsatisfiedKeys.length === 0
|
|
198
|
+
? '—'
|
|
199
|
+
: record.unsatisfiedKeys.map((entry) => `${entry.key} (${entry.state})`).join(', ');
|
|
200
|
+
lines.push(`| ${record.sliceRid} | ${record.reasons.join(', ')} | ${record.passMoment.ts} | ${checks} |`);
|
|
201
|
+
}
|
|
202
|
+
lines.push('');
|
|
203
|
+
lines.push('_`refused` — the check was running at the pass moment and said no. ' +
|
|
204
|
+
'`unattempted` — the check had not been run at the pass moment at all, so the owning ' +
|
|
205
|
+
'role had not yet attempted its transition._');
|
|
206
|
+
lines.push('');
|
|
207
|
+
return lines.join('\n');
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* The markdown for the near-miss section, including its heading.
|
|
211
|
+
*
|
|
212
|
+
* The section is rendered ONLY when the caller supplies the measurement, so a
|
|
213
|
+
* caller that does not compute it gets exactly the report it got before.
|
|
214
|
+
*/
|
|
215
|
+
export function markdownNearMissSection(nearMiss) {
|
|
216
|
+
const lines = [];
|
|
217
|
+
lines.push('## Near-misses');
|
|
218
|
+
lines.push('');
|
|
219
|
+
lines.push(rateLine(nearMiss));
|
|
220
|
+
lines.push(denominatorLine(nearMiss));
|
|
221
|
+
lines.push(statusLine(nearMiss));
|
|
222
|
+
lines.push(...undeterminedLines(nearMiss));
|
|
223
|
+
lines.push(...unmeasuredLines(nearMiss));
|
|
224
|
+
if (nearMiss.denominator.difference !== null) {
|
|
225
|
+
lines.push('');
|
|
226
|
+
lines.push(nearMiss.denominator.difference.note);
|
|
227
|
+
}
|
|
228
|
+
lines.push('');
|
|
229
|
+
lines.push(coverageTable(nearMiss.coverage));
|
|
230
|
+
lines.push(unobservedLine(nearMiss));
|
|
231
|
+
lines.push('');
|
|
232
|
+
lines.push(flaggedSlices(nearMiss));
|
|
233
|
+
return lines.join('\n');
|
|
234
|
+
}
|
|
@@ -6,13 +6,20 @@
|
|
|
6
6
|
* entries. The CLI subcommand `peaks observability report` wires
|
|
7
7
|
* the file read + aggregation + format pipeline.
|
|
8
8
|
*
|
|
9
|
-
* - Header: scope, period, generated-at timestamp
|
|
10
|
-
*
|
|
9
|
+
* - Header: scope, period, generated-at timestamp, and any warning the
|
|
10
|
+
* scope or the period raised — the warning travels IN the body, because
|
|
11
|
+
* the body is what gets pasted and the stderr line is what gets lost
|
|
12
|
+
* - Near-miss section: rate | denominator | coverage | flagged slices
|
|
13
|
+
* - Slice table: rid | transitions | final state | duration | outcome
|
|
14
|
+
* - Hotspots table: artifact | owner | mode | confidence | count
|
|
11
15
|
* - Fanout table: role | count
|
|
12
16
|
* - Repair-cycle table: sliceRid | cycleCount
|
|
13
|
-
* - Top-N slowest slices:
|
|
17
|
+
* - Top-N slowest slices: rid | duration | transitions | final state,
|
|
18
|
+
* sorted by duration desc
|
|
14
19
|
*/
|
|
15
20
|
import { type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation.js';
|
|
21
|
+
import type { HotspotRow } from './hotspot-shared.js';
|
|
22
|
+
import type { NearMissReport } from './near-miss.js';
|
|
16
23
|
export type ReportInput = {
|
|
17
24
|
scope: 'session' | 'all-sessions';
|
|
18
25
|
scopeId: string;
|
|
@@ -22,6 +29,45 @@ export type ReportInput = {
|
|
|
22
29
|
slices: SliceRollup[];
|
|
23
30
|
fanout: FanoutBreakdown;
|
|
24
31
|
repairCycles: RepairCycleReport;
|
|
32
|
+
/**
|
|
33
|
+
* The warnings the scope or the period raised, rendered in the header.
|
|
34
|
+
*
|
|
35
|
+
* They are the reader's answer to "why is this table empty?" — a report
|
|
36
|
+
* scoped to one session, or narrowed to a period that holds no events,
|
|
37
|
+
* would otherwise show an empty table with no explanation. Printed to
|
|
38
|
+
* stderr they are lost the moment the report is pasted somewhere else, so
|
|
39
|
+
* the body carries them.
|
|
40
|
+
*/
|
|
41
|
+
warnings?: readonly string[];
|
|
42
|
+
/**
|
|
43
|
+
* The near-miss measurement, rendered when it is supplied.
|
|
44
|
+
*
|
|
45
|
+
* It is OPTIONAL, and absent means the section is not rendered at all — a
|
|
46
|
+
* caller that does not compute the measurement gets exactly the report it
|
|
47
|
+
* got before the section existed.
|
|
48
|
+
*
|
|
49
|
+
* THE SECTION NEVER PRINTS A BARE RATE. A rate over a reason class the
|
|
50
|
+
* scope had no events for is an absence of data, not a result, so the
|
|
51
|
+
* section carries the per-class coverage beside the number: which classes
|
|
52
|
+
* were observable, which were not, and that the unobserved ones are not
|
|
53
|
+
* measured. The section lives in `report-formatter-near-miss.ts` — this
|
|
54
|
+
* file was near its cap — and the reasoning is explained there.
|
|
55
|
+
*/
|
|
56
|
+
nearMiss?: NearMissReport;
|
|
57
|
+
/**
|
|
58
|
+
* The hotspot ranking, rendered when it is supplied.
|
|
59
|
+
*
|
|
60
|
+
* It is OPTIONAL, and absent means the section is not rendered at all — a
|
|
61
|
+
* caller that does not compute the ranking gets exactly the report it got
|
|
62
|
+
* before the ranking existed.
|
|
63
|
+
*
|
|
64
|
+
* THE SHAPE IS SET HERE, THE WIRING IS TASK 7's. The count column is
|
|
65
|
+
* named for what it counts — "times observed missing" and "candidate
|
|
66
|
+
* mentions" — so a reader cannot take a candidate mention for a missing
|
|
67
|
+
* artifact. The CLI command that supplies the ranking is Task 7's to
|
|
68
|
+
* wire; this file states the contract it will fill.
|
|
69
|
+
*/
|
|
70
|
+
hotspots?: readonly HotspotRow[];
|
|
25
71
|
};
|
|
26
72
|
declare function pad(value: string | number, width: number): string;
|
|
27
73
|
declare function formatDurationMs(ms: number | null): string;
|
|
@@ -6,13 +6,20 @@
|
|
|
6
6
|
* entries. The CLI subcommand `peaks observability report` wires
|
|
7
7
|
* the file read + aggregation + format pipeline.
|
|
8
8
|
*
|
|
9
|
-
* - Header: scope, period, generated-at timestamp
|
|
10
|
-
*
|
|
9
|
+
* - Header: scope, period, generated-at timestamp, and any warning the
|
|
10
|
+
* scope or the period raised — the warning travels IN the body, because
|
|
11
|
+
* the body is what gets pasted and the stderr line is what gets lost
|
|
12
|
+
* - Near-miss section: rate | denominator | coverage | flagged slices
|
|
13
|
+
* - Slice table: rid | transitions | final state | duration | outcome
|
|
14
|
+
* - Hotspots table: artifact | owner | mode | confidence | count
|
|
11
15
|
* - Fanout table: role | count
|
|
12
16
|
* - Repair-cycle table: sliceRid | cycleCount
|
|
13
|
-
* - Top-N slowest slices:
|
|
17
|
+
* - Top-N slowest slices: rid | duration | transitions | final state,
|
|
18
|
+
* sorted by duration desc
|
|
14
19
|
*/
|
|
15
|
-
import { REPAIR_CYCLE_METRIC_VERSION } from './aggregation.js';
|
|
20
|
+
import { REPAIR_CYCLE_METRIC_VERSION, sliceOutcome } from './aggregation.js';
|
|
21
|
+
import { markdownHotspotTables } from './report-formatter-hotspots.js';
|
|
22
|
+
import { markdownNearMissSection } from './report-formatter-near-miss.js';
|
|
16
23
|
const SLOWEST_TOP_N = 5;
|
|
17
24
|
function pad(value, width) {
|
|
18
25
|
const str = String(value);
|
|
@@ -35,6 +42,12 @@ function markdownHeader(input) {
|
|
|
35
42
|
lines.push(`- **period**: ${input.period}`);
|
|
36
43
|
lines.push(`- **generated at**: ${input.generatedAt}`);
|
|
37
44
|
lines.push(`- **scope marker**: from v2.11.1 install date (no backfill per PRD Q5)`);
|
|
45
|
+
const warnings = input.warnings ?? [];
|
|
46
|
+
if (warnings.length > 0) {
|
|
47
|
+
lines.push('');
|
|
48
|
+
for (const warning of warnings)
|
|
49
|
+
lines.push(`> **warning**: ${warning}`);
|
|
50
|
+
}
|
|
38
51
|
lines.push('');
|
|
39
52
|
return lines.join('\n');
|
|
40
53
|
}
|
|
@@ -48,11 +61,26 @@ function markdownStatusSummary(status) {
|
|
|
48
61
|
lines.push(`| total slices | ${status.totalSlices} |`);
|
|
49
62
|
lines.push(`| success count | ${status.successCount} |`);
|
|
50
63
|
lines.push(`| fail count | ${status.failCount} |`);
|
|
64
|
+
lines.push(`| stalled count | ${status.stalledCount} |`);
|
|
51
65
|
lines.push(`| repair-cycle peak (v${REPAIR_CYCLE_METRIC_VERSION} metric) | ${status.repairCyclePeak} |`);
|
|
52
66
|
lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
|
|
53
67
|
lines.push('');
|
|
54
68
|
return lines.join('\n');
|
|
55
69
|
}
|
|
70
|
+
/**
|
|
71
|
+
* The marker each outcome is drawn with in the slice table.
|
|
72
|
+
*
|
|
73
|
+
* A stalled slice is NOT a failure: it advanced partway and stopped, and
|
|
74
|
+
* drawing it `✗` is what put the "8 failures" into a report whose own summary
|
|
75
|
+
* counted 0 — the two halves of one report disagreeing about the same slices.
|
|
76
|
+
* `…` says "did not finish" and leaves the failure marker for the slices that
|
|
77
|
+
* really were blocked.
|
|
78
|
+
*/
|
|
79
|
+
const OUTCOME_MARKERS = {
|
|
80
|
+
success: '✓',
|
|
81
|
+
failed: '✗',
|
|
82
|
+
stalled: '…'
|
|
83
|
+
};
|
|
56
84
|
function markdownSliceTable(slices) {
|
|
57
85
|
const lines = [];
|
|
58
86
|
lines.push('## Slices');
|
|
@@ -62,14 +90,22 @@ function markdownSliceTable(slices) {
|
|
|
62
90
|
lines.push('');
|
|
63
91
|
return lines.join('\n');
|
|
64
92
|
}
|
|
65
|
-
lines.push('| rid | transitions | final state | duration |
|
|
93
|
+
lines.push('| rid | transitions | final state | duration | outcome |');
|
|
66
94
|
lines.push('|---|---|---|---|---|');
|
|
67
95
|
for (const slice of slices) {
|
|
68
|
-
lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${slice
|
|
96
|
+
lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${OUTCOME_MARKERS[sliceOutcome(slice)]} |`);
|
|
69
97
|
}
|
|
70
98
|
lines.push('');
|
|
99
|
+
lines.push('_✓ succeeded · ✗ failed · … did not finish (stalled)_');
|
|
100
|
+
lines.push('');
|
|
71
101
|
return lines.join('\n');
|
|
72
102
|
}
|
|
103
|
+
/**
|
|
104
|
+
* The hotspot section: the rows, split by what their count actually counts.
|
|
105
|
+
*
|
|
106
|
+
* The section lives in `report-formatter-hotspots.ts` — this file was near
|
|
107
|
+
* its cap — and the split of the tables is explained there.
|
|
108
|
+
*/
|
|
73
109
|
function markdownFanoutTable(fanout) {
|
|
74
110
|
const lines = [];
|
|
75
111
|
lines.push('## Fanout');
|
|
@@ -148,14 +184,19 @@ function markdownSlowestSlices(slices) {
|
|
|
148
184
|
* layer reads events, calls aggregations, and passes the result here.
|
|
149
185
|
*/
|
|
150
186
|
export function renderObservabilityReport(input) {
|
|
151
|
-
const sections = [
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
187
|
+
const sections = [markdownHeader(input), markdownStatusSummary(input.status)];
|
|
188
|
+
// The near-miss section is rendered ONLY when the measurement is supplied,
|
|
189
|
+
// so a caller that does not compute it gets exactly the report it got
|
|
190
|
+
// before. It sits between the summary and the slice table: the summary
|
|
191
|
+
// says what the slices did, the near-misses say what was skipped.
|
|
192
|
+
if (input.nearMiss !== undefined)
|
|
193
|
+
sections.push(markdownNearMissSection(input.nearMiss));
|
|
194
|
+
sections.push(markdownSliceTable(input.slices));
|
|
195
|
+
// The hotspot section is rendered ONLY when the ranking is supplied, so a
|
|
196
|
+
// caller that does not compute it gets exactly the report it got before.
|
|
197
|
+
if (input.hotspots !== undefined)
|
|
198
|
+
sections.push(markdownHotspotTables(input.hotspots));
|
|
199
|
+
sections.push(markdownFanoutTable(input.fanout), markdownRepairCycleTable(input.repairCycles), markdownSlowestSlices(input.slices));
|
|
159
200
|
return sections.join('\n').trimEnd() + '\n';
|
|
160
201
|
}
|
|
161
202
|
export const REPORT_FORMAT_CONSTANTS = {
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/retro-attribution.ts`
|
|
3
|
+
*
|
|
4
|
+
* Retro-attribution: name the artifacts behind the historical failures that
|
|
5
|
+
* recorded only a COUNT.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS. Every slice-transition event carries `detail.missingCount`.
|
|
8
|
+
* The v1 events in this repository's own event log were written before the
|
|
9
|
+
* emitter kept the missing-artifact LIST, so the list they name is not in the
|
|
10
|
+
* record, and no amount of reading the record will produce it.
|
|
11
|
+
*
|
|
12
|
+
* WHAT CAN BE DERIVED INSTEAD. The prerequisite table is a pure function of
|
|
13
|
+
* three values — the artifact role, the target state and the request type —
|
|
14
|
+
* and a v1 event carries the first two. Re-deriving the table for that
|
|
15
|
+
* transition yields the CANDIDATE set: the artifacts the missing entries could
|
|
16
|
+
* be. The recorded count then says how many artifacts were missing in total,
|
|
17
|
+
* which is what decides whether the candidates can be narrowed.
|
|
18
|
+
*
|
|
19
|
+
* WHY THE CONFIDENCE IS CAPPED AT `inferred`. The derivation runs over
|
|
20
|
+
* TODAY's prerequisite table, and the table is version-controlled code that
|
|
21
|
+
* changes between two recorded events. A retro-attribution is therefore a
|
|
22
|
+
* reconstruction, not a measurement, so `exact` — which means "observed when
|
|
23
|
+
* it happened" — is never returned here. Only a forward event that stored the
|
|
24
|
+
* missing list as it was observed can carry it.
|
|
25
|
+
*
|
|
26
|
+
* WHY A COUNT MAY EXCEED THE TABLE. The recorded count is not the table's row
|
|
27
|
+
* count: the missing list is also fed by the judged-declaration refusals (the
|
|
28
|
+
* security artifact's own location) and by the handoff capsule's gate-evidence
|
|
29
|
+
* declaration (a key naming a file that is not on disk). Neither of those two
|
|
30
|
+
* sources is derivable from what a v1 event stores, so a count larger than
|
|
31
|
+
* the table's list yields `ambiguous` with the table's entries as the
|
|
32
|
+
* candidates. The candidate set is never widened with a guess, and the
|
|
33
|
+
* confidence never rises to cover the gap.
|
|
34
|
+
*/
|
|
35
|
+
import { type RequestType } from '../artifacts/artifact-prerequisites.js';
|
|
36
|
+
import type { RequestArtifactRole } from '../artifacts/artifact-templates.js';
|
|
37
|
+
import type { RequestTypeSource } from '../artifacts/request-artifact-metadata.js';
|
|
38
|
+
import type { RequestArtifactState } from '../artifacts/request-artifact-state-helpers.js';
|
|
39
|
+
/**
|
|
40
|
+
* How far an attribution can be trusted.
|
|
41
|
+
*
|
|
42
|
+
* - `exact` — the missing list was measured when the event was recorded.
|
|
43
|
+
* Only a forward event carries it; the retro-attribution never does.
|
|
44
|
+
* - `inferred` — the recorded count is CONSISTENT WITH the whole candidate
|
|
45
|
+
* list being the missing set. It is not proof, and it must not be read as
|
|
46
|
+
* proof: the missing list has three sources (the prereq table, the
|
|
47
|
+
* judged-declaration refusals, the gate-evidence declaration), so a count
|
|
48
|
+
* equal to the table's length can match by coincidence while the missing
|
|
49
|
+
* entries came from the other two. `inferred` says "the count does not
|
|
50
|
+
* contradict this set", never "these artifacts were proven missing".
|
|
51
|
+
* - `ambiguous` — the count cannot single out any subset, so the candidate
|
|
52
|
+
* set stays the whole prereq list. An EMPTY candidate set means "nothing
|
|
53
|
+
* derivable" — distinguishable from "ambiguous among N" by
|
|
54
|
+
* `candidates.length === 0`, and it is the shape a transition the table
|
|
55
|
+
* holds nothing for produces.
|
|
56
|
+
*/
|
|
57
|
+
export type AttributionConfidence = 'exact' | 'inferred' | 'ambiguous';
|
|
58
|
+
/**
|
|
59
|
+
* One attribution: how far it can be trusted, and the artifacts it can name.
|
|
60
|
+
*
|
|
61
|
+
* The candidates are a CANDIDATE list: the prereq paths of the transition,
|
|
62
|
+
* each paired with the skill that owns it. They name the artifacts the missing
|
|
63
|
+
* entries could be — not the artifacts that were proven missing, which only a
|
|
64
|
+
* forward event records. `ownerSkill` is `null` when no skill owns the path —
|
|
65
|
+
* a stated absence, not a missing field.
|
|
66
|
+
*
|
|
67
|
+
* `typeSource` says where the type that produced these candidates came from.
|
|
68
|
+
* The CANDIDATES are the same either way — the effective type is the type the
|
|
69
|
+
* prerequisite table was indexed by — but a reader asking "how many of these
|
|
70
|
+
* attributions rested on a type nobody wrote down?" cannot answer it unless
|
|
71
|
+
* the source travels with the attribution.
|
|
72
|
+
*/
|
|
73
|
+
export type RetroAttribution = {
|
|
74
|
+
readonly confidence: AttributionConfidence;
|
|
75
|
+
readonly candidates: ReadonlyArray<{
|
|
76
|
+
path: string;
|
|
77
|
+
ownerSkill: string | null;
|
|
78
|
+
}>;
|
|
79
|
+
/** Whether the type that produced these candidates was DECLARED or defaulted. */
|
|
80
|
+
readonly typeSource: RequestTypeSource;
|
|
81
|
+
};
|
|
82
|
+
/** The inputs one historical failure carries, all of them derivable. */
|
|
83
|
+
export type RetroAttributionInput = {
|
|
84
|
+
/** The role of the artifact that was moving — the event's `detail.artifactRole`. */
|
|
85
|
+
readonly artifactRole: RequestArtifactRole;
|
|
86
|
+
/** The state it was moving to — the event's `detail.to`. */
|
|
87
|
+
readonly newState: RequestArtifactState;
|
|
88
|
+
/** The request's EFFECTIVE type — read from the artifact, or the default. */
|
|
89
|
+
readonly requestType: RequestType;
|
|
90
|
+
/** Where that type came from: declared on the `- type:` line, or defaulted. */
|
|
91
|
+
readonly typeSource: RequestTypeSource;
|
|
92
|
+
/** How many artifacts the event recorded as missing. */
|
|
93
|
+
readonly missingCount: number;
|
|
94
|
+
};
|
|
95
|
+
/**
|
|
96
|
+
* Attribute one historical failure to the artifacts that could have been
|
|
97
|
+
* missing.
|
|
98
|
+
*
|
|
99
|
+
* The rules, in the order they apply:
|
|
100
|
+
*
|
|
101
|
+
* - a transition the table demands nothing for → `ambiguous`, no candidate;
|
|
102
|
+
* - a count that cannot be read → `ambiguous`, the whole list as candidates;
|
|
103
|
+
* - a count of zero → `ambiguous`, no candidate (the record says nothing
|
|
104
|
+
* was missing, so naming a candidate would contradict it);
|
|
105
|
+
* - a count equal to the list's length → `inferred`, the whole list;
|
|
106
|
+
* - any other count → `ambiguous`, the whole list as candidates.
|
|
107
|
+
*
|
|
108
|
+
* WHAT `inferred` CLAIMS AT THE THIRD RULE. The count matches the table's
|
|
109
|
+
* length, so the count is CONSISTENT WITH the whole list being the missing
|
|
110
|
+
* set — and it is not proof of that. The missing list has three sources (the
|
|
111
|
+
* prereq table, the judged-declaration refusals, the gate-evidence
|
|
112
|
+
* declaration), and a count equal to the table's length can match by
|
|
113
|
+
* coincidence while the missing entries came from the other two, leaving a
|
|
114
|
+
* table entry intact. The same holds for a one-entry list and a count of one:
|
|
115
|
+
* the single missing entry may have come from source two or three. So the
|
|
116
|
+
* label says "the count does not contradict this set", and never "these
|
|
117
|
+
* artifacts were proven missing".
|
|
118
|
+
*
|
|
119
|
+
* The last rule covers a count of one against a list of several, a count
|
|
120
|
+
* between zero and the list's length, and a count ABOVE the list's length —
|
|
121
|
+
* the last because the missing list has two further sources the table does
|
|
122
|
+
* not describe, and neither of them is derivable from a v1 event.
|
|
123
|
+
*
|
|
124
|
+
* This function never returns `exact`. That confidence belongs to a forward
|
|
125
|
+
* event, which recorded the missing list as it was observed; this one
|
|
126
|
+
* reconstructs a candidate set from today's table and can therefore only
|
|
127
|
+
* claim `inferred` or `ambiguous`.
|
|
128
|
+
*/
|
|
129
|
+
export declare function attributeV1Failure(opts: RetroAttributionInput): RetroAttribution;
|