peaks-loop 4.1.21 → 4.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +191 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  6. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  7. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  8. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  9. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  10. package/dist/cli/commands/observability-commands-queries.js +88 -47
  11. package/dist/cli/commands/observability-commands.js +79 -20
  12. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  13. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  14. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  15. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  16. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  17. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  18. package/dist/services/artifacts/rd-gate-event.js +211 -0
  19. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  20. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  21. package/dist/services/distribution/json-layout.d.ts +20 -0
  22. package/dist/services/distribution/json-layout.js +195 -0
  23. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  24. package/dist/services/distribution/plugin-manifest.js +40 -4
  25. package/dist/services/observability/aggregation-types.d.ts +21 -0
  26. package/dist/services/observability/aggregation.d.ts +12 -2
  27. package/dist/services/observability/aggregation.js +26 -2
  28. package/dist/services/observability/compliance-judge.d.ts +77 -0
  29. package/dist/services/observability/compliance-judge.js +143 -0
  30. package/dist/services/observability/compliance-spec.d.ts +96 -0
  31. package/dist/services/observability/compliance-spec.js +29 -0
  32. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  33. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  34. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  35. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  36. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  37. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  38. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  39. package/dist/services/observability/hotspot-rows.js +89 -0
  40. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  41. package/dist/services/observability/hotspot-shared.js +122 -0
  42. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  43. package/dist/services/observability/hotspot-sources.js +142 -0
  44. package/dist/services/observability/hotspots.d.ts +47 -0
  45. package/dist/services/observability/hotspots.js +47 -0
  46. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  47. package/dist/services/observability/near-miss-attempts.js +223 -0
  48. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  49. package/dist/services/observability/near-miss-coverage.js +108 -0
  50. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  51. package/dist/services/observability/near-miss-denominator.js +75 -0
  52. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  53. package/dist/services/observability/near-miss-difference.js +132 -0
  54. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  55. package/dist/services/observability/near-miss-facts.js +101 -0
  56. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  57. package/dist/services/observability/near-miss-gate-events.js +106 -0
  58. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  59. package/dist/services/observability/near-miss-gates.js +135 -0
  60. package/dist/services/observability/near-miss-records.d.ts +93 -0
  61. package/dist/services/observability/near-miss-records.js +87 -0
  62. package/dist/services/observability/near-miss.d.ts +148 -0
  63. package/dist/services/observability/near-miss.js +196 -0
  64. package/dist/services/observability/observability-schema.d.ts +17 -2
  65. package/dist/services/observability/observability-schema.js +21 -1
  66. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  67. package/dist/services/observability/owner-skill-map.js +144 -0
  68. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  69. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  70. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  71. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  72. package/dist/services/observability/report-formatter.d.ts +49 -3
  73. package/dist/services/observability/report-formatter.js +55 -14
  74. package/dist/services/observability/retro-attribution.d.ts +129 -0
  75. package/dist/services/observability/retro-attribution.js +134 -0
  76. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  77. package/dist/services/observability/session-metric-rows.js +184 -0
  78. package/package.json +5 -5
@@ -0,0 +1,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
+ }