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,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
+ }
@@ -0,0 +1,148 @@
1
+ /**
2
+ * `src/services/observability/near-miss.ts`
3
+ *
4
+ * The near-miss rate: of the slices that were declared PASSING, how many
5
+ * passed anyway after a required check was still unsatisfied?
6
+ *
7
+ * WHY THIS EXISTS. The premise of the whole programme is that "the QA verdict
8
+ * says pass" is a metric that is blind: it cannot see a pass that was bought
9
+ * by skipping a check. This module is the number that can see it. The spec
10
+ * (§2.3 S2.3) names it the headline output of the project, and the review
11
+ * focus of Task 5 is the distinction between "gate skipped and never
12
+ * evaluated" and "gate evaluated and passed" — the latter is normal flow, and
13
+ * misreading it as the former would inflate the metric past meaning.
14
+ *
15
+ * THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question this metric asks
16
+ * is "at the moment the slice was declared passing, had the required check
17
+ * been satisfied?" — so the reference is the PASS, not the first
18
+ * `verdict-issued` event and not the last attempt at a key. A `verdict-issued`
19
+ * attempt whose prereq check FAILED is not a pass at all; it is a refused
20
+ * transition recorded under the same `to` state. The pass moment is therefore
21
+ * the first `verdict-issued` attempt whose prereq check SUCCEEDED.
22
+ *
23
+ * A slice with no pass moment was never declared passing, so it is in
24
+ * neither the numerator nor the denominator: there is no pass to have been
25
+ * bought by skipping a check. The EXCEPTION is a slice whose pass moment
26
+ * exists but could not be READ — a `verdict-issued` attempt whose prereq
27
+ * verdict is recorded in a shape this build cannot read. Whether such a slice
28
+ * passed is unknown, so it is reported as UNMEASURED rather than dropped: a
29
+ * slice that vanishes from the accounting reads as "no passing slices", which
30
+ * is an absence read as a result.
31
+ *
32
+ * THE LIVE SET IS A UNION OVER THE SLICE'S WHOLE HISTORY. A gate is "live"
33
+ * for a transition when it WOULD have run had the transition not been
34
+ * bypassed — `liveGateIds(phase, judged)` answers that. But the live set of
35
+ * the FINAL transition is not the question: the size ratchet is live only at
36
+ * `implemented`, so a slice bypassed there and later advanced to `qa-handoff`
37
+ * has an EMPTY live set at its final transition, and a reader who looked only
38
+ * there would see nothing wrong. The union over every gate event the slice
39
+ * ever produced is what catches it.
40
+ *
41
+ * A `bypass` event is the PRIMARY evidence of a near-miss but the rule does
42
+ * not DEPEND on it: a live gate with NO verdict of its own is a near-miss too,
43
+ * because a gate that was skipped and recorded nothing must not vanish from
44
+ * the metric. The converse is what keeps the number honest: a live gate that
45
+ * got a `pass` OR a `block` WAS evaluated, and neither is a near-miss.
46
+ *
47
+ * WHAT THE RULE CANNOT SEE. The live set is the union over the slice's gate
48
+ * EVENTS, so a gate is only ever found unevaluated when a sibling gate event
49
+ * establishes that it was live. A phase at which NO gate event was emitted
50
+ * contributes nothing — the gates live there are not in the live set at all —
51
+ * so that shape is NOT observable for this class, and the coverage output
52
+ * carries the count of slices that produced no gate event.
53
+ *
54
+ * WHY THE DECLARED TYPE IS READ FROM THE EVENT AND NOT FROM THE ARTIFACT.
55
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
56
+ * the artifact on disk carries the CURRENT type, not the type the transition
57
+ * ran under. The gate event carries the type the transition judged, so the
58
+ * live set is reproduced from the event stream alone.
59
+ *
60
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
61
+ * (written before the type was carried) exist on this branch without the
62
+ * field. A `claim-table` event at the same phase in the same slice proves
63
+ * the slice was tooling-only at that phase — the claim table only runs for
64
+ * tooling-only slices — and its absence proves it was not. When even that
65
+ * leaves the liveness undetermined (no usable phase), the gate is reported in
66
+ * the `undetermined` list rather than being silently counted or silently
67
+ * dropped: a reader must be able to see that something was not decidable.
68
+ *
69
+ * WHY THE TOOL-BLOCKED BRANCH IS EMPTY. The `tool-trace` category does not
70
+ * exist in the schema yet — the tool-trace stream is a later slice. The
71
+ * branch in `near-miss-facts.ts` is written so that the moment the category
72
+ * lands, the reason starts firing with no change to this file's contract;
73
+ * until then it finds nothing, because there is nothing to find.
74
+ *
75
+ * WHY THE REPORT CARRIES ITS COVERAGE. A rate over a class that had no
76
+ * events to observe is not a rate — it is an absence read as a result, which
77
+ * is the exact failure this programme exists to close. The report therefore
78
+ * says, per class, whether the class was observable at all, and the CLI
79
+ * warns when one was not.
80
+ *
81
+ * WHY THE REPORT CARRIES ITS DENOMINATOR. "Passed" has two definitions here
82
+ * and they do not count the same slices, so the report states the one it
83
+ * uses and reconciles it with the status summary's.
84
+ *
85
+ * WHY THE READERS LIVE NEXT DOOR. `near-miss-facts.ts` holds the event-shape
86
+ * readers this metric is computed from, and `near-miss-records.ts` holds the
87
+ * shape of a finding; this file holds the METRIC and nothing else — the same
88
+ * split `aggregation.ts` and `aggregation-helpers.ts` make in this directory.
89
+ */
90
+ import type { ObservabilityEvent } from './observability-service.js';
91
+ import { type NearMissUndetermined, type NearMissReason } from './near-miss-facts.js';
92
+ import { type NearMissRecord, type NearMissUnmeasured } from './near-miss-records.js';
93
+ import { type NearMissClassCoverage } from './near-miss-coverage.js';
94
+ import { type NearMissDenominator } from './near-miss-denominator.js';
95
+ import type { RequestTypeReading } from './hotspot-shared.js';
96
+ export type { NearMissEvidence, NearMissUndetermined, NearMissReason, UnsatisfiedKey, UnsatisfiedKeyState } from './near-miss-facts.js';
97
+ export type { NearMissClassCoverage } from './near-miss-coverage.js';
98
+ export type { NearMissDenominator } from './near-miss-denominator.js';
99
+ export type { NearMissRecord, NearMissUnmeasured } from './near-miss-records.js';
100
+ /** The near-miss metric over a set of events. */
101
+ export type NearMissReport = {
102
+ /** Near-miss slices over passing slices; 0 when there are no passing slices. */
103
+ readonly nearMissRate: number;
104
+ readonly passedSliceCount: number;
105
+ readonly nearMissSliceCount: number;
106
+ readonly records: readonly NearMissRecord[];
107
+ /** Gates whose liveness or verdict the stream did not decide. */
108
+ readonly undetermined: readonly NearMissUndetermined[];
109
+ /**
110
+ * The slices whose PASS verdict could not be READ.
111
+ *
112
+ * Whether such a slice passed is unknown, so it is in neither the
113
+ * numerator nor the denominator — and it is listed here rather than
114
+ * dropped, because a slice that vanishes from the accounting reads as "no
115
+ * passing slices", which is an absence read as a result.
116
+ */
117
+ readonly unmeasured: readonly NearMissUnmeasured[];
118
+ /**
119
+ * What each reason class could and could not be observed for.
120
+ *
121
+ * A class with `observable: false` had NO events of its kind in the scope,
122
+ * so its share of the rate is an absence of data — not a result. A consumer
123
+ * that reads `nearMissRate` alone can still be misled, so this travels in
124
+ * the same envelope.
125
+ */
126
+ readonly coverage: readonly NearMissClassCoverage[];
127
+ /**
128
+ * The reason classes this scope had NO events to observe.
129
+ *
130
+ * The aggregate `nearMissRate` does NOT cover these classes, so a zero
131
+ * over them is an absence of data rather than a result. The per-class
132
+ * `coverage` entry says the same thing with the numbers behind it.
133
+ */
134
+ readonly unobservedClasses: readonly NearMissReason[];
135
+ /**
136
+ * The denominator the rate divides by, and how it relates to the status
137
+ * summary's success count.
138
+ */
139
+ readonly denominator: NearMissDenominator;
140
+ };
141
+ /**
142
+ * The near-miss metric over a set of events.
143
+ *
144
+ * The rate divides the near-miss slices by the PASSING slices — the slices
145
+ * that recorded a successful verdict attempt — and is 0 when there are none,
146
+ * so an empty scope reads as "no rate" rather than as a division by zero.
147
+ */
148
+ export declare function computeNearMiss(events: readonly ObservabilityEvent[], requestTypes?: ReadonlyMap<string, RequestTypeReading>): NearMissReport;
@@ -0,0 +1,196 @@
1
+ /**
2
+ * `src/services/observability/near-miss.ts`
3
+ *
4
+ * The near-miss rate: of the slices that were declared PASSING, how many
5
+ * passed anyway after a required check was still unsatisfied?
6
+ *
7
+ * WHY THIS EXISTS. The premise of the whole programme is that "the QA verdict
8
+ * says pass" is a metric that is blind: it cannot see a pass that was bought
9
+ * by skipping a check. This module is the number that can see it. The spec
10
+ * (§2.3 S2.3) names it the headline output of the project, and the review
11
+ * focus of Task 5 is the distinction between "gate skipped and never
12
+ * evaluated" and "gate evaluated and passed" — the latter is normal flow, and
13
+ * misreading it as the former would inflate the metric past meaning.
14
+ *
15
+ * THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question this metric asks
16
+ * is "at the moment the slice was declared passing, had the required check
17
+ * been satisfied?" — so the reference is the PASS, not the first
18
+ * `verdict-issued` event and not the last attempt at a key. A `verdict-issued`
19
+ * attempt whose prereq check FAILED is not a pass at all; it is a refused
20
+ * transition recorded under the same `to` state. The pass moment is therefore
21
+ * the first `verdict-issued` attempt whose prereq check SUCCEEDED.
22
+ *
23
+ * A slice with no pass moment was never declared passing, so it is in
24
+ * neither the numerator nor the denominator: there is no pass to have been
25
+ * bought by skipping a check. The EXCEPTION is a slice whose pass moment
26
+ * exists but could not be READ — a `verdict-issued` attempt whose prereq
27
+ * verdict is recorded in a shape this build cannot read. Whether such a slice
28
+ * passed is unknown, so it is reported as UNMEASURED rather than dropped: a
29
+ * slice that vanishes from the accounting reads as "no passing slices", which
30
+ * is an absence read as a result.
31
+ *
32
+ * THE LIVE SET IS A UNION OVER THE SLICE'S WHOLE HISTORY. A gate is "live"
33
+ * for a transition when it WOULD have run had the transition not been
34
+ * bypassed — `liveGateIds(phase, judged)` answers that. But the live set of
35
+ * the FINAL transition is not the question: the size ratchet is live only at
36
+ * `implemented`, so a slice bypassed there and later advanced to `qa-handoff`
37
+ * has an EMPTY live set at its final transition, and a reader who looked only
38
+ * there would see nothing wrong. The union over every gate event the slice
39
+ * ever produced is what catches it.
40
+ *
41
+ * A `bypass` event is the PRIMARY evidence of a near-miss but the rule does
42
+ * not DEPEND on it: a live gate with NO verdict of its own is a near-miss too,
43
+ * because a gate that was skipped and recorded nothing must not vanish from
44
+ * the metric. The converse is what keeps the number honest: a live gate that
45
+ * got a `pass` OR a `block` WAS evaluated, and neither is a near-miss.
46
+ *
47
+ * WHAT THE RULE CANNOT SEE. The live set is the union over the slice's gate
48
+ * EVENTS, so a gate is only ever found unevaluated when a sibling gate event
49
+ * establishes that it was live. A phase at which NO gate event was emitted
50
+ * contributes nothing — the gates live there are not in the live set at all —
51
+ * so that shape is NOT observable for this class, and the coverage output
52
+ * carries the count of slices that produced no gate event.
53
+ *
54
+ * WHY THE DECLARED TYPE IS READ FROM THE EVENT AND NOT FROM THE ARTIFACT.
55
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
56
+ * the artifact on disk carries the CURRENT type, not the type the transition
57
+ * ran under. The gate event carries the type the transition judged, so the
58
+ * live set is reproduced from the event stream alone.
59
+ *
60
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
61
+ * (written before the type was carried) exist on this branch without the
62
+ * field. A `claim-table` event at the same phase in the same slice proves
63
+ * the slice was tooling-only at that phase — the claim table only runs for
64
+ * tooling-only slices — and its absence proves it was not. When even that
65
+ * leaves the liveness undetermined (no usable phase), the gate is reported in
66
+ * the `undetermined` list rather than being silently counted or silently
67
+ * dropped: a reader must be able to see that something was not decidable.
68
+ *
69
+ * WHY THE TOOL-BLOCKED BRANCH IS EMPTY. The `tool-trace` category does not
70
+ * exist in the schema yet — the tool-trace stream is a later slice. The
71
+ * branch in `near-miss-facts.ts` is written so that the moment the category
72
+ * lands, the reason starts firing with no change to this file's contract;
73
+ * until then it finds nothing, because there is nothing to find.
74
+ *
75
+ * WHY THE REPORT CARRIES ITS COVERAGE. A rate over a class that had no
76
+ * events to observe is not a rate — it is an absence read as a result, which
77
+ * is the exact failure this programme exists to close. The report therefore
78
+ * says, per class, whether the class was observable at all, and the CLI
79
+ * warns when one was not.
80
+ *
81
+ * WHY THE REPORT CARRIES ITS DENOMINATOR. "Passed" has two definitions here
82
+ * and they do not count the same slices, so the report states the one it
83
+ * uses and reconciles it with the status summary's.
84
+ *
85
+ * WHY THE READERS LIVE NEXT DOOR. `near-miss-facts.ts` holds the event-shape
86
+ * readers this metric is computed from, and `near-miss-records.ts` holds the
87
+ * shape of a finding; this file holds the METRIC and nothing else — the same
88
+ * split `aggregation.ts` and `aggregation-helpers.ts` make in this directory.
89
+ */
90
+ import { sliceFacts } from './near-miss-facts.js';
91
+ import { evidenceFor, reasonsFor, unmeasuredReason } from './near-miss-records.js';
92
+ import { computeCoverage, unobservableReasons } from './near-miss-coverage.js';
93
+ import { describeDenominator } from './near-miss-denominator.js';
94
+ /**
95
+ * The events of one slice, grouped by the slice they belong to.
96
+ *
97
+ * An event with no slice rid belongs to no slice, so it is not in any of the
98
+ * populations — it is not a slice's evidence of anything.
99
+ */
100
+ function groupBySlice(events) {
101
+ const bySlice = new Map();
102
+ for (const event of events) {
103
+ const sliceRid = event.sliceRid;
104
+ if (sliceRid === undefined)
105
+ continue;
106
+ const bucket = bySlice.get(sliceRid);
107
+ if (bucket === undefined)
108
+ bySlice.set(sliceRid, [event]);
109
+ else
110
+ bucket.push(event);
111
+ }
112
+ return bySlice;
113
+ }
114
+ /**
115
+ * The walk over the slices: what passed, what was flagged, and what could
116
+ * not be measured at all.
117
+ */
118
+ function walkSlices(bySlice) {
119
+ const records = [];
120
+ const undetermined = [];
121
+ const unmeasured = [];
122
+ const passingFacts = [];
123
+ const unmeasuredFacts = [];
124
+ const reasonsBySlice = new Map();
125
+ let passedSliceCount = 0;
126
+ for (const [sliceRid, sliceEvents] of bySlice) {
127
+ const fact = sliceFacts(sliceRid, sliceEvents);
128
+ const unreadable = fact.unreadableVerdict;
129
+ if (unreadable !== null) {
130
+ // The verdict was RECORDED and could not be READ, so whether the slice
131
+ // passed is unknown. It is in neither the numerator nor the denominator,
132
+ // and it is reported rather than dropped.
133
+ unmeasured.push({
134
+ sliceRid,
135
+ sessionId: unreadable.sessionId,
136
+ ts: unreadable.ts,
137
+ reason: unmeasuredReason(unreadable, fact.passMoment !== null)
138
+ });
139
+ unmeasuredFacts.push(fact);
140
+ continue;
141
+ }
142
+ // A slice with no pass moment was never declared passing.
143
+ if (fact.passMoment === null)
144
+ continue;
145
+ passedSliceCount += 1;
146
+ passingFacts.push(fact);
147
+ const { reasons, neverEvaluated } = reasonsFor(fact);
148
+ undetermined.push(...fact.undetermined);
149
+ if (reasons.length === 0)
150
+ continue;
151
+ const gateEvents = sliceEvents.filter((event) => event.category === 'gate');
152
+ reasonsBySlice.set(sliceRid, reasons);
153
+ records.push({
154
+ sliceRid,
155
+ reasons,
156
+ passMoment: { ts: fact.passMoment.ts },
157
+ unsatisfiedKeys: fact.passMoment.unsatisfiedKeys,
158
+ evidence: evidenceFor(neverEvaluated, gateEvents, fact.passMoment)
159
+ });
160
+ }
161
+ return {
162
+ records,
163
+ undetermined,
164
+ unmeasured,
165
+ passingFacts,
166
+ unmeasuredFacts,
167
+ reasonsBySlice,
168
+ passedSliceCount
169
+ };
170
+ }
171
+ /**
172
+ * The near-miss metric over a set of events.
173
+ *
174
+ * The rate divides the near-miss slices by the PASSING slices — the slices
175
+ * that recorded a successful verdict attempt — and is 0 when there are none,
176
+ * so an empty scope reads as "no rate" rather than as a division by zero.
177
+ */
178
+ export function computeNearMiss(events, requestTypes = new Map()) {
179
+ const walk = walkSlices(groupBySlice(events));
180
+ const { records, undetermined, unmeasured, passingFacts, unmeasuredFacts, reasonsBySlice } = walk;
181
+ const passedSliceCount = walk.passedSliceCount;
182
+ const nearMissSliceCount = records.length;
183
+ const nearMissRate = passedSliceCount === 0 ? 0 : nearMissSliceCount / passedSliceCount;
184
+ const coverage = computeCoverage({ events, passingFacts, reasonsBySlice, unmeasuredFacts });
185
+ return {
186
+ nearMissRate,
187
+ passedSliceCount,
188
+ nearMissSliceCount,
189
+ records,
190
+ undetermined,
191
+ unmeasured,
192
+ coverage,
193
+ unobservedClasses: unobservableReasons(coverage),
194
+ denominator: describeDenominator(events, passedSliceCount, requestTypes, unmeasured.length)
195
+ };
196
+ }