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,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 {};
|