peaks-loop 4.1.21 → 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.
Files changed (78) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +191 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  6. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  7. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  8. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  9. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  10. package/dist/cli/commands/observability-commands-queries.js +88 -47
  11. package/dist/cli/commands/observability-commands.js +79 -20
  12. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  13. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  14. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  15. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  16. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  17. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  18. package/dist/services/artifacts/rd-gate-event.js +211 -0
  19. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  20. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  21. package/dist/services/distribution/json-layout.d.ts +20 -0
  22. package/dist/services/distribution/json-layout.js +195 -0
  23. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  24. package/dist/services/distribution/plugin-manifest.js +40 -4
  25. package/dist/services/observability/aggregation-types.d.ts +21 -0
  26. package/dist/services/observability/aggregation.d.ts +12 -2
  27. package/dist/services/observability/aggregation.js +26 -2
  28. package/dist/services/observability/compliance-judge.d.ts +77 -0
  29. package/dist/services/observability/compliance-judge.js +143 -0
  30. package/dist/services/observability/compliance-spec.d.ts +96 -0
  31. package/dist/services/observability/compliance-spec.js +29 -0
  32. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  33. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  34. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  35. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  36. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  37. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  38. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  39. package/dist/services/observability/hotspot-rows.js +89 -0
  40. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  41. package/dist/services/observability/hotspot-shared.js +122 -0
  42. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  43. package/dist/services/observability/hotspot-sources.js +142 -0
  44. package/dist/services/observability/hotspots.d.ts +47 -0
  45. package/dist/services/observability/hotspots.js +47 -0
  46. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  47. package/dist/services/observability/near-miss-attempts.js +223 -0
  48. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  49. package/dist/services/observability/near-miss-coverage.js +108 -0
  50. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  51. package/dist/services/observability/near-miss-denominator.js +75 -0
  52. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  53. package/dist/services/observability/near-miss-difference.js +132 -0
  54. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  55. package/dist/services/observability/near-miss-facts.js +101 -0
  56. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  57. package/dist/services/observability/near-miss-gate-events.js +106 -0
  58. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  59. package/dist/services/observability/near-miss-gates.js +135 -0
  60. package/dist/services/observability/near-miss-records.d.ts +93 -0
  61. package/dist/services/observability/near-miss-records.js +87 -0
  62. package/dist/services/observability/near-miss.d.ts +148 -0
  63. package/dist/services/observability/near-miss.js +196 -0
  64. package/dist/services/observability/observability-schema.d.ts +17 -2
  65. package/dist/services/observability/observability-schema.js +21 -1
  66. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  67. package/dist/services/observability/owner-skill-map.js +144 -0
  68. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  69. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  70. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  71. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  72. package/dist/services/observability/report-formatter.d.ts +49 -3
  73. package/dist/services/observability/report-formatter.js +55 -14
  74. package/dist/services/observability/retro-attribution.d.ts +129 -0
  75. package/dist/services/observability/retro-attribution.js +134 -0
  76. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  77. package/dist/services/observability/session-metric-rows.js +184 -0
  78. package/package.json +5 -5
@@ -0,0 +1,89 @@
1
+ /**
2
+ * `src/services/observability/hotspot-rows.ts`
3
+ *
4
+ * The hotspot RANKING: the rows, in the order a reader should read them.
5
+ *
6
+ * WHY THIS EXISTS. The programme's premise is that the QA verdict says
7
+ * "pass" without saying WHICH check was skipped, so a reader cannot go and
8
+ * fix the skill that is actually failing. This ranking names the artifact and
9
+ * its owner, so the next step ("raise this to a hook") has a target.
10
+ *
11
+ * TWO SOURCES, AND THE CONFIDENCE COLUMN SAYS WHICH. A FORWARD event (v2)
12
+ * carries the missing list as it was MEASURED: the path, the mode and the
13
+ * owner are all facts, and the row's confidence is `exact`. A HISTORICAL
14
+ * event (v1) carries only a COUNT, so the artifact is a CANDIDATE recovered
15
+ * by the retro-attribution, and the row's confidence is `inferred` (the count
16
+ * matched the whole prerequisite list) or `ambiguous` (the count did not
17
+ * localise to one entry). The spec (§2.2 S2.2) puts all three tiers in one
18
+ * ranking and requires them to be LABELLED, because an `inferred` row says
19
+ * "this artifact was in the missing set", NOT "this artifact was proven
20
+ * missing". A reader who sorts by count must be able to see which rows are
21
+ * measurements and which are reconstructions.
22
+ *
23
+ * A ROW WITH NO OWNER IS STILL A ROW. An artifact whose directory the
24
+ * owner map does not know is a NEW artifact type, and a new artifact type is
25
+ * exactly what a reader needs to see — the gate is that it is COUNTED, not
26
+ * that it is attributed. Dropping it would hide a whole class of failures
27
+ * behind a mapping gap, which is the failure mode the owner map exists to
28
+ * prevent.
29
+ *
30
+ * WHY THE READERS LIVE NEXT DOOR. `hotspot-sources.ts` holds the reading of
31
+ * the event stream, so this file states what a row MEANS and what the
32
+ * ranking guarantees; `hotspot-shared.ts` holds the vocabulary the two
33
+ * share. The same split `aggregation.ts` and `aggregation-helpers.ts` make in
34
+ * this directory.
35
+ */
36
+ import { forwardRows, isHistoricalFailure, recordedMissing, retroRows } from './hotspot-sources.js';
37
+ import { countMeaningOf } from './hotspot-shared.js';
38
+ /** The confidence order the ranking sorts by at equal counts. */
39
+ const CONFIDENCE_ORDER = {
40
+ exact: 0,
41
+ inferred: 1,
42
+ ambiguous: 2
43
+ };
44
+ /** The row a builder has become. */
45
+ function toRow(row) {
46
+ return {
47
+ ownerSkill: row.ownerSkill,
48
+ ownerReason: row.ownerReason,
49
+ artifact: row.artifact,
50
+ kind: row.kind,
51
+ confidence: row.confidence,
52
+ count: row.count,
53
+ countMeaning: countMeaningOf(row.confidence),
54
+ sessions: row.sessions.size,
55
+ firstSeen: row.firstSeen,
56
+ lastSeen: row.lastSeen,
57
+ evidence: row.evidence
58
+ };
59
+ }
60
+ /**
61
+ * The hotspot ranking over a set of events.
62
+ *
63
+ * The request types are the DECLARED type of each slice, resolved by the
64
+ * caller from the request artifact: the retro-attribution needs them to
65
+ * re-derive a transition's prerequisite list, and the event stream does
66
+ * not carry them. Without them the historical failures cannot be
67
+ * attributed, and the ranking would silently show only the forward events.
68
+ */
69
+ export function aggregateHotspots(events, requestTypes = new Map()) {
70
+ const builders = new Map();
71
+ for (const event of events) {
72
+ const rid = event.sliceRid;
73
+ if (rid === undefined)
74
+ continue;
75
+ if (isHistoricalFailure(event)) {
76
+ retroRows(event, rid, requestTypes.get(rid), builders);
77
+ continue;
78
+ }
79
+ if (recordedMissing(event) !== null) {
80
+ forwardRows(event, rid, builders);
81
+ }
82
+ }
83
+ return [...builders.values()]
84
+ .map(toRow)
85
+ .sort((a, b) => b.count - a.count ||
86
+ CONFIDENCE_ORDER[a.confidence] - CONFIDENCE_ORDER[b.confidence] ||
87
+ (a.ownerSkill ?? '').localeCompare(b.ownerSkill ?? '') ||
88
+ a.artifact.localeCompare(b.artifact));
89
+ }
@@ -0,0 +1,212 @@
1
+ /**
2
+ * `src/services/observability/hotspot-shared.ts`
3
+ *
4
+ * The vocabulary the hotspot ranking and its two source readers share: what
5
+ * a row IS, the key rows are grouped by, and the counting primitive that
6
+ * adds one occurrence to a row.
7
+ *
8
+ * WHY IT IS ITS OWN MODULE. The ranking, the forward reader and the
9
+ * historical reader all need these, and the ranking CALLS the readers — so
10
+ * the shared vocabulary cannot live in the ranking without a cycle. This
11
+ * module is the seam.
12
+ *
13
+ * WHY THE ARTIFACT IS ITS TEMPLATE, AND WHY THE PLACEHOLDER STAYS. The path
14
+ * a forward event carries has the slice's rid substituted into it, so the same
15
+ * artifact missed by two slices would be two rows and the count would be
16
+ * useless. The template the path came from is recognised by re-filling the
17
+ * slot with the rid and comparing, which is exact — a substring search could
18
+ * match the wrong template.
19
+ *
20
+ * The template is named WITH its `<rid>` placeholder intact. Stripping the
21
+ * placeholder produced paths that name no real file — `qa/test-cases/.md` is
22
+ * a directory and a dot, not an artifact — and a reader could not tell which
23
+ * artifact the row was about. The placeholder is the template's own way of
24
+ * saying "the slice's id goes here", and it is what makes a forward row and a
25
+ * retro-attributed row for the same artifact land on the SAME row.
26
+ *
27
+ * Paths no template claims (a declaration key, a legacy location) keep their
28
+ * own shape.
29
+ */
30
+ import type { RequestType } from '../artifacts/artifact-prerequisites.js';
31
+ import type { RequestTypeSource } from '../artifacts/request-artifact-metadata.js';
32
+ import type { AttributionConfidence } from './retro-attribution.js';
33
+ import type { ObservabilityEvent } from './observability-service.js';
34
+ /** How a row's artifact was known. */
35
+ export type HotspotConfidence = AttributionConfidence;
36
+ /** A pointer at one raw event. */
37
+ export type HotspotEvidence = {
38
+ readonly sessionId: string;
39
+ readonly ts: string;
40
+ /** The slice the event belongs to. */
41
+ readonly rid?: string;
42
+ };
43
+ /** One row of the hotspot ranking. */
44
+ export type HotspotRow = {
45
+ /** The skill that owns the artifact, or null when no row claims it. */
46
+ readonly ownerSkill: string | null;
47
+ /**
48
+ * Why the artifact has no owning skill, or null when it has one.
49
+ *
50
+ * The owner map states WHY each ownerless shape has no owner, and the row
51
+ * carries that reason: a reader is told "no skill produces this" rather
52
+ * than left to guess, and the reason no longer lives only in the tests.
53
+ */
54
+ readonly ownerReason: string | null;
55
+ /** The artifact path, with the `<rid>` placeholder left in place. */
56
+ readonly artifact: string;
57
+ /**
58
+ * The failure mode. For an `exact` row this is MEASURED — the file was
59
+ * absent, or it existed and lacked a marker. For a reconstructed row it is
60
+ * the surface the prerequisite checks, which is what a count alone can
61
+ * support.
62
+ */
63
+ readonly kind: 'absent' | 'body';
64
+ /**
65
+ * How the row was known.
66
+ *
67
+ * - `exact` — the missing list was MEASURED when the event was written.
68
+ * - `inferred` — recovered by the retro-attribution; the count matched the
69
+ * whole prerequisite list.
70
+ * - `ambiguous` — a CANDIDATE SET: the count did not localise to one
71
+ * entry, so the row says the artifact was a candidate, NOT that it was
72
+ * missing. An `ambiguous` row is not proof, and the report must not
73
+ * present it as such.
74
+ */
75
+ readonly confidence: HotspotConfidence;
76
+ /**
77
+ * How many times the artifact was COUNTED.
78
+ *
79
+ * WHAT THE NUMBER COUNTS DEPENDS ON THE CONFIDENCE, and the row says which
80
+ * — see `countMeaning`. For an `exact` row it is how many times the
81
+ * artifact was observed MISSING. For a reconstructed row it is how many
82
+ * times the artifact appeared in the CANDIDATE SET, which is not the same
83
+ * thing at all: one real failure contributes to every candidate the
84
+ * attribution could not narrow, so the number is candidate mentions, not
85
+ * failures.
86
+ */
87
+ readonly count: number;
88
+ /**
89
+ * What `count` counts, so a reader cannot take a candidate mention for a
90
+ * missing artifact.
91
+ *
92
+ * - `observed-missing` — the artifact was seen to be missing, this many
93
+ * times. Only an `exact` row says this.
94
+ * - `candidate-mentions` — the artifact was one of the candidates, this
95
+ * many times. One real failure contributes to SEVERAL candidates, so
96
+ * this number is an UPPER BOUND on the real count and is NOT a count of
97
+ * failures.
98
+ */
99
+ readonly countMeaning: 'observed-missing' | 'candidate-mentions';
100
+ /** How many sessions the occurrences came from. */
101
+ readonly sessions: number;
102
+ readonly firstSeen: string;
103
+ readonly lastSeen: string;
104
+ /** The raw events the row was counted from. */
105
+ readonly evidence: readonly HotspotEvidence[];
106
+ };
107
+ /**
108
+ * A slice's request type, AND where that type came from.
109
+ *
110
+ * WHY THE SOURCE RIDES ALONG WITH THE TYPE. The EFFECTIVE type of a request
111
+ * whose artifact declares no `- type:` line is the default — it is the type
112
+ * the prerequisite table was actually indexed by when the transition ran — so
113
+ * the attribution must use it. But a default and a DECLARED type are
114
+ * different facts, and a reader asking "how many of these attributions rested
115
+ * on a type nobody wrote down?" cannot answer it if the source is dropped on
116
+ * the way through.
117
+ *
118
+ * The two facts a reader must not confuse:
119
+ *
120
+ * - `declared` — the request artifact carried a usable `- type:` line.
121
+ * - `default` — the artifact carried NO usable line, so the effective type
122
+ * is the system's default. The type is real; nobody wrote it down.
123
+ */
124
+ export type RequestTypeReading = {
125
+ /** The type the prerequisite table was indexed by. */
126
+ readonly requestType: RequestType;
127
+ /** Whether that type was DECLARED or fell back to the default. */
128
+ readonly source: RequestTypeSource;
129
+ };
130
+ /** The request type of each slice, for the retro-attribution of v1 failures. */
131
+ export type HotspotRequestTypes = ReadonlyMap<string, RequestTypeReading>;
132
+ /**
133
+ * The artifact path with the `<rid>` placeholder left in place.
134
+ *
135
+ * The template is recognised by re-filling the slot with the rid and
136
+ * comparing, which is exact. The template is then returned AS IT IS: the
137
+ * placeholder is part of the artifact's name, and stripping it produced paths
138
+ * that name no real file.
139
+ *
140
+ * WHY A `<rid>`-LESS PATH IS RETURNED AS IT IS. The templates matched here
141
+ * are the ones that CARRY a slot, so a path that came from a template
142
+ * without one — `qa/.initiated` is a real artifact — never matches and is
143
+ * returned unchanged. That asymmetry is DELIBERATE: there is nothing to
144
+ * canonicalise, because the path already names the artifact it is. Do not
145
+ * "fix" it by widening the template list — a template with no slot would
146
+ * match EVERY path it happened to equal, and the comparison is only exact
147
+ * for the form that carries the substituted id.
148
+ */
149
+ export declare function canonicalArtifact(path: string, rid: string): string;
150
+ /** The owner of an artifact, or null when no row claims it. */
151
+ export declare function ownerOf(artifact: string): string | null;
152
+ /** The row under construction. */
153
+ export type RowBuilder = {
154
+ ownerSkill: string | null;
155
+ ownerReason: string | null;
156
+ artifact: string;
157
+ kind: 'absent' | 'body';
158
+ confidence: HotspotConfidence;
159
+ count: number;
160
+ readonly sessions: Set<string>;
161
+ firstSeen: string;
162
+ lastSeen: string;
163
+ readonly evidence: HotspotEvidence[];
164
+ };
165
+ /**
166
+ * What a row's count counts, decided by the row's confidence.
167
+ *
168
+ * Only a row whose missing list was MEASURED counts missing artifacts. A
169
+ * reconstructed row counts CANDIDATE MENTIONS, and one real failure
170
+ * contributes to every candidate the attribution could not narrow — so the
171
+ * number is not a count of failures and must not be read as one.
172
+ */
173
+ export declare function countMeaningOf(confidence: HotspotConfidence): 'observed-missing' | 'candidate-mentions';
174
+ /**
175
+ * The ranking split by what each row's count counts.
176
+ *
177
+ * WHY THE SPLIT EXISTS. A row's `count` means DIFFERENT THINGS depending on
178
+ * how the row was known: an `exact` row counted the artifact being MISSING,
179
+ * and a reconstructed row counted the artifact being one of the CANDIDATES —
180
+ * one real failure contributes to every candidate the attribution could not
181
+ * narrow, so the number is candidate mentions, not failures.
182
+ *
183
+ * A consumer that sees `count: 91` and `countMeaning` as a SIBLING field has
184
+ * to look up the meaning before reading the number. Splitting the rows by
185
+ * their meaning puts the meaning in the NAME the reader sees — the group a
186
+ * row is in says what its count counts — and the same split serves the
187
+ * markdown report, so there is ONE structure in two places.
188
+ */
189
+ export type HotspotGroups = {
190
+ /** Rows whose count is how many times the artifact was OBSERVED missing. */
191
+ readonly observedOmissions: readonly HotspotRow[];
192
+ /** Rows whose count is how many times the artifact was a CANDIDATE mention. */
193
+ readonly candidateMentions: readonly HotspotRow[];
194
+ };
195
+ /**
196
+ * The ranking, split by what each row's count counts.
197
+ *
198
+ * The split is by the row's `countMeaning`, so it cannot disagree with the
199
+ * column the report renders.
200
+ */
201
+ export declare function groupHotspotsByMeaning(rows: readonly HotspotRow[]): HotspotGroups;
202
+ /** One occurrence of an artifact, ready to be counted. */
203
+ export type Occurrence = {
204
+ readonly ownerSkill: string | null;
205
+ readonly artifact: string;
206
+ readonly kind: 'absent' | 'body';
207
+ readonly confidence: HotspotConfidence;
208
+ readonly event: ObservabilityEvent;
209
+ readonly rid: string;
210
+ };
211
+ /** Count one occurrence into the row the key names, creating it if new. */
212
+ export declare function count(into: Map<string, RowBuilder>, occurrence: Occurrence): void;
@@ -0,0 +1,122 @@
1
+ /**
2
+ * `src/services/observability/hotspot-shared.ts`
3
+ *
4
+ * The vocabulary the hotspot ranking and its two source readers share: what
5
+ * a row IS, the key rows are grouped by, and the counting primitive that
6
+ * adds one occurrence to a row.
7
+ *
8
+ * WHY IT IS ITS OWN MODULE. The ranking, the forward reader and the
9
+ * historical reader all need these, and the ranking CALLS the readers — so
10
+ * the shared vocabulary cannot live in the ranking without a cycle. This
11
+ * module is the seam.
12
+ *
13
+ * WHY THE ARTIFACT IS ITS TEMPLATE, AND WHY THE PLACEHOLDER STAYS. The path
14
+ * a forward event carries has the slice's rid substituted into it, so the same
15
+ * artifact missed by two slices would be two rows and the count would be
16
+ * useless. The template the path came from is recognised by re-filling the
17
+ * slot with the rid and comparing, which is exact — a substring search could
18
+ * match the wrong template.
19
+ *
20
+ * The template is named WITH its `<rid>` placeholder intact. Stripping the
21
+ * placeholder produced paths that name no real file — `qa/test-cases/.md` is
22
+ * a directory and a dot, not an artifact — and a reader could not tell which
23
+ * artifact the row was about. The placeholder is the template's own way of
24
+ * saying "the slice's id goes here", and it is what makes a forward row and a
25
+ * retro-attributed row for the same artifact land on the SAME row.
26
+ *
27
+ * Paths no template claims (a declaration key, a legacy location) keep their
28
+ * own shape.
29
+ */
30
+ import { allPrerequisitePaths } from '../artifacts/prerequisite-path-census.js';
31
+ import { ownerSkillForPath, unownedPathReason } from './owner-skill-map.js';
32
+ /** The templates a path can be recognised as, with the rid slot filled. */
33
+ const PREREQ_TEMPLATES = allPrerequisitePaths().filter((path) => path.includes('<rid>'));
34
+ /**
35
+ * The artifact path with the `<rid>` placeholder left in place.
36
+ *
37
+ * The template is recognised by re-filling the slot with the rid and
38
+ * comparing, which is exact. The template is then returned AS IT IS: the
39
+ * placeholder is part of the artifact's name, and stripping it produced paths
40
+ * that name no real file.
41
+ *
42
+ * WHY A `<rid>`-LESS PATH IS RETURNED AS IT IS. The templates matched here
43
+ * are the ones that CARRY a slot, so a path that came from a template
44
+ * without one — `qa/.initiated` is a real artifact — never matches and is
45
+ * returned unchanged. That asymmetry is DELIBERATE: there is nothing to
46
+ * canonicalise, because the path already names the artifact it is. Do not
47
+ * "fix" it by widening the template list — a template with no slot would
48
+ * match EVERY path it happened to equal, and the comparison is only exact
49
+ * for the form that carries the substituted id.
50
+ */
51
+ export function canonicalArtifact(path, rid) {
52
+ for (const template of PREREQ_TEMPLATES) {
53
+ if (template.replace('<rid>', rid) === path)
54
+ return template;
55
+ }
56
+ return path;
57
+ }
58
+ /** The owner of an artifact, or null when no row claims it. */
59
+ export function ownerOf(artifact) {
60
+ return ownerSkillForPath(artifact);
61
+ }
62
+ /**
63
+ * What a row's count counts, decided by the row's confidence.
64
+ *
65
+ * Only a row whose missing list was MEASURED counts missing artifacts. A
66
+ * reconstructed row counts CANDIDATE MENTIONS, and one real failure
67
+ * contributes to every candidate the attribution could not narrow — so the
68
+ * number is not a count of failures and must not be read as one.
69
+ */
70
+ export function countMeaningOf(confidence) {
71
+ return confidence === 'exact' ? 'observed-missing' : 'candidate-mentions';
72
+ }
73
+ /**
74
+ * The ranking, split by what each row's count counts.
75
+ *
76
+ * The split is by the row's `countMeaning`, so it cannot disagree with the
77
+ * column the report renders.
78
+ */
79
+ export function groupHotspotsByMeaning(rows) {
80
+ return {
81
+ observedOmissions: rows.filter((row) => row.countMeaning === 'observed-missing'),
82
+ candidateMentions: rows.filter((row) => row.countMeaning === 'candidate-mentions')
83
+ };
84
+ }
85
+ /** The key a row is grouped by. */
86
+ function rowKey(ownerSkill, artifact, kind, confidence) {
87
+ return [ownerSkill ?? '', artifact, kind, confidence].join(' :: ');
88
+ }
89
+ /** Add one occurrence to a row. */
90
+ function accumulate(row, occurrence) {
91
+ const { event, rid } = occurrence;
92
+ row.count += 1;
93
+ row.sessions.add(event.sessionId);
94
+ if (row.firstSeen === '' || event.ts < row.firstSeen)
95
+ row.firstSeen = event.ts;
96
+ if (event.ts > row.lastSeen)
97
+ row.lastSeen = event.ts;
98
+ row.evidence.push({ sessionId: event.sessionId, ts: event.ts, rid });
99
+ }
100
+ /** Count one occurrence into the row the key names, creating it if new. */
101
+ export function count(into, occurrence) {
102
+ const key = rowKey(occurrence.ownerSkill, occurrence.artifact, occurrence.kind, occurrence.confidence);
103
+ const existing = into.get(key);
104
+ if (existing !== undefined) {
105
+ accumulate(existing, occurrence);
106
+ return;
107
+ }
108
+ const row = {
109
+ ownerSkill: occurrence.ownerSkill,
110
+ ownerReason: occurrence.ownerSkill === null ? unownedPathReason(occurrence.artifact) : null,
111
+ artifact: occurrence.artifact,
112
+ kind: occurrence.kind,
113
+ confidence: occurrence.confidence,
114
+ count: 0,
115
+ sessions: new Set(),
116
+ firstSeen: '',
117
+ lastSeen: '',
118
+ evidence: []
119
+ };
120
+ into.set(key, row);
121
+ accumulate(row, occurrence);
122
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * `src/services/observability/hotspot-sources.ts`
3
+ *
4
+ * The two readers the hotspot ranking is built from: a FORWARD event's
5
+ * measured missing list, and a HISTORICAL event's count-only failure.
6
+ *
7
+ * WHY THEY ARE HERE AND NOT IN THE RANKING. The ranking says what a row
8
+ * MEANS; this file says how each SOURCE of a row is turned into one. The
9
+ * two are kept apart so the difference between a measurement and a
10
+ * reconstruction is a difference of FILES, not of a branch buried in the
11
+ * middle of a sort.
12
+ *
13
+ * WHY A HISTORICAL EVENT CANNOT CARRY A MODE. A v1 event recorded only a
14
+ * COUNT — not which artifacts were missing, and not whether each was absent
15
+ * or short. So a reconstructed row names the failure SURFACE the
16
+ * prerequisite checks, and the row's confidence is what marks it as a
17
+ * reconstruction rather than a measurement.
18
+ */
19
+ import { type RetroAttribution } from './retro-attribution.js';
20
+ import { type RequestTypeReading, type RowBuilder } from './hotspot-shared.js';
21
+ import type { ObservabilityEvent } from './observability-service.js';
22
+ /** One missing entry as the event recorded it. */
23
+ type RecordedMissing = {
24
+ readonly path?: unknown;
25
+ readonly kind?: unknown;
26
+ readonly ownerSkill?: unknown;
27
+ };
28
+ /** The measured missing list of a forward event, or null when it has none. */
29
+ export declare function recordedMissing(event: ObservabilityEvent): readonly RecordedMissing[] | null;
30
+ /**
31
+ * Whether the event is a HISTORICAL failure — a count-only one the
32
+ * retro-attribution can speak about.
33
+ *
34
+ * A forward event carries the missing list as it was measured, so it is not
35
+ * a reconstruction and never enters the retro-attribution.
36
+ */
37
+ export declare function isHistoricalFailure(event: ObservabilityEvent): boolean;
38
+ /** The rows a slice's forward (measured) missing list contributes. */
39
+ export declare function forwardRows(event: ObservabilityEvent, rid: string, into: Map<string, RowBuilder>): void;
40
+ /**
41
+ * The attribution of one historical failure, or null when the event is not
42
+ * one the retro-attribution can speak about.
43
+ *
44
+ * ONE IMPLEMENTATION, TWO CALLERS. The rows and the attribution summary must
45
+ * agree about which failures were attributed — a copy of this gate would
46
+ * drift, and the drift would show up as two numbers that disagree.
47
+ */
48
+ export declare function attributeFailure(event: ObservabilityEvent, reading: RequestTypeReading | undefined): {
49
+ attribution: RetroAttribution;
50
+ role: string;
51
+ state: string;
52
+ } | null;
53
+ /** The rows a slice's historical (count-only) failure contributes. */
54
+ export declare function retroRows(event: ObservabilityEvent, rid: string, reading: RequestTypeReading | undefined, into: Map<string, RowBuilder>): void;
55
+ export {};
@@ -0,0 +1,142 @@
1
+ /**
2
+ * `src/services/observability/hotspot-sources.ts`
3
+ *
4
+ * The two readers the hotspot ranking is built from: a FORWARD event's
5
+ * measured missing list, and a HISTORICAL event's count-only failure.
6
+ *
7
+ * WHY THEY ARE HERE AND NOT IN THE RANKING. The ranking says what a row
8
+ * MEANS; this file says how each SOURCE of a row is turned into one. The
9
+ * two are kept apart so the difference between a measurement and a
10
+ * reconstruction is a difference of FILES, not of a branch buried in the
11
+ * middle of a sort.
12
+ *
13
+ * WHY A HISTORICAL EVENT CANNOT CARRY A MODE. A v1 event recorded only a
14
+ * COUNT — not which artifacts were missing, and not whether each was absent
15
+ * or short. So a reconstructed row names the failure SURFACE the
16
+ * prerequisite checks, and the row's confidence is what marks it as a
17
+ * reconstruction rather than a measurement.
18
+ */
19
+ import { getPrerequisitesFor } from '../artifacts/artifact-prerequisites.js';
20
+ import { ALLOWED_STATES_PER_ROLE } from '../artifacts/request-artifact-state-helpers.js';
21
+ import { attributeV1Failure } from './retro-attribution.js';
22
+ import { canonicalArtifact, count, ownerOf } from './hotspot-shared.js';
23
+ /**
24
+ * The artifact roles a transition can belong to.
25
+ *
26
+ * READ FROM THE CANONICAL TABLE, not from a list written here: a second
27
+ * copy of the state vocabulary is a list that rots, and a state missing from
28
+ * it silently drops every failure of that transition — which is how a whole
29
+ * class of failures stops being counted.
30
+ */
31
+ const TRANSITION_ROLES = Object.keys(ALLOWED_STATES_PER_ROLE);
32
+ /** The measured missing list of a forward event, or null when it has none. */
33
+ export function recordedMissing(event) {
34
+ const detail = event.detail;
35
+ if (!Array.isArray(detail.missing))
36
+ return null;
37
+ return detail.missing;
38
+ }
39
+ /**
40
+ * Whether the event is a HISTORICAL failure — a count-only one the
41
+ * retro-attribution can speak about.
42
+ *
43
+ * A forward event carries the missing list as it was measured, so it is not
44
+ * a reconstruction and never enters the retro-attribution.
45
+ */
46
+ export function isHistoricalFailure(event) {
47
+ if (recordedMissing(event) !== null)
48
+ return false;
49
+ return event.detail.prereqOk === false;
50
+ }
51
+ /**
52
+ * The failure mode a prerequisite's own check reports.
53
+ *
54
+ * A prerequisite with no body markers can only fail by the file being
55
+ * ABSENT; one WITH body markers is a file whose MARKERS may be short. The
56
+ * row therefore names the surface the prerequisite checks, which is what a
57
+ * count alone can support.
58
+ */
59
+ function failureSurface(path, role, state, type) {
60
+ const entry = getPrerequisitesFor(role, state, type).find((candidate) => candidate.relativePath === path);
61
+ if (entry === undefined)
62
+ return 'absent';
63
+ const demandsMarkers = (entry.mustContain?.length ?? 0) > 0 ||
64
+ (entry.mustContainAny?.length ?? 0) > 0 ||
65
+ (entry.headingMustContain?.length ?? 0) > 0;
66
+ return demandsMarkers ? 'body' : 'absent';
67
+ }
68
+ /** The rows a slice's forward (measured) missing list contributes. */
69
+ export function forwardRows(event, rid, into) {
70
+ const missing = recordedMissing(event);
71
+ if (missing === null)
72
+ return;
73
+ for (const entry of missing) {
74
+ if (typeof entry.path !== 'string')
75
+ continue;
76
+ const artifact = canonicalArtifact(entry.path, rid);
77
+ const kind = entry.kind === 'body' ? 'body' : 'absent';
78
+ // The owner is the ONE THE EVENT RECORDED, including a null: the event
79
+ // resolved it when it was written, and a path the owner map does not know
80
+ // is exactly the case that must stay visible. The map is only consulted
81
+ // for an entry that carries no owner field at all.
82
+ const ownerSkill = 'ownerSkill' in entry
83
+ ? typeof entry.ownerSkill === 'string'
84
+ ? entry.ownerSkill
85
+ : null
86
+ : ownerOf(artifact);
87
+ count(into, { ownerSkill, artifact, kind, confidence: 'exact', event, rid });
88
+ }
89
+ }
90
+ /**
91
+ * The attribution of one historical failure, or null when the event is not
92
+ * one the retro-attribution can speak about.
93
+ *
94
+ * ONE IMPLEMENTATION, TWO CALLERS. The rows and the attribution summary must
95
+ * agree about which failures were attributed — a copy of this gate would
96
+ * drift, and the drift would show up as two numbers that disagree.
97
+ */
98
+ export function attributeFailure(event, reading) {
99
+ if (reading === undefined)
100
+ return null;
101
+ const requestType = reading.requestType;
102
+ const detail = event.detail;
103
+ const role = typeof detail.artifactRole === 'string' ? detail.artifactRole : '';
104
+ const state = typeof detail.to === 'string' ? detail.to : '';
105
+ const missingCount = typeof detail.missingCount === 'number' ? detail.missingCount : 0;
106
+ if (!TRANSITION_ROLES.includes(role))
107
+ return null;
108
+ if (!ALLOWED_STATES_PER_ROLE[role].includes(state)) {
109
+ return null;
110
+ }
111
+ return {
112
+ attribution: attributeV1Failure({
113
+ artifactRole: role,
114
+ newState: state,
115
+ requestType,
116
+ typeSource: reading.source,
117
+ missingCount
118
+ }),
119
+ role,
120
+ state
121
+ };
122
+ }
123
+ /** The rows a slice's historical (count-only) failure contributes. */
124
+ export function retroRows(event, rid, reading, into) {
125
+ const resolved = attributeFailure(event, reading);
126
+ if (resolved === null)
127
+ return;
128
+ const { attribution, role, state } = resolved;
129
+ for (const candidate of attribution.candidates) {
130
+ const artifact = canonicalArtifact(candidate.path, rid);
131
+ const kind = failureSurface(candidate.path, role, state, reading?.requestType ?? 'feature');
132
+ const ownerSkill = candidate.ownerSkill ?? ownerOf(artifact);
133
+ count(into, {
134
+ ownerSkill,
135
+ artifact,
136
+ kind,
137
+ confidence: attribution.confidence,
138
+ event,
139
+ rid
140
+ });
141
+ }
142
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `src/services/observability/hotspots.ts`
3
+ *
4
+ * The hotspot ranking: which artifact does a skill keep failing to deliver,
5
+ * and who owns it.
6
+ *
7
+ * WHY THIS EXISTS. The programme's premise is that the QA verdict says
8
+ * "pass" without saying WHICH check was skipped, so a reader cannot go and
9
+ * fix the skill that is actually failing. This ranking names the artifact and
10
+ * its owner, so the next step ("raise this to a hook") has a target.
11
+ *
12
+ * TWO SOURCES, AND THE CONFIDENCE COLUMN SAYS WHICH. A FORWARD event (v2)
13
+ * carries the missing list as it was MEASURED: the path, the mode and the
14
+ * owner are all facts, and the row's confidence is `exact`. A HISTORICAL
15
+ * event (v1) carries only a COUNT, so the artifact is a CANDIDATE recovered
16
+ * by the retro-attribution, and the row's confidence is `inferred` (the count
17
+ * matched the whole prerequisite list) or `ambiguous` (the count did not
18
+ * localise to one entry). The spec (§2.2 S2.2) puts all three tiers in one
19
+ * ranking and requires them to be LABELLED, because an `inferred` row says
20
+ * "this artifact was in the missing set", NOT "this artifact was proven
21
+ * missing". A reader who sorts by count must be able to see which rows are
22
+ * measurements and which are reconstructions.
23
+ *
24
+ * WHY THE ROW SAYS WHAT ITS COUNT COUNTS. The confidence label names HOW the
25
+ * row was known, but a reader sorting by `count` sees a NUMBER and reaches
26
+ * for the obvious meaning — how many times the artifact was missing. For a
27
+ * reconstructed row that meaning is wrong: one real failure contributes to
28
+ * every candidate the attribution could not narrow, so the count is CANDIDATE
29
+ * MENTIONS. The row therefore carries `countMeaning` beside the count, so the
30
+ * number cannot be read the wrong way without the reader having to know the
31
+ * rule.
32
+ *
33
+ * A ROW WITH NO OWNER IS STILL A ROW. An artifact whose directory the
34
+ * owner map does not know is a NEW artifact type, and a new artifact type is
35
+ * exactly what a reader needs to see — the gate is that it is COUNTED, not
36
+ * that it is attributed. Dropping it would hide a whole class of failures
37
+ * behind a mapping gap, which is the failure mode the owner map exists to
38
+ * prevent.
39
+ *
40
+ * WHY THE READERS LIVE NEXT DOOR. `hotspot-rows.ts` holds the reading of
41
+ * the event stream, so this file states what a row MEANS and what the
42
+ * ranking guarantees — the same split `aggregation.ts` and
43
+ * `aggregation-helpers.ts` make in this directory.
44
+ */
45
+ export { aggregateHotspots } from './hotspot-rows.js';
46
+ export { summarizeAttribution, type HotspotAttributionSummary, type RequestArtifactCounts } from './hotspot-attribution-summary.js';
47
+ export { canonicalArtifact, countMeaningOf, type HotspotConfidence, type HotspotEvidence, type HotspotRequestTypes, type HotspotRow, type RequestTypeReading } from './hotspot-shared.js';