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.
- package/.claude-plugin/marketplace.json +3 -6
- package/CHANGELOG.md +191 -0
- package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
- package/dist/cli/commands/mut-commands-helpers.js +44 -26
- 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/distribution/json-layout.d.ts +20 -0
- package/dist/services/distribution/json-layout.js +195 -0
- package/dist/services/distribution/plugin-manifest.d.ts +31 -2
- package/dist/services/distribution/plugin-manifest.js +40 -4
- 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,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-gate-events.ts`
|
|
3
|
+
*
|
|
4
|
+
* The readers of ONE gate event: which gate it names, at which phase, with
|
|
5
|
+
* which outcome, and which gates were live at that phase.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS IS ITS OWN MODULE. A gate is identified by a gate id and a phase,
|
|
8
|
+
* a prerequisite by a transition key — different vocabularies, so the readers
|
|
9
|
+
* of one sit beside the readers of the other. What lives HERE is the reading
|
|
10
|
+
* of a single event; what lives in `near-miss-gates.ts` is the accumulation
|
|
11
|
+
* of many readings into the facts the metric reads.
|
|
12
|
+
*
|
|
13
|
+
* WHY THE LIVE SET IS REPRODUCED FROM THE EVENT AND NOT FROM THE ARTIFACT.
|
|
14
|
+
* `peaks request retag` rewrites the `- type:` line with no state guard, so
|
|
15
|
+
* the artifact on disk carries the CURRENT type, not the type the transition
|
|
16
|
+
* ran under. The gate event carries the type the transition judged, so the
|
|
17
|
+
* live set is reproduced from the event stream alone.
|
|
18
|
+
*
|
|
19
|
+
* WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
|
|
20
|
+
* (written before the type was carried) exist on this branch without the
|
|
21
|
+
* field. A `claim-table` event at the same phase in the same slice proves
|
|
22
|
+
* the slice was tooling-only at that phase — the claim table only runs for
|
|
23
|
+
* tooling-only slices — and its absence proves it was not. When even that
|
|
24
|
+
* leaves the liveness undetermined (no usable phase), the gate is reported
|
|
25
|
+
* rather than guessed at.
|
|
26
|
+
*/
|
|
27
|
+
import { type RequestType } from '../artifacts/artifact-prerequisites.js';
|
|
28
|
+
import { type RdGateId } from '../artifacts/rd-gate-event.js';
|
|
29
|
+
import type { RdGatePhase } from '../artifacts/rd-transition-gates.js';
|
|
30
|
+
import type { ObservabilityEvent } from './observability-service.js';
|
|
31
|
+
/** The gate that only a tooling-only slice runs. */
|
|
32
|
+
export declare const CLAIM_TABLE_GATE: RdGateId;
|
|
33
|
+
/**
|
|
34
|
+
* The gate ids this metric knows how to judge.
|
|
35
|
+
*
|
|
36
|
+
* READ FROM THE CANONICAL LIST, not re-typed here: a second copy of the
|
|
37
|
+
* vocabulary is a list that rots, and it rots SILENTLY — a gate id added
|
|
38
|
+
* upstream would not be in the copy, so `gateIdOf` would answer null for it
|
|
39
|
+
* and a gate that PASSED would never be counted as evaluated, reading as
|
|
40
|
+
* "never evaluated" — a false near-miss.
|
|
41
|
+
*/
|
|
42
|
+
export declare const KNOWN_GATE_IDS: readonly RdGateId[];
|
|
43
|
+
/** The gate id an event's own detail names, or null when it names none we know. */
|
|
44
|
+
export declare function gateIdOf(event: ObservabilityEvent): RdGateId | null;
|
|
45
|
+
/**
|
|
46
|
+
* The phase a gate event was recorded at, or null when it carries none.
|
|
47
|
+
*
|
|
48
|
+
* TYPED BY THE GATE LAYER'S OWN UNION, not by a second copy of it: the copy
|
|
49
|
+
* would be a list that rots, and it rots silently — a phase added upstream
|
|
50
|
+
* would not be in the copy, so a gate that PASSED at that phase would be read
|
|
51
|
+
* as carrying no usable phase, and the slice would be reported as
|
|
52
|
+
* undetermined instead of evaluated.
|
|
53
|
+
*/
|
|
54
|
+
export declare function phaseOf(event: ObservabilityEvent): RdGatePhase | null;
|
|
55
|
+
/** The declared type a gate event carries, or null when it carries none usable. */
|
|
56
|
+
export declare function declaredTypeOf(event: ObservabilityEvent): RequestType | null;
|
|
57
|
+
/** The outcome a gate event carries. */
|
|
58
|
+
export declare function outcomeOf(event: ObservabilityEvent): string;
|
|
59
|
+
/**
|
|
60
|
+
* Whether the slice was tooling-only at a phase, judged from the stream.
|
|
61
|
+
*
|
|
62
|
+
* The claim table only runs for tooling-only slices, so a claim-table event
|
|
63
|
+
* at this phase in this slice proves the slice was tooling-only here, and its
|
|
64
|
+
* absence proves it was not. This is the fallback for gate events written
|
|
65
|
+
* before the declared type was carried.
|
|
66
|
+
*/
|
|
67
|
+
export declare function toolingOnlyAtPhase(phase: RdGatePhase, gateEvents: readonly ObservabilityEvent[]): boolean;
|
|
68
|
+
/**
|
|
69
|
+
* The live gate set of one gate event's transition, or null when it cannot
|
|
70
|
+
* be reproduced.
|
|
71
|
+
*
|
|
72
|
+
* `null` means the liveness is undetermined — the event carries no usable
|
|
73
|
+
* phase — and the caller reports it rather than guessing.
|
|
74
|
+
*/
|
|
75
|
+
export declare function liveGatesOf(event: ObservabilityEvent, gateEvents: readonly ObservabilityEvent[]): readonly RdGateId[] | null;
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-gate-events.ts`
|
|
3
|
+
*
|
|
4
|
+
* The readers of ONE gate event: which gate it names, at which phase, with
|
|
5
|
+
* which outcome, and which gates were live at that phase.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS IS ITS OWN MODULE. A gate is identified by a gate id and a phase,
|
|
8
|
+
* a prerequisite by a transition key — different vocabularies, so the readers
|
|
9
|
+
* of one sit beside the readers of the other. What lives HERE is the reading
|
|
10
|
+
* of a single event; what lives in `near-miss-gates.ts` is the accumulation
|
|
11
|
+
* of many readings into the facts the metric reads.
|
|
12
|
+
*
|
|
13
|
+
* WHY THE LIVE SET IS REPRODUCED FROM THE EVENT AND NOT FROM THE ARTIFACT.
|
|
14
|
+
* `peaks request retag` rewrites the `- type:` line with no state guard, so
|
|
15
|
+
* the artifact on disk carries the CURRENT type, not the type the transition
|
|
16
|
+
* ran under. The gate event carries the type the transition judged, so the
|
|
17
|
+
* live set is reproduced from the event stream alone.
|
|
18
|
+
*
|
|
19
|
+
* WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
|
|
20
|
+
* (written before the type was carried) exist on this branch without the
|
|
21
|
+
* field. A `claim-table` event at the same phase in the same slice proves
|
|
22
|
+
* the slice was tooling-only at that phase — the claim table only runs for
|
|
23
|
+
* tooling-only slices — and its absence proves it was not. When even that
|
|
24
|
+
* leaves the liveness undetermined (no usable phase), the gate is reported
|
|
25
|
+
* rather than guessed at.
|
|
26
|
+
*/
|
|
27
|
+
import { isRequestType } from '../artifacts/artifact-prerequisites.js';
|
|
28
|
+
import { liveGateIds, RD_GATE_IDS } from '../artifacts/rd-gate-event.js';
|
|
29
|
+
import { isToolingOnlyDeclaredType } from '../scan/type-corroboration.js';
|
|
30
|
+
/** The gate that only a tooling-only slice runs. */
|
|
31
|
+
export const CLAIM_TABLE_GATE = 'claim-table';
|
|
32
|
+
/**
|
|
33
|
+
* The gate ids this metric knows how to judge.
|
|
34
|
+
*
|
|
35
|
+
* READ FROM THE CANONICAL LIST, not re-typed here: a second copy of the
|
|
36
|
+
* vocabulary is a list that rots, and it rots SILENTLY — a gate id added
|
|
37
|
+
* upstream would not be in the copy, so `gateIdOf` would answer null for it
|
|
38
|
+
* and a gate that PASSED would never be counted as evaluated, reading as
|
|
39
|
+
* "never evaluated" — a false near-miss.
|
|
40
|
+
*/
|
|
41
|
+
export const KNOWN_GATE_IDS = RD_GATE_IDS;
|
|
42
|
+
/** The gate id an event's own detail names, or null when it names none we know. */
|
|
43
|
+
export function gateIdOf(event) {
|
|
44
|
+
const detail = event.detail;
|
|
45
|
+
const gateId = detail.gateId;
|
|
46
|
+
if (typeof gateId !== 'string')
|
|
47
|
+
return null;
|
|
48
|
+
return KNOWN_GATE_IDS.find((known) => known === gateId) ?? null;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* The phase a gate event was recorded at, or null when it carries none.
|
|
52
|
+
*
|
|
53
|
+
* TYPED BY THE GATE LAYER'S OWN UNION, not by a second copy of it: the copy
|
|
54
|
+
* would be a list that rots, and it rots silently — a phase added upstream
|
|
55
|
+
* would not be in the copy, so a gate that PASSED at that phase would be read
|
|
56
|
+
* as carrying no usable phase, and the slice would be reported as
|
|
57
|
+
* undetermined instead of evaluated.
|
|
58
|
+
*/
|
|
59
|
+
export function phaseOf(event) {
|
|
60
|
+
const detail = event.detail;
|
|
61
|
+
const phase = detail.phase;
|
|
62
|
+
if (phase === 'implemented' || phase === 'qa-handoff' || phase === 'handed-off')
|
|
63
|
+
return phase;
|
|
64
|
+
return null;
|
|
65
|
+
}
|
|
66
|
+
/** The declared type a gate event carries, or null when it carries none usable. */
|
|
67
|
+
export function declaredTypeOf(event) {
|
|
68
|
+
const detail = event.detail;
|
|
69
|
+
const declaredType = detail.declaredType;
|
|
70
|
+
if (typeof declaredType !== 'string' || !isRequestType(declaredType))
|
|
71
|
+
return null;
|
|
72
|
+
return declaredType;
|
|
73
|
+
}
|
|
74
|
+
/** The outcome a gate event carries. */
|
|
75
|
+
export function outcomeOf(event) {
|
|
76
|
+
const detail = event.detail;
|
|
77
|
+
return typeof detail.outcome === 'string' ? detail.outcome : '';
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Whether the slice was tooling-only at a phase, judged from the stream.
|
|
81
|
+
*
|
|
82
|
+
* The claim table only runs for tooling-only slices, so a claim-table event
|
|
83
|
+
* at this phase in this slice proves the slice was tooling-only here, and its
|
|
84
|
+
* absence proves it was not. This is the fallback for gate events written
|
|
85
|
+
* before the declared type was carried.
|
|
86
|
+
*/
|
|
87
|
+
export function toolingOnlyAtPhase(phase, gateEvents) {
|
|
88
|
+
return gateEvents.some((event) => phaseOf(event) === phase && gateIdOf(event) === CLAIM_TABLE_GATE);
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* The live gate set of one gate event's transition, or null when it cannot
|
|
92
|
+
* be reproduced.
|
|
93
|
+
*
|
|
94
|
+
* `null` means the liveness is undetermined — the event carries no usable
|
|
95
|
+
* phase — and the caller reports it rather than guessing.
|
|
96
|
+
*/
|
|
97
|
+
export function liveGatesOf(event, gateEvents) {
|
|
98
|
+
const phase = phaseOf(event);
|
|
99
|
+
if (phase === null)
|
|
100
|
+
return null;
|
|
101
|
+
const declaredType = declaredTypeOf(event);
|
|
102
|
+
const judged = declaredType === null
|
|
103
|
+
? toolingOnlyAtPhase(phase, gateEvents)
|
|
104
|
+
: isToolingOnlyDeclaredType(declaredType);
|
|
105
|
+
return liveGateIds(phase, judged);
|
|
106
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-gates.ts`
|
|
3
|
+
*
|
|
4
|
+
* The GATE facts the near-miss metric is computed from: which gates were
|
|
5
|
+
* live, which of them were evaluated, which of them recorded a verdict this
|
|
6
|
+
* build cannot read, and the liveness of the ones the stream did not decide.
|
|
7
|
+
*
|
|
8
|
+
* WHY THIS IS ITS OWN MODULE. The near-miss metric reads the gate side of
|
|
9
|
+
* the stream and the prerequisite side of the stream, and the two have
|
|
10
|
+
* different vocabularies: a gate is identified by a gate id and a phase, a
|
|
11
|
+
* prerequisite by a transition key. Keeping the readers of one beside the
|
|
12
|
+
* readers of the other is what lets the metric itself stay a metric. The
|
|
13
|
+
* readers of a single gate event live in `near-miss-gate-events.ts`; what
|
|
14
|
+
* lives here is the accumulation of many readings into the facts.
|
|
15
|
+
*
|
|
16
|
+
* WHY THE READERS OF ONE EVENT ARE BESIDE THE READERS OF MANY. The scope of
|
|
17
|
+
* an unreadable verdict depends on what the WHOLE slice's gate events say —
|
|
18
|
+
* an event this build cannot attribute may have been the verdict of a gate
|
|
19
|
+
* that recorded nothing of its own, and of no other. So the decision of what
|
|
20
|
+
* is unreadable cannot be made by one event alone, and the facts it reads
|
|
21
|
+
* have to be accumulated before it is answered.
|
|
22
|
+
*/
|
|
23
|
+
import { type RdGateId } from '../artifacts/rd-gate-event.js';
|
|
24
|
+
import type { ObservabilityEvent } from './observability-service.js';
|
|
25
|
+
/** A gate whose liveness could not be decided from the event stream. */
|
|
26
|
+
export type NearMissUndetermined = {
|
|
27
|
+
readonly sliceRid: string;
|
|
28
|
+
readonly sessionId: string;
|
|
29
|
+
readonly ts: string;
|
|
30
|
+
readonly gateId: string;
|
|
31
|
+
/**
|
|
32
|
+
* WHAT could not be decided — the liveness of the gate, or its verdict.
|
|
33
|
+
*
|
|
34
|
+
* The two are different questions, and a count that says only "undetermined"
|
|
35
|
+
* cannot say which one it counted.
|
|
36
|
+
*/
|
|
37
|
+
readonly kind: 'liveness' | 'verdict';
|
|
38
|
+
/** What left the question open. */
|
|
39
|
+
readonly reason: string;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* The gate facts one slice's events carry, accumulated as the stream is walked.
|
|
43
|
+
*
|
|
44
|
+
* MUTABLE on purpose: this is the accumulator the reader folds events into,
|
|
45
|
+
* and the metric reads the finished set. The public surface exposes them
|
|
46
|
+
* read-only.
|
|
47
|
+
*/
|
|
48
|
+
export type GateFacts = {
|
|
49
|
+
/** The gate ids that were live at some transition of this slice. */
|
|
50
|
+
readonly liveGates: Set<RdGateId>;
|
|
51
|
+
/** The gate ids that got a `pass` or a `block` — i.e. WERE evaluated. */
|
|
52
|
+
readonly evaluatedGates: Set<RdGateId>;
|
|
53
|
+
/**
|
|
54
|
+
* The gate ids some event NAMED, whatever verdict that event carried.
|
|
55
|
+
*
|
|
56
|
+
* A gate that has an event of its own carries its own verdict, and the
|
|
57
|
+
* verdict of one gate says nothing about another — that is what keeps an
|
|
58
|
+
* event about a gate this build does not know from masking a gate that
|
|
59
|
+
* was bypassed.
|
|
60
|
+
*/
|
|
61
|
+
readonly namedGates: Set<RdGateId>;
|
|
62
|
+
/**
|
|
63
|
+
* The live gates an event naming a gate this build does not know MIGHT
|
|
64
|
+
* have been about.
|
|
65
|
+
*
|
|
66
|
+
* Such an event cannot be attributed to a gate, so it may be the verdict
|
|
67
|
+
* of any gate that was live at its phase and recorded no verdict of its
|
|
68
|
+
* own. The scope is settled by `unreadableGateIds`, once every event of
|
|
69
|
+
* the slice has been read.
|
|
70
|
+
*/
|
|
71
|
+
readonly unattributedGates: Set<RdGateId>;
|
|
72
|
+
/**
|
|
73
|
+
* The gate ids whose own VERDICT could not be read.
|
|
74
|
+
*
|
|
75
|
+
* An unreadable verdict is not an absent one: a gate whose own event
|
|
76
|
+
* names an outcome this build does not know was not shown to have been
|
|
77
|
+
* skipped — it was shown to be unreadable. Those gates are excluded from
|
|
78
|
+
* the never-evaluated finding, and reported as undetermined instead.
|
|
79
|
+
*/
|
|
80
|
+
readonly unreadableGates: Set<RdGateId>;
|
|
81
|
+
/** The gates whose liveness the stream did not decide. */
|
|
82
|
+
readonly undetermined: NearMissUndetermined[];
|
|
83
|
+
};
|
|
84
|
+
/**
|
|
85
|
+
* The gates whose verdict this build cannot read.
|
|
86
|
+
*
|
|
87
|
+
* An event that names a KNOWN gate and an outcome this build does not know
|
|
88
|
+
* leaves exactly that gate unreadable. An event that names a gate this build
|
|
89
|
+
* does not know leaves UNATTRIBUTED: it may have been the verdict of any gate
|
|
90
|
+
* that was live at its phase and recorded no verdict of its own — and of no
|
|
91
|
+
* other, because a gate that recorded a verdict of its own carries that
|
|
92
|
+
* verdict, and one gate's verdict says nothing about another's.
|
|
93
|
+
*/
|
|
94
|
+
export declare function unreadableGateIds(facts: GateFacts): ReadonlySet<RdGateId>;
|
|
95
|
+
/**
|
|
96
|
+
* Fold one gate event into the gate facts.
|
|
97
|
+
*
|
|
98
|
+
* A VERDICT THIS BUILD CANNOT READ IS NOT A FINDING. The event schema keeps
|
|
99
|
+
* `detail` loose, so an event can carry an outcome this build does not know
|
|
100
|
+
* (`'PASS'`) or name a gate id this build does not know. Neither is a gate
|
|
101
|
+
* that was skipped: both are events whose verdict cannot be read. Reading them
|
|
102
|
+
* as "never evaluated" would report a slice that evaluated every gate as one
|
|
103
|
+
* that skipped one — a false near-miss at a rate of 100%.
|
|
104
|
+
*/
|
|
105
|
+
export declare function readGate(facts: GateFacts, event: ObservabilityEvent, sliceRid: string, gateEvents: readonly ObservabilityEvent[]): void;
|
|
106
|
+
export { gateIdOf, liveGatesOf, phaseOf } from './near-miss-gate-events.js';
|
|
107
|
+
export { CLAIM_TABLE_GATE, KNOWN_GATE_IDS } from './near-miss-gate-events.js';
|
|
108
|
+
export { declaredTypeOf, outcomeOf, toolingOnlyAtPhase } from './near-miss-gate-events.js';
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-gates.ts`
|
|
3
|
+
*
|
|
4
|
+
* The GATE facts the near-miss metric is computed from: which gates were
|
|
5
|
+
* live, which of them were evaluated, which of them recorded a verdict this
|
|
6
|
+
* build cannot read, and the liveness of the ones the stream did not decide.
|
|
7
|
+
*
|
|
8
|
+
* WHY THIS IS ITS OWN MODULE. The near-miss metric reads the gate side of
|
|
9
|
+
* the stream and the prerequisite side of the stream, and the two have
|
|
10
|
+
* different vocabularies: a gate is identified by a gate id and a phase, a
|
|
11
|
+
* prerequisite by a transition key. Keeping the readers of one beside the
|
|
12
|
+
* readers of the other is what lets the metric itself stay a metric. The
|
|
13
|
+
* readers of a single gate event live in `near-miss-gate-events.ts`; what
|
|
14
|
+
* lives here is the accumulation of many readings into the facts.
|
|
15
|
+
*
|
|
16
|
+
* WHY THE READERS OF ONE EVENT ARE BESIDE THE READERS OF MANY. The scope of
|
|
17
|
+
* an unreadable verdict depends on what the WHOLE slice's gate events say —
|
|
18
|
+
* an event this build cannot attribute may have been the verdict of a gate
|
|
19
|
+
* that recorded nothing of its own, and of no other. So the decision of what
|
|
20
|
+
* is unreadable cannot be made by one event alone, and the facts it reads
|
|
21
|
+
* have to be accumulated before it is answered.
|
|
22
|
+
*/
|
|
23
|
+
import { isRdGateOutcome } from '../artifacts/rd-gate-event.js';
|
|
24
|
+
import { gateIdOf, liveGatesOf, outcomeOf } from './near-miss-gate-events.js';
|
|
25
|
+
/**
|
|
26
|
+
* The gates whose verdict this build cannot read.
|
|
27
|
+
*
|
|
28
|
+
* An event that names a KNOWN gate and an outcome this build does not know
|
|
29
|
+
* leaves exactly that gate unreadable. An event that names a gate this build
|
|
30
|
+
* does not know leaves UNATTRIBUTED: it may have been the verdict of any gate
|
|
31
|
+
* that was live at its phase and recorded no verdict of its own — and of no
|
|
32
|
+
* other, because a gate that recorded a verdict of its own carries that
|
|
33
|
+
* verdict, and one gate's verdict says nothing about another's.
|
|
34
|
+
*/
|
|
35
|
+
export function unreadableGateIds(facts) {
|
|
36
|
+
const unreadable = new Set(facts.unreadableGates);
|
|
37
|
+
for (const gate of facts.unattributedGates) {
|
|
38
|
+
if (!facts.namedGates.has(gate))
|
|
39
|
+
unreadable.add(gate);
|
|
40
|
+
}
|
|
41
|
+
return unreadable;
|
|
42
|
+
}
|
|
43
|
+
/** The gate id an event names, spelled out even when this build knows none. */
|
|
44
|
+
function rawGateIdOf(event) {
|
|
45
|
+
const detail = event.detail;
|
|
46
|
+
return typeof detail.gateId === 'string' ? detail.gateId : '';
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Fold one gate event into the gate facts.
|
|
50
|
+
*
|
|
51
|
+
* A VERDICT THIS BUILD CANNOT READ IS NOT A FINDING. The event schema keeps
|
|
52
|
+
* `detail` loose, so an event can carry an outcome this build does not know
|
|
53
|
+
* (`'PASS'`) or name a gate id this build does not know. Neither is a gate
|
|
54
|
+
* that was skipped: both are events whose verdict cannot be read. Reading them
|
|
55
|
+
* as "never evaluated" would report a slice that evaluated every gate as one
|
|
56
|
+
* that skipped one — a false near-miss at a rate of 100%.
|
|
57
|
+
*/
|
|
58
|
+
export function readGate(facts, event, sliceRid, gateEvents) {
|
|
59
|
+
const gateId = gateIdOf(event);
|
|
60
|
+
const outcome = outcomeOf(event);
|
|
61
|
+
const outcomeKnown = isRdGateOutcome(outcome);
|
|
62
|
+
if (gateId !== null) {
|
|
63
|
+
// The event NAMES this gate, so this gate's verdict is carried here.
|
|
64
|
+
facts.namedGates.add(gateId);
|
|
65
|
+
if (outcomeKnown && (outcome === 'pass' || outcome === 'block')) {
|
|
66
|
+
facts.evaluatedGates.add(gateId);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
const live = liveGatesOf(event, gateEvents);
|
|
70
|
+
if (live === null) {
|
|
71
|
+
if (gateId !== null) {
|
|
72
|
+
facts.undetermined.push({
|
|
73
|
+
sliceRid,
|
|
74
|
+
sessionId: event.sessionId,
|
|
75
|
+
ts: event.ts,
|
|
76
|
+
gateId,
|
|
77
|
+
kind: 'liveness',
|
|
78
|
+
reason: 'the gate event carries no usable phase, so the live set cannot be reproduced'
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
for (const gate of live)
|
|
84
|
+
facts.liveGates.add(gate);
|
|
85
|
+
readVerdict({ facts, event, sliceRid, gateId, outcomeKnown, live });
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Read the VERDICT an event carries, when it carries one this build can read.
|
|
89
|
+
*
|
|
90
|
+
* A verdict that CAN be read is already accounted for: a `pass` or a `block`
|
|
91
|
+
* was counted as evaluated, and a `bypass` is the skip the metric reports.
|
|
92
|
+
* What is left here is the verdict this build could NOT read — an outcome
|
|
93
|
+
* outside the vocabulary, or a gate id outside it. Neither is a gate that was
|
|
94
|
+
* skipped, so the event is reported as undetermined.
|
|
95
|
+
*
|
|
96
|
+
* THE SCOPE OF AN UNREADABLE VERDICT IS THE GATE IT NAMES. An event that
|
|
97
|
+
* names a known gate and an outcome this build does not know leaves exactly
|
|
98
|
+
* that gate unreadable. An event that names a gate this build does not know
|
|
99
|
+
* leaves UNATTRIBUTED: it may have been the verdict of any gate that was live
|
|
100
|
+
* at its phase and recorded no verdict of its own — and of no other, because
|
|
101
|
+
* a gate that recorded a verdict of its own carries that verdict, and one
|
|
102
|
+
* gate's verdict says nothing about another's.
|
|
103
|
+
*/
|
|
104
|
+
function readVerdict(reading) {
|
|
105
|
+
const { facts, event, sliceRid, gateId, outcomeKnown, live } = reading;
|
|
106
|
+
if (gateId !== null && outcomeKnown)
|
|
107
|
+
return;
|
|
108
|
+
if (gateId === null) {
|
|
109
|
+
for (const gate of live)
|
|
110
|
+
facts.unattributedGates.add(gate);
|
|
111
|
+
facts.undetermined.push({
|
|
112
|
+
sliceRid,
|
|
113
|
+
sessionId: event.sessionId,
|
|
114
|
+
ts: event.ts,
|
|
115
|
+
gateId: rawGateIdOf(event),
|
|
116
|
+
kind: 'verdict',
|
|
117
|
+
reason: 'the gate event names a gate id this build does not know, so its verdict could not be ' +
|
|
118
|
+
'attributed to a gate'
|
|
119
|
+
});
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
facts.unreadableGates.add(gateId);
|
|
123
|
+
facts.undetermined.push({
|
|
124
|
+
sliceRid,
|
|
125
|
+
sessionId: event.sessionId,
|
|
126
|
+
ts: event.ts,
|
|
127
|
+
gateId,
|
|
128
|
+
kind: 'verdict',
|
|
129
|
+
reason: 'the gate event carries an outcome this build does not know, so the gate verdict could ' +
|
|
130
|
+
'not be read'
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
export { gateIdOf, liveGatesOf, phaseOf } from './near-miss-gate-events.js';
|
|
134
|
+
export { CLAIM_TABLE_GATE, KNOWN_GATE_IDS } from './near-miss-gate-events.js';
|
|
135
|
+
export { declaredTypeOf, outcomeOf, toolingOnlyAtPhase } from './near-miss-gate-events.js';
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-records.ts`
|
|
3
|
+
*
|
|
4
|
+
* The FINDINGS one slice carries: which gates were live and never evaluated,
|
|
5
|
+
* which required checks were still unsatisfied when the slice passed, and the
|
|
6
|
+
* events a reader can check those claims against.
|
|
7
|
+
*
|
|
8
|
+
* WHY THIS IS ITS OWN MODULE. The metric itself reads the stream and counts;
|
|
9
|
+
* the shape of a finding is a different question, and `near-miss.ts` was at
|
|
10
|
+
* its file-size cap with both in it. The evidence pointers in particular are
|
|
11
|
+
* the part a reader USES rather than the part the metric computes, so they
|
|
12
|
+
* travel with the record they belong to.
|
|
13
|
+
*/
|
|
14
|
+
import type { UnreadableVerdict } from './near-miss-attempts.js';
|
|
15
|
+
import type { RdGateId } from '../artifacts/rd-gate-event.js';
|
|
16
|
+
import type { ObservabilityEvent } from './observability-service.js';
|
|
17
|
+
import type { NearMissEvidence, NearMissReason, SliceFacts, UnsatisfiedKey } from './near-miss-facts.js';
|
|
18
|
+
/** One slice that passed with a check skipped. */
|
|
19
|
+
export type NearMissRecord = {
|
|
20
|
+
readonly sliceRid: string;
|
|
21
|
+
readonly reasons: readonly NearMissReason[];
|
|
22
|
+
/**
|
|
23
|
+
* The moment the slice was declared passing.
|
|
24
|
+
*
|
|
25
|
+
* It travels WITH the record because it is what makes the finding
|
|
26
|
+
* actionable: a reader cannot tell from the key alone whether the check was
|
|
27
|
+
* REFUSING at that moment or had not been ATTEMPTED yet. On this
|
|
28
|
+
* repository's recorded history one of the twelve findings is the first and
|
|
29
|
+
* eleven are the second.
|
|
30
|
+
*/
|
|
31
|
+
readonly passMoment: {
|
|
32
|
+
/** The instant of the successful verdict attempt. */
|
|
33
|
+
readonly ts: string;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* The transition keys whose check was unsatisfied at the pass moment, each
|
|
37
|
+
* with its state there.
|
|
38
|
+
*/
|
|
39
|
+
readonly unsatisfiedKeys: readonly UnsatisfiedKey[];
|
|
40
|
+
readonly evidence: readonly NearMissEvidence[];
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* A slice whose PASS verdict this build could not READ.
|
|
44
|
+
*
|
|
45
|
+
* It is neither a pass nor a non-pass: the record says a verdict was issued
|
|
46
|
+
* and the value cannot be read, so whether the slice passed is unknown. It is
|
|
47
|
+
* in neither the numerator nor the denominator, and it is listed rather than
|
|
48
|
+
* dropped — a slice that vanishes from the accounting reads as "no passing
|
|
49
|
+
* slices", which is an absence read as a result.
|
|
50
|
+
*/
|
|
51
|
+
export type NearMissUnmeasured = {
|
|
52
|
+
readonly sliceRid: string;
|
|
53
|
+
readonly sessionId: string;
|
|
54
|
+
readonly ts: string;
|
|
55
|
+
/** What left the question open. */
|
|
56
|
+
readonly reason: string;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Why a slice's pass verdict could not be read, in a sentence a reader can
|
|
60
|
+
* act on.
|
|
61
|
+
*
|
|
62
|
+
* The recorded value is NAMED rather than summarised: a reader told only
|
|
63
|
+
* "the verdict was unreadable" has to open the record to learn what it
|
|
64
|
+
* actually said, and `"true"` read as a boolean is exactly the reading this
|
|
65
|
+
* build must not make.
|
|
66
|
+
*
|
|
67
|
+
* `hasPassMoment` says whether a later readable attempt established the pass.
|
|
68
|
+
* When it did, the open question is WHICH attempt was the reference moment;
|
|
69
|
+
* when it did not, the open question is whether the slice passed at all.
|
|
70
|
+
*/
|
|
71
|
+
export declare function unmeasuredReason(unreadable: UnreadableVerdict, hasPassMoment: boolean): string;
|
|
72
|
+
/**
|
|
73
|
+
* The evidence a near-miss record carries.
|
|
74
|
+
*
|
|
75
|
+
* For a gate that was live and never evaluated, the evidence is the events
|
|
76
|
+
* that let a reader CHECK that claim: the events about that gate (a bypass
|
|
77
|
+
* is the primary one) and the sibling gate events of the same transition,
|
|
78
|
+
* which are what establish the live set. For an unsatisfied prerequisite, it
|
|
79
|
+
* is the refusal itself, named by the transition key it refused.
|
|
80
|
+
*/
|
|
81
|
+
export declare function evidenceFor(neverEvaluated: readonly RdGateId[], gateEvents: readonly ObservabilityEvent[], unsatisfied: NonNullable<SliceFacts['passMoment']>): readonly NearMissEvidence[];
|
|
82
|
+
/**
|
|
83
|
+
* The reasons one passing slice carries.
|
|
84
|
+
*
|
|
85
|
+
* A prerequisite key counts when its check was STILL UNSATISFIED at the pass
|
|
86
|
+
* moment: the slice was declared passing while a required check had not been
|
|
87
|
+
* satisfied. A check that refused and was then satisfied before the pass is
|
|
88
|
+
* a gate working as designed, and it is not a near-miss.
|
|
89
|
+
*/
|
|
90
|
+
export declare function reasonsFor(fact: SliceFacts): {
|
|
91
|
+
readonly reasons: NearMissReason[];
|
|
92
|
+
readonly neverEvaluated: readonly RdGateId[];
|
|
93
|
+
};
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/near-miss-records.ts`
|
|
3
|
+
*
|
|
4
|
+
* The FINDINGS one slice carries: which gates were live and never evaluated,
|
|
5
|
+
* which required checks were still unsatisfied when the slice passed, and the
|
|
6
|
+
* events a reader can check those claims against.
|
|
7
|
+
*
|
|
8
|
+
* WHY THIS IS ITS OWN MODULE. The metric itself reads the stream and counts;
|
|
9
|
+
* the shape of a finding is a different question, and `near-miss.ts` was at
|
|
10
|
+
* its file-size cap with both in it. The evidence pointers in particular are
|
|
11
|
+
* the part a reader USES rather than the part the metric computes, so they
|
|
12
|
+
* travel with the record they belong to.
|
|
13
|
+
*/
|
|
14
|
+
import { gateIdOf, liveGatesOf } from './near-miss-gate-events.js';
|
|
15
|
+
/**
|
|
16
|
+
* Why a slice's pass verdict could not be read, in a sentence a reader can
|
|
17
|
+
* act on.
|
|
18
|
+
*
|
|
19
|
+
* The recorded value is NAMED rather than summarised: a reader told only
|
|
20
|
+
* "the verdict was unreadable" has to open the record to learn what it
|
|
21
|
+
* actually said, and `"true"` read as a boolean is exactly the reading this
|
|
22
|
+
* build must not make.
|
|
23
|
+
*
|
|
24
|
+
* `hasPassMoment` says whether a later readable attempt established the pass.
|
|
25
|
+
* When it did, the open question is WHICH attempt was the reference moment;
|
|
26
|
+
* when it did not, the open question is whether the slice passed at all.
|
|
27
|
+
*/
|
|
28
|
+
export function unmeasuredReason(unreadable, hasPassMoment) {
|
|
29
|
+
const consequence = hasPassMoment
|
|
30
|
+
? "so which attempt was the slice's pass moment could not be read"
|
|
31
|
+
: 'so whether the slice passed could not be read';
|
|
32
|
+
return (`the \`${unreadable.key}\` attempt records \`prereqOk\` as ${unreadable.value}, which is not a ` +
|
|
33
|
+
`boolean, ${consequence}`);
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The evidence a near-miss record carries.
|
|
37
|
+
*
|
|
38
|
+
* For a gate that was live and never evaluated, the evidence is the events
|
|
39
|
+
* that let a reader CHECK that claim: the events about that gate (a bypass
|
|
40
|
+
* is the primary one) and the sibling gate events of the same transition,
|
|
41
|
+
* which are what establish the live set. For an unsatisfied prerequisite, it
|
|
42
|
+
* is the refusal itself, named by the transition key it refused.
|
|
43
|
+
*/
|
|
44
|
+
export function evidenceFor(neverEvaluated, gateEvents, unsatisfied) {
|
|
45
|
+
const pointers = [];
|
|
46
|
+
for (const gateId of neverEvaluated) {
|
|
47
|
+
for (const event of gateEvents) {
|
|
48
|
+
const own = gateIdOf(event);
|
|
49
|
+
const live = liveGatesOf(event, gateEvents);
|
|
50
|
+
const witnessed = live !== null && live.includes(gateId);
|
|
51
|
+
if (own !== gateId && !witnessed)
|
|
52
|
+
continue;
|
|
53
|
+
pointers.push({
|
|
54
|
+
sessionId: event.sessionId,
|
|
55
|
+
ts: event.ts,
|
|
56
|
+
...(own !== null ? { gateId: own } : {})
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
for (const failure of unsatisfied.failures) {
|
|
61
|
+
pointers.push({
|
|
62
|
+
sessionId: failure.sessionId,
|
|
63
|
+
ts: failure.ts,
|
|
64
|
+
transitionKey: failure.key
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
return pointers;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* The reasons one passing slice carries.
|
|
71
|
+
*
|
|
72
|
+
* A prerequisite key counts when its check was STILL UNSATISFIED at the pass
|
|
73
|
+
* moment: the slice was declared passing while a required check had not been
|
|
74
|
+
* satisfied. A check that refused and was then satisfied before the pass is
|
|
75
|
+
* a gate working as designed, and it is not a near-miss.
|
|
76
|
+
*/
|
|
77
|
+
export function reasonsFor(fact) {
|
|
78
|
+
const neverEvaluated = [...fact.liveGates].filter((gateId) => !fact.evaluatedGates.has(gateId) && !fact.unreadableGates.has(gateId));
|
|
79
|
+
const reasons = [];
|
|
80
|
+
if (neverEvaluated.length > 0)
|
|
81
|
+
reasons.push('gate-never-evaluated');
|
|
82
|
+
if ((fact.passMoment?.unsatisfiedKeys.length ?? 0) > 0)
|
|
83
|
+
reasons.push('prereq-skipped');
|
|
84
|
+
if (fact.toolBlocked)
|
|
85
|
+
reasons.push('tool-blocked');
|
|
86
|
+
return { reasons, neverEvaluated };
|
|
87
|
+
}
|