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,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
|
+
}
|
|
@@ -15,7 +15,21 @@
|
|
|
15
15
|
*/
|
|
16
16
|
import { z } from 'zod';
|
|
17
17
|
export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
|
|
18
|
-
|
|
18
|
+
/**
|
|
19
|
+
* The event vocabulary every observability record is drawn from.
|
|
20
|
+
*
|
|
21
|
+
* EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
|
|
22
|
+
* what makes it fire is a promise the schema makes and the program does not
|
|
23
|
+
* keep. The audit that records, for every category, where it is emitted, what
|
|
24
|
+
* triggers it and whether it has ever fired, lives at
|
|
25
|
+
* `.peaks/docs/observability-category-audit.md`; a category added to this list
|
|
26
|
+
* joins that table in the same change that declares it.
|
|
27
|
+
*
|
|
28
|
+
* THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
|
|
29
|
+
* a reader that stores a category by its index must never watch its meaning
|
|
30
|
+
* change under it.
|
|
31
|
+
*/
|
|
32
|
+
export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
|
|
19
33
|
export type ObservabilityCategory = (typeof OBSERVABILITY_CATEGORIES)[number];
|
|
20
34
|
export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
|
|
21
35
|
export type ObservabilitySubagentRole = (typeof OBSERVABILITY_SUBAGENT_ROLES)[number];
|
|
@@ -24,6 +38,7 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
|
|
|
24
38
|
ts: z.ZodString;
|
|
25
39
|
sessionId: z.ZodString;
|
|
26
40
|
category: z.ZodEnum<{
|
|
41
|
+
gate: "gate";
|
|
27
42
|
"slice-transition": "slice-transition";
|
|
28
43
|
dispatch: "dispatch";
|
|
29
44
|
checkpoint: "checkpoint";
|
|
@@ -66,6 +81,6 @@ export type EmitResult = {
|
|
|
66
81
|
};
|
|
67
82
|
export declare const OBSERVABILITY_CONSTANTS: {
|
|
68
83
|
readonly SCHEMA_VERSION: 1;
|
|
69
|
-
readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
|
|
84
|
+
readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
|
|
70
85
|
readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
|
|
71
86
|
};
|
|
@@ -15,6 +15,20 @@
|
|
|
15
15
|
*/
|
|
16
16
|
import { z } from 'zod';
|
|
17
17
|
export const OBSERVABILITY_SCHEMA_VERSION = 1;
|
|
18
|
+
/**
|
|
19
|
+
* The event vocabulary every observability record is drawn from.
|
|
20
|
+
*
|
|
21
|
+
* EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
|
|
22
|
+
* what makes it fire is a promise the schema makes and the program does not
|
|
23
|
+
* keep. The audit that records, for every category, where it is emitted, what
|
|
24
|
+
* triggers it and whether it has ever fired, lives at
|
|
25
|
+
* `.peaks/docs/observability-category-audit.md`; a category added to this list
|
|
26
|
+
* joins that table in the same change that declares it.
|
|
27
|
+
*
|
|
28
|
+
* THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
|
|
29
|
+
* a reader that stores a category by its index must never watch its meaning
|
|
30
|
+
* change under it.
|
|
31
|
+
*/
|
|
18
32
|
export const OBSERVABILITY_CATEGORIES = [
|
|
19
33
|
'slice-transition',
|
|
20
34
|
'dispatch',
|
|
@@ -30,7 +44,13 @@ export const OBSERVABILITY_CATEGORIES = [
|
|
|
30
44
|
// 3.A). Read by `peaks lease metrics`. The `detail.kind` field
|
|
31
45
|
// discriminates spawn / renew / release / gc / autoRelease /
|
|
32
46
|
// autoRelease-failed / autoRelease-skipped.
|
|
33
|
-
'lease'
|
|
47
|
+
'lease',
|
|
48
|
+
// The RD transition gates' verdicts. One event per gate DECISION, so a
|
|
49
|
+
// reader can ask which gate was never evaluated: `detail.gateId` names it
|
|
50
|
+
// ('file-size-ratchet' / 'declared-type-corroboration' / 'claim-table'),
|
|
51
|
+
// `detail.outcome` says what it decided ('pass' / 'block' / 'bypass').
|
|
52
|
+
// APPENDED, so no existing category's index shifts.
|
|
53
|
+
'gate'
|
|
34
54
|
];
|
|
35
55
|
// v2.12.0 fan-out collapse: `security-reviewer` (in-process RD slot)
|
|
36
56
|
// moved out to the standalone `peaks-security-audit` skill; the matching
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/owner-skill-map.ts`
|
|
3
|
+
*
|
|
4
|
+
* The path → owning-skill lookup. An artifact path says WHAT is missing;
|
|
5
|
+
* this table says WHO was supposed to produce it, so a reader of the
|
|
6
|
+
* observability stream can name the skill that failed to deliver rather
|
|
7
|
+
* than only counting the failure.
|
|
8
|
+
*
|
|
9
|
+
* WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
|
|
10
|
+
* from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
|
|
11
|
+
* live under the same directory and belong to two different skills, and a
|
|
12
|
+
* rule that said "anything under `audit/` is an audit artifact" would name
|
|
13
|
+
* neither. The table states the ownership explicitly, and the more specific
|
|
14
|
+
* prefix wins when two could match.
|
|
15
|
+
*
|
|
16
|
+
* WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
|
|
17
|
+
* would attribute both audit artifacts to one skill, which is the
|
|
18
|
+
* ambiguity this table exists to remove. The audit entries are the
|
|
19
|
+
* specific ones instead — one per artifact, and one per location that
|
|
20
|
+
* artifact is written at.
|
|
21
|
+
*
|
|
22
|
+
* WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
|
|
23
|
+
* name, and a guessed owner is worse than none: it would put a skill's name
|
|
24
|
+
* on an artifact that skill never produces. The paths that are genuinely
|
|
25
|
+
* ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
|
|
26
|
+
* "no owner" is always a stated fact and never a gap.
|
|
27
|
+
*
|
|
28
|
+
* TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
|
|
29
|
+
* with it — and an EXACT claim when it says so. The exact rows exist for
|
|
30
|
+
* the bare, file-shaped legacy locations: a prefix claim on a file name
|
|
31
|
+
* would also claim every file whose name merely starts with it, and an
|
|
32
|
+
* artifact that was never produced must not be attributed to the skill
|
|
33
|
+
* that owns a different file with a similar name.
|
|
34
|
+
*
|
|
35
|
+
* THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
|
|
36
|
+
* capsule declares the evidence Gate C will check, and a declared key that
|
|
37
|
+
* names a file that is not on disk reaches the missing list under the key's
|
|
38
|
+
* own name. The owner of a key is the skill that produces the evidence the
|
|
39
|
+
* key names — the same question the artifact rows answer, asked of a
|
|
40
|
+
* declaration instead of a file.
|
|
41
|
+
*/
|
|
42
|
+
/** One row of the map: a path prefix and the skill that owns what it names. */
|
|
43
|
+
export type OwnerSkillEntry = {
|
|
44
|
+
readonly prefix: string;
|
|
45
|
+
readonly skill: string;
|
|
46
|
+
/**
|
|
47
|
+
* True when `prefix` names ONE file rather than a directory of files: the
|
|
48
|
+
* match is the whole path, not its start.
|
|
49
|
+
*/
|
|
50
|
+
readonly exact?: boolean;
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* The map, in declaration order. The LOOKUP sorts by prefix length, so this
|
|
54
|
+
* order is documentation, not the resolution order.
|
|
55
|
+
*/
|
|
56
|
+
export declare const OWNER_SKILL_ENTRIES: readonly OwnerSkillEntry[];
|
|
57
|
+
/**
|
|
58
|
+
* A shape of path that has no owning skill, and the reason it has none.
|
|
59
|
+
*
|
|
60
|
+
* The list exists so that "no owner" is a STATED fact. A path that reaches
|
|
61
|
+
* the missing list and is neither in the map nor here is a hole, and the
|
|
62
|
+
* census test is what turns that hole into a red test.
|
|
63
|
+
*/
|
|
64
|
+
export type UnownedPathEntry = {
|
|
65
|
+
/** The path prefix that identifies the shape. */
|
|
66
|
+
readonly prefix: string;
|
|
67
|
+
/** Why no skill owns a path of this shape. */
|
|
68
|
+
readonly reason: string;
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* The paths that have no owner, and why.
|
|
72
|
+
*
|
|
73
|
+
* `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
|
|
74
|
+
* read. It is not an artifact: no skill produces a broken capsule, so there
|
|
75
|
+
* is no owner to name — the defect belongs to whoever wrote the capsule, and
|
|
76
|
+
* the gate reports it as a body failure on the capsule itself.
|
|
77
|
+
*/
|
|
78
|
+
export declare const UNOWNED_PATH_ENTRIES: readonly UnownedPathEntry[];
|
|
79
|
+
/**
|
|
80
|
+
* The skill that owns the artifact at `path`, or `null` when no row claims
|
|
81
|
+
* it.
|
|
82
|
+
*
|
|
83
|
+
* Total over every input: a value that is not a string answers `null` rather
|
|
84
|
+
* than raising, because this runs inside the observability emit, whose
|
|
85
|
+
* contract is that it never throws and never changes the caller's decision.
|
|
86
|
+
*/
|
|
87
|
+
export declare function ownerSkillForPath(path: string): string | null;
|
|
88
|
+
/**
|
|
89
|
+
* The reason the path at `path` has no owning skill, or `null` when the
|
|
90
|
+
* path is not one of the known ownerless shapes.
|
|
91
|
+
*/
|
|
92
|
+
export declare function unownedPathReason(path: string): string | null;
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/owner-skill-map.ts`
|
|
3
|
+
*
|
|
4
|
+
* The path → owning-skill lookup. An artifact path says WHAT is missing;
|
|
5
|
+
* this table says WHO was supposed to produce it, so a reader of the
|
|
6
|
+
* observability stream can name the skill that failed to deliver rather
|
|
7
|
+
* than only counting the failure.
|
|
8
|
+
*
|
|
9
|
+
* WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
|
|
10
|
+
* from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
|
|
11
|
+
* live under the same directory and belong to two different skills, and a
|
|
12
|
+
* rule that said "anything under `audit/` is an audit artifact" would name
|
|
13
|
+
* neither. The table states the ownership explicitly, and the more specific
|
|
14
|
+
* prefix wins when two could match.
|
|
15
|
+
*
|
|
16
|
+
* WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
|
|
17
|
+
* would attribute both audit artifacts to one skill, which is the
|
|
18
|
+
* ambiguity this table exists to remove. The audit entries are the
|
|
19
|
+
* specific ones instead — one per artifact, and one per location that
|
|
20
|
+
* artifact is written at.
|
|
21
|
+
*
|
|
22
|
+
* WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
|
|
23
|
+
* name, and a guessed owner is worse than none: it would put a skill's name
|
|
24
|
+
* on an artifact that skill never produces. The paths that are genuinely
|
|
25
|
+
* ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
|
|
26
|
+
* "no owner" is always a stated fact and never a gap.
|
|
27
|
+
*
|
|
28
|
+
* TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
|
|
29
|
+
* with it — and an EXACT claim when it says so. The exact rows exist for
|
|
30
|
+
* the bare, file-shaped legacy locations: a prefix claim on a file name
|
|
31
|
+
* would also claim every file whose name merely starts with it, and an
|
|
32
|
+
* artifact that was never produced must not be attributed to the skill
|
|
33
|
+
* that owns a different file with a similar name.
|
|
34
|
+
*
|
|
35
|
+
* THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
|
|
36
|
+
* capsule declares the evidence Gate C will check, and a declared key that
|
|
37
|
+
* names a file that is not on disk reaches the missing list under the key's
|
|
38
|
+
* own name. The owner of a key is the skill that produces the evidence the
|
|
39
|
+
* key names — the same question the artifact rows answer, asked of a
|
|
40
|
+
* declaration instead of a file.
|
|
41
|
+
*/
|
|
42
|
+
/**
|
|
43
|
+
* The map, in declaration order. The LOOKUP sorts by prefix length, so this
|
|
44
|
+
* order is documentation, not the resolution order.
|
|
45
|
+
*/
|
|
46
|
+
export const OWNER_SKILL_ENTRIES = [
|
|
47
|
+
{ prefix: 'gateEvidence.codeReview', skill: 'peaks-rd' },
|
|
48
|
+
{ prefix: 'gateEvidence.perfBaseline', skill: 'peaks-perf-audit' },
|
|
49
|
+
{ prefix: 'gateEvidence.prdHandoff', skill: 'peaks-prd' },
|
|
50
|
+
// The project scan is Gate A's artifact, and Gate A belongs to the
|
|
51
|
+
// orchestrator: `skills/peaks-code/SKILL.md` carries it as the MANDATORY
|
|
52
|
+
// "Pre-RD project scan checklist", and
|
|
53
|
+
// `skills/peaks-code/references/project-scan-checklist.md` opens with
|
|
54
|
+
// "Before handing off to `peaks-rd`, scan the project and record findings
|
|
55
|
+
// to `.peaks/project-scan/project-scan.md`". The declared path is that
|
|
56
|
+
// file, so the skill that writes it is the one that owns the key.
|
|
57
|
+
{ prefix: 'gateEvidence.projectScan', skill: 'peaks-code' },
|
|
58
|
+
// The security review evidence. For the fanout types the key declares
|
|
59
|
+
// `audit/security-<rid>.md`, which the independent security audit writes;
|
|
60
|
+
// for the `config` type it declares the config-specific
|
|
61
|
+
// `rd/security-review-<rid>.md`, which is an RD artifact. One key, one
|
|
62
|
+
// answer — the row names the skill that owns the security review as a
|
|
63
|
+
// concept, which is the audit skill for every type that reaches it.
|
|
64
|
+
{ prefix: 'gateEvidence.securityReview', skill: 'peaks-security-audit' },
|
|
65
|
+
{ prefix: 'audit/security-', skill: 'peaks-security-audit' },
|
|
66
|
+
// The bare security audit location — the one that predates the request id
|
|
67
|
+
// in the filename. It is a live tier, not a guess: the judged-declaration
|
|
68
|
+
// check resolves the audit artifact through `securityArtifactTiers`, and
|
|
69
|
+
// that list's second entry is this file — so a session holding it puts that
|
|
70
|
+
// path into the missing list, and a row that did not claim it would leave
|
|
71
|
+
// that missing artifact with no owner. EXACT, because the row claims this
|
|
72
|
+
// one file and not every file whose name begins with it.
|
|
73
|
+
{ prefix: 'audit/security.md', skill: 'peaks-security-audit', exact: true },
|
|
74
|
+
{ prefix: 'audit/perf-', skill: 'peaks-perf-audit' },
|
|
75
|
+
// The bare perf audit location — the sibling of the security one above,
|
|
76
|
+
// and the same story: the resolver probes it as a legacy tier.
|
|
77
|
+
{ prefix: 'audit/perf.md', skill: 'peaks-perf-audit', exact: true },
|
|
78
|
+
{ prefix: 'prd/', skill: 'peaks-prd' },
|
|
79
|
+
{ prefix: 'ui/', skill: 'peaks-ui' },
|
|
80
|
+
{ prefix: 'rd/', skill: 'peaks-rd' },
|
|
81
|
+
// The third-party review is the REVIEWER's artifact, not RD's: the prereq
|
|
82
|
+
// that demands it names the skill that writes it ("v2.14.0 G4 third-party
|
|
83
|
+
// reviewer (peaks-reviewer skill)"). The `rd/` row above is a DIRECTORY
|
|
84
|
+
// claim, so without this row it over-claimed this file and named the wrong
|
|
85
|
+
// skill to fix.
|
|
86
|
+
{ prefix: 'rd/third-party-review-', skill: 'peaks-reviewer' },
|
|
87
|
+
{ prefix: 'qa/', skill: 'peaks-qa' },
|
|
88
|
+
{ prefix: 'sc/', skill: 'peaks-sc' },
|
|
89
|
+
{ prefix: 'mut/', skill: 'peaks-mut' }
|
|
90
|
+
];
|
|
91
|
+
/**
|
|
92
|
+
* The same rows, most specific prefix first. A longer prefix is a narrower
|
|
93
|
+
* claim, so it is tried first — that is what keeps `audit/security.md` ahead
|
|
94
|
+
* of `audit/security-`, and both ahead of a shorter prefix that would also
|
|
95
|
+
* match them.
|
|
96
|
+
*/
|
|
97
|
+
const ENTRIES_BY_SPECIFICITY = [...OWNER_SKILL_ENTRIES].sort((a, b) => b.prefix.length - a.prefix.length);
|
|
98
|
+
/**
|
|
99
|
+
* The paths that have no owner, and why.
|
|
100
|
+
*
|
|
101
|
+
* `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
|
|
102
|
+
* read. It is not an artifact: no skill produces a broken capsule, so there
|
|
103
|
+
* is no owner to name — the defect belongs to whoever wrote the capsule, and
|
|
104
|
+
* the gate reports it as a body failure on the capsule itself.
|
|
105
|
+
*/
|
|
106
|
+
export const UNOWNED_PATH_ENTRIES = [
|
|
107
|
+
{
|
|
108
|
+
prefix: 'gateEvidence(',
|
|
109
|
+
reason: 'a handoff capsule whose gateEvidence declaration cannot be read is not an artifact ' +
|
|
110
|
+
'any skill produces — the defect belongs to whoever wrote the capsule, so there is ' +
|
|
111
|
+
'no owning skill to name'
|
|
112
|
+
}
|
|
113
|
+
];
|
|
114
|
+
/**
|
|
115
|
+
* The skill that owns the artifact at `path`, or `null` when no row claims
|
|
116
|
+
* it.
|
|
117
|
+
*
|
|
118
|
+
* Total over every input: a value that is not a string answers `null` rather
|
|
119
|
+
* than raising, because this runs inside the observability emit, whose
|
|
120
|
+
* contract is that it never throws and never changes the caller's decision.
|
|
121
|
+
*/
|
|
122
|
+
export function ownerSkillForPath(path) {
|
|
123
|
+
if (typeof path !== 'string')
|
|
124
|
+
return null;
|
|
125
|
+
for (const entry of ENTRIES_BY_SPECIFICITY) {
|
|
126
|
+
const claimed = entry.exact === true ? path === entry.prefix : path.startsWith(entry.prefix);
|
|
127
|
+
if (claimed)
|
|
128
|
+
return entry.skill;
|
|
129
|
+
}
|
|
130
|
+
return null;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* The reason the path at `path` has no owning skill, or `null` when the
|
|
134
|
+
* path is not one of the known ownerless shapes.
|
|
135
|
+
*/
|
|
136
|
+
export function unownedPathReason(path) {
|
|
137
|
+
if (typeof path !== 'string')
|
|
138
|
+
return null;
|
|
139
|
+
for (const entry of UNOWNED_PATH_ENTRIES) {
|
|
140
|
+
if (path.startsWith(entry.prefix))
|
|
141
|
+
return entry.reason;
|
|
142
|
+
}
|
|
143
|
+
return null;
|
|
144
|
+
}
|