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.
Files changed (72) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +82 -0
  3. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  4. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  5. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  6. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  8. package/dist/cli/commands/observability-commands-queries.js +88 -47
  9. package/dist/cli/commands/observability-commands.js +79 -20
  10. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  11. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  12. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  13. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  14. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  15. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  16. package/dist/services/artifacts/rd-gate-event.js +211 -0
  17. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  18. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  19. package/dist/services/observability/aggregation-types.d.ts +21 -0
  20. package/dist/services/observability/aggregation.d.ts +12 -2
  21. package/dist/services/observability/aggregation.js +26 -2
  22. package/dist/services/observability/compliance-judge.d.ts +77 -0
  23. package/dist/services/observability/compliance-judge.js +143 -0
  24. package/dist/services/observability/compliance-spec.d.ts +96 -0
  25. package/dist/services/observability/compliance-spec.js +29 -0
  26. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  27. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  28. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  29. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  30. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  31. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  32. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  33. package/dist/services/observability/hotspot-rows.js +89 -0
  34. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  35. package/dist/services/observability/hotspot-shared.js +122 -0
  36. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  37. package/dist/services/observability/hotspot-sources.js +142 -0
  38. package/dist/services/observability/hotspots.d.ts +47 -0
  39. package/dist/services/observability/hotspots.js +47 -0
  40. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  41. package/dist/services/observability/near-miss-attempts.js +223 -0
  42. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  43. package/dist/services/observability/near-miss-coverage.js +108 -0
  44. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  45. package/dist/services/observability/near-miss-denominator.js +75 -0
  46. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  47. package/dist/services/observability/near-miss-difference.js +132 -0
  48. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  49. package/dist/services/observability/near-miss-facts.js +101 -0
  50. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  51. package/dist/services/observability/near-miss-gate-events.js +106 -0
  52. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  53. package/dist/services/observability/near-miss-gates.js +135 -0
  54. package/dist/services/observability/near-miss-records.d.ts +93 -0
  55. package/dist/services/observability/near-miss-records.js +87 -0
  56. package/dist/services/observability/near-miss.d.ts +148 -0
  57. package/dist/services/observability/near-miss.js +196 -0
  58. package/dist/services/observability/observability-schema.d.ts +17 -2
  59. package/dist/services/observability/observability-schema.js +21 -1
  60. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  61. package/dist/services/observability/owner-skill-map.js +144 -0
  62. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  63. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  64. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  65. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  66. package/dist/services/observability/report-formatter.d.ts +49 -3
  67. package/dist/services/observability/report-formatter.js +55 -14
  68. package/dist/services/observability/retro-attribution.d.ts +129 -0
  69. package/dist/services/observability/retro-attribution.js +134 -0
  70. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  71. package/dist/services/observability/session-metric-rows.js +184 -0
  72. package/package.json +5 -5
@@ -0,0 +1,74 @@
1
+ /**
2
+ * `src/services/observability/hotspot-attribution-summary.ts`
3
+ *
4
+ * The retro-attribution's own accounting: how many historical failures were
5
+ * attributed, how confidently, and on what basis.
6
+ *
7
+ * WHY THIS IS A SEPARATE MODULE FROM THE RANKING. The ranking answers
8
+ * "which artifact does a skill keep failing to deliver"; this answers "how
9
+ * much of that rests on a fact nobody wrote down". The two share the
10
+ * attribution gate (`hotspot-sources.ts`) so they cannot disagree about
11
+ * WHICH failures were attributed — but they report different things, and a
12
+ * reader asking "how many of these attributions rested on a type nobody
13
+ * wrote down?" needs this one.
14
+ *
15
+ * WHY THE PROVENANCE IS COUNTED HERE AND NOT IN THE RANKING. The ranking's
16
+ * rows are per ARTIFACT, and one failure fans out into many candidate rows.
17
+ * Counting there would count one failure many times and answer a question
18
+ * nobody asked. This counts failures.
19
+ *
20
+ * WHY A DEFAULTED TYPE IS NOT A MISSING TYPE. An artifact with no usable
21
+ * `- type:` line still has an EFFECTIVE type — the system's default — and
22
+ * that is the type the prerequisite table was indexed by when the transition
23
+ * ran, so the attribution uses it. The attribution is real; only its
24
+ * PROVENANCE is weak. The two facts are reported apart: `fromDeclaredType`
25
+ * and `fromDefaultedType` are separate numbers, and `unresolved` counts the
26
+ * failures whose request artifact could not be read at all — a fact that is
27
+ * NOT the same as "nobody wrote the type down".
28
+ */
29
+ import { attributeFailure, isHistoricalFailure } from './hotspot-sources.js';
30
+ /**
31
+ * The attribution summary of a scope.
32
+ *
33
+ * `requestTypes` is keyed by slice rid and carries each type WITH its
34
+ * provenance, so a failure whose type was defaulted is counted as defaulted
35
+ * rather than being indistinguishable from a declared one.
36
+ */
37
+ export function summarizeAttribution(events, requestTypes, artifacts) {
38
+ let attributed = 0;
39
+ let inferred = 0;
40
+ let ambiguous = 0;
41
+ let fromDeclaredType = 0;
42
+ let fromDefaultedType = 0;
43
+ let unresolved = 0;
44
+ for (const event of events) {
45
+ if (!isHistoricalFailure(event))
46
+ continue;
47
+ const rid = event.sliceRid;
48
+ const reading = rid === undefined ? undefined : requestTypes.get(rid);
49
+ const resolved = attributeFailure(event, reading);
50
+ if (resolved === null) {
51
+ unresolved += 1;
52
+ continue;
53
+ }
54
+ attributed += 1;
55
+ if (resolved.attribution.confidence === 'inferred')
56
+ inferred += 1;
57
+ else
58
+ ambiguous += 1;
59
+ if (resolved.attribution.typeSource === 'declared')
60
+ fromDeclaredType += 1;
61
+ else
62
+ fromDefaultedType += 1;
63
+ }
64
+ return {
65
+ attributed,
66
+ inferred,
67
+ ambiguous,
68
+ fromDeclaredType,
69
+ fromDefaultedType,
70
+ unresolved,
71
+ artifactsUnreadable: artifacts.unreadable,
72
+ artifactsWithoutTypeLine: artifacts.withoutTypeLine
73
+ };
74
+ }
@@ -0,0 +1,47 @@
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 { type HotspotRequestTypes, type HotspotRow } from './hotspot-shared.js';
37
+ import type { ObservabilityEvent } from './observability-service.js';
38
+ /**
39
+ * The hotspot ranking over a set of events.
40
+ *
41
+ * The request types are the DECLARED type of each slice, resolved by the
42
+ * caller from the request artifact: the retro-attribution needs them to
43
+ * re-derive a transition's prerequisite list, and the event stream does
44
+ * not carry them. Without them the historical failures cannot be
45
+ * attributed, and the ranking would silently show only the forward events.
46
+ */
47
+ export declare function aggregateHotspots(events: readonly ObservabilityEvent[], requestTypes?: HotspotRequestTypes): HotspotRow[];
@@ -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 {};