peaks-loop 4.1.22 → 4.1.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +82 -0
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands.js +79 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
- package/dist/services/artifacts/prerequisite-path-census.js +79 -0
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +26 -2
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +212 -0
- package/dist/services/observability/hotspot-shared.js +122 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +132 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +196 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +144 -0
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/package.json +5 -5
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/retro-attribution.ts`
|
|
3
|
+
*
|
|
4
|
+
* Retro-attribution: name the artifacts behind the historical failures that
|
|
5
|
+
* recorded only a COUNT.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS. Every slice-transition event carries `detail.missingCount`.
|
|
8
|
+
* The v1 events in this repository's own event log were written before the
|
|
9
|
+
* emitter kept the missing-artifact LIST, so the list they name is not in the
|
|
10
|
+
* record, and no amount of reading the record will produce it.
|
|
11
|
+
*
|
|
12
|
+
* WHAT CAN BE DERIVED INSTEAD. The prerequisite table is a pure function of
|
|
13
|
+
* three values — the artifact role, the target state and the request type —
|
|
14
|
+
* and a v1 event carries the first two. Re-deriving the table for that
|
|
15
|
+
* transition yields the CANDIDATE set: the artifacts the missing entries could
|
|
16
|
+
* be. The recorded count then says how many artifacts were missing in total,
|
|
17
|
+
* which is what decides whether the candidates can be narrowed.
|
|
18
|
+
*
|
|
19
|
+
* WHY THE CONFIDENCE IS CAPPED AT `inferred`. The derivation runs over
|
|
20
|
+
* TODAY's prerequisite table, and the table is version-controlled code that
|
|
21
|
+
* changes between two recorded events. A retro-attribution is therefore a
|
|
22
|
+
* reconstruction, not a measurement, so `exact` — which means "observed when
|
|
23
|
+
* it happened" — is never returned here. Only a forward event that stored the
|
|
24
|
+
* missing list as it was observed can carry it.
|
|
25
|
+
*
|
|
26
|
+
* WHY A COUNT MAY EXCEED THE TABLE. The recorded count is not the table's row
|
|
27
|
+
* count: the missing list is also fed by the judged-declaration refusals (the
|
|
28
|
+
* security artifact's own location) and by the handoff capsule's gate-evidence
|
|
29
|
+
* declaration (a key naming a file that is not on disk). Neither of those two
|
|
30
|
+
* sources is derivable from what a v1 event stores, so a count larger than
|
|
31
|
+
* the table's list yields `ambiguous` with the table's entries as the
|
|
32
|
+
* candidates. The candidate set is never widened with a guess, and the
|
|
33
|
+
* confidence never rises to cover the gap.
|
|
34
|
+
*/
|
|
35
|
+
import { getPrerequisitesFor, isRequestType } from '../artifacts/artifact-prerequisites.js';
|
|
36
|
+
import { ownerSkillForPath } from './owner-skill-map.js';
|
|
37
|
+
/**
|
|
38
|
+
* The prereq list for one transition, or an empty list when the request type
|
|
39
|
+
* is not one the table knows.
|
|
40
|
+
*
|
|
41
|
+
* The table is indexed by request type, and an event's type arrives from a
|
|
42
|
+
* file this module does not own — so an unknown type must answer an empty
|
|
43
|
+
* list rather than raise inside a read path.
|
|
44
|
+
*
|
|
45
|
+
* The published parameter is a `RequestType`, so this arm is reachable only
|
|
46
|
+
* from a caller that ignores the signature.
|
|
47
|
+
*/
|
|
48
|
+
function prerequisitesFor(role, newState, requestType) {
|
|
49
|
+
if (!isRequestType(requestType))
|
|
50
|
+
return [];
|
|
51
|
+
return getPrerequisitesFor(role, newState, requestType);
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The recorded count, or `null` when it cannot be read as a count.
|
|
55
|
+
*
|
|
56
|
+
* A count that is missing, negative or not a number says nothing about how
|
|
57
|
+
* many artifacts were missing, so the candidate set cannot be narrowed by it.
|
|
58
|
+
*
|
|
59
|
+
* The published parameter is a `number`, so this arm is reachable only from a
|
|
60
|
+
* caller that ignores the signature.
|
|
61
|
+
*/
|
|
62
|
+
function readableCount(value) {
|
|
63
|
+
if (typeof value !== 'number')
|
|
64
|
+
return null;
|
|
65
|
+
if (!Number.isFinite(value))
|
|
66
|
+
return null;
|
|
67
|
+
if (value < 0)
|
|
68
|
+
return null;
|
|
69
|
+
return value;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The candidate list of one transition, in the table's own order.
|
|
73
|
+
*
|
|
74
|
+
* The path is the table's `relativePath` TEMPLATE, with the `<rid>`
|
|
75
|
+
* placeholder still in it: the transition that produced the event is not
|
|
76
|
+
* available here, so the template is the most specific path that can be
|
|
77
|
+
* named. The owner lookup is a prefix match, so the placeholder does not
|
|
78
|
+
* affect it.
|
|
79
|
+
*/
|
|
80
|
+
function candidatesFor(prereqs) {
|
|
81
|
+
return prereqs.map((prereq) => ({
|
|
82
|
+
path: prereq.relativePath,
|
|
83
|
+
ownerSkill: ownerSkillForPath(prereq.relativePath)
|
|
84
|
+
}));
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Attribute one historical failure to the artifacts that could have been
|
|
88
|
+
* missing.
|
|
89
|
+
*
|
|
90
|
+
* The rules, in the order they apply:
|
|
91
|
+
*
|
|
92
|
+
* - a transition the table demands nothing for → `ambiguous`, no candidate;
|
|
93
|
+
* - a count that cannot be read → `ambiguous`, the whole list as candidates;
|
|
94
|
+
* - a count of zero → `ambiguous`, no candidate (the record says nothing
|
|
95
|
+
* was missing, so naming a candidate would contradict it);
|
|
96
|
+
* - a count equal to the list's length → `inferred`, the whole list;
|
|
97
|
+
* - any other count → `ambiguous`, the whole list as candidates.
|
|
98
|
+
*
|
|
99
|
+
* WHAT `inferred` CLAIMS AT THE THIRD RULE. The count matches the table's
|
|
100
|
+
* length, so the count is CONSISTENT WITH the whole list being the missing
|
|
101
|
+
* set — and it is not proof of that. The missing list has three sources (the
|
|
102
|
+
* prereq table, the judged-declaration refusals, the gate-evidence
|
|
103
|
+
* declaration), and a count equal to the table's length can match by
|
|
104
|
+
* coincidence while the missing entries came from the other two, leaving a
|
|
105
|
+
* table entry intact. The same holds for a one-entry list and a count of one:
|
|
106
|
+
* the single missing entry may have come from source two or three. So the
|
|
107
|
+
* label says "the count does not contradict this set", and never "these
|
|
108
|
+
* artifacts were proven missing".
|
|
109
|
+
*
|
|
110
|
+
* The last rule covers a count of one against a list of several, a count
|
|
111
|
+
* between zero and the list's length, and a count ABOVE the list's length —
|
|
112
|
+
* the last because the missing list has two further sources the table does
|
|
113
|
+
* not describe, and neither of them is derivable from a v1 event.
|
|
114
|
+
*
|
|
115
|
+
* This function never returns `exact`. That confidence belongs to a forward
|
|
116
|
+
* event, which recorded the missing list as it was observed; this one
|
|
117
|
+
* reconstructs a candidate set from today's table and can therefore only
|
|
118
|
+
* claim `inferred` or `ambiguous`.
|
|
119
|
+
*/
|
|
120
|
+
export function attributeV1Failure(opts) {
|
|
121
|
+
const prereqs = prerequisitesFor(opts.artifactRole, opts.newState, opts.requestType);
|
|
122
|
+
const typeSource = opts.typeSource;
|
|
123
|
+
if (prereqs.length === 0)
|
|
124
|
+
return { confidence: 'ambiguous', candidates: [], typeSource };
|
|
125
|
+
const candidates = candidatesFor(prereqs);
|
|
126
|
+
const count = readableCount(opts.missingCount);
|
|
127
|
+
if (count === null)
|
|
128
|
+
return { confidence: 'ambiguous', candidates, typeSource };
|
|
129
|
+
if (count === 0)
|
|
130
|
+
return { confidence: 'ambiguous', candidates: [], typeSource };
|
|
131
|
+
if (count === prereqs.length)
|
|
132
|
+
return { confidence: 'inferred', candidates, typeSource };
|
|
133
|
+
return { confidence: 'ambiguous', candidates, typeSource };
|
|
134
|
+
}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/session-metric-rows.ts`
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS FILE EXISTS. The raw event stream lives in gitignored session
|
|
5
|
+
* state, so a CI runner and a fresh clone have nothing to compare against.
|
|
6
|
+
* The per-session row is the TRACKED artifact that makes the numbers
|
|
7
|
+
* comparable across machines and across time: one JSON file per session,
|
|
8
|
+
* holding that session's aggregate numbers.
|
|
9
|
+
*
|
|
10
|
+
* WHAT THE ROW CARRIES, AND WHAT IT REFUSES TO CARRY. Counts and rates, and
|
|
11
|
+
* nothing else: no event, no free-text reason, no tool input or output. The
|
|
12
|
+
* event stream's `reason` field holds paths and code fragments, and a
|
|
13
|
+
* tracked file is the one place in this program where such text would
|
|
14
|
+
* outlive the session that produced it.
|
|
15
|
+
*
|
|
16
|
+
* WHY THE COMPLIANCE READING IS COMPUTED HERE. The compliance judge asks
|
|
17
|
+
* whether an artifact exists, and the paths it asks about carry an
|
|
18
|
+
* UNRESOLVED `<rid>` placeholder: the judge hands the declared path through
|
|
19
|
+
* verbatim, and the CALLER substitutes the request id. A caller that probes
|
|
20
|
+
* the raw string asks the filesystem about a path that contains the literal
|
|
21
|
+
* `<rid>`, every step misses, and the rate reads 0 without a single error.
|
|
22
|
+
* The substitution is therefore not left to the caller of this module: the
|
|
23
|
+
* reading is produced here, through the repository's own path resolver.
|
|
24
|
+
*
|
|
25
|
+
* WHY THE ROW IS PUBLISHED THROUGH THE SHARED ATOMIC WRITER. A tracked file
|
|
26
|
+
* that a later run reads must never be observed half-written, so the row is
|
|
27
|
+
* written to a temporary file in the same directory and renamed over the
|
|
28
|
+
* target — the same guarantee the lease store gives.
|
|
29
|
+
*/
|
|
30
|
+
import type { ComplianceSpec } from './compliance-spec.js';
|
|
31
|
+
import type { HotspotRequestTypes } from './hotspot-shared.js';
|
|
32
|
+
import type { RequestType } from '../artifacts/artifact-prerequisites.js';
|
|
33
|
+
import type { ObservabilityEvent } from './observability-service.js';
|
|
34
|
+
/** Where a session's tracked row lives, relative to the project root. */
|
|
35
|
+
export declare const SESSION_METRIC_ROWS_RELATIVE_PATH = ".peaks/observability/sessions/<sessionId>.json";
|
|
36
|
+
/** The row's schema version. */
|
|
37
|
+
export declare const SESSION_METRIC_ROW_SCHEMA_VERSION = 1;
|
|
38
|
+
/** One slice's compliance reading, inside a session row. */
|
|
39
|
+
export type SessionComplianceReading = {
|
|
40
|
+
/** The spec that was judged. */
|
|
41
|
+
readonly specId: string;
|
|
42
|
+
/** The slice the spec was judged against. */
|
|
43
|
+
readonly sliceRid: string;
|
|
44
|
+
/** The share of the spec's REQUIRED steps that ran. */
|
|
45
|
+
readonly complianceRate: number;
|
|
46
|
+
};
|
|
47
|
+
/** The tracked per-session aggregate row. */
|
|
48
|
+
export type SessionMetricRow = {
|
|
49
|
+
readonly schemaVersion: 1;
|
|
50
|
+
readonly sessionId: string;
|
|
51
|
+
readonly generatedAt: string;
|
|
52
|
+
readonly nearMissRate: number;
|
|
53
|
+
readonly passedSliceCount: number;
|
|
54
|
+
readonly nearMissSliceCount: number;
|
|
55
|
+
readonly hotspotCount: number;
|
|
56
|
+
/**
|
|
57
|
+
* The request types whose passes were never GATED.
|
|
58
|
+
*
|
|
59
|
+
* The cause of the gap between the two "passed" definitions: a type whose
|
|
60
|
+
* prerequisite table has no `qa:verdict-issued` row has no check to verify
|
|
61
|
+
* that transition against, so the check emits nothing and the pass is never
|
|
62
|
+
* gated — not gated-and-unrecorded. The row carries the cause, because the
|
|
63
|
+
* row is what outlives the session: a reader holding only the tracked file
|
|
64
|
+
* could otherwise hunt for an emitter bug that does not exist.
|
|
65
|
+
*/
|
|
66
|
+
readonly typesWithoutVerdictPrerequisite: readonly RequestType[];
|
|
67
|
+
readonly compliance: readonly SessionComplianceReading[];
|
|
68
|
+
readonly skillsBlobSha?: string;
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* Judge one slice against one compliance spec, in this session's directory.
|
|
72
|
+
*
|
|
73
|
+
* THE SUBSTITUTION HAPPENS HERE, NOT AT THE CALL SITE. The declared paths
|
|
74
|
+
* carry the `<rid>` placeholder, and the request id is put in before the
|
|
75
|
+
* filesystem is asked — through the repository's own path resolver, which
|
|
76
|
+
* also honours the numbered filename prefix the request writer stamps on.
|
|
77
|
+
*
|
|
78
|
+
* The rate is the share of the spec's REQUIRED steps that ran. A spec that
|
|
79
|
+
* declares no required step demonstrates no compliance and reads 0, which is
|
|
80
|
+
* the judge's own rule and is not restated here.
|
|
81
|
+
*/
|
|
82
|
+
export declare function judgeSessionCompliance(opts: {
|
|
83
|
+
readonly projectRoot: string;
|
|
84
|
+
readonly sessionId: string;
|
|
85
|
+
readonly spec: ComplianceSpec;
|
|
86
|
+
readonly sliceRid: string;
|
|
87
|
+
}): Promise<SessionComplianceReading>;
|
|
88
|
+
/**
|
|
89
|
+
* Build a session's row from its events.
|
|
90
|
+
*
|
|
91
|
+
* The row carries the metrics a later run compares: the near-miss rate with
|
|
92
|
+
* the two counts behind it, the size of the hotspot ranking, and the
|
|
93
|
+
* compliance readings the caller judged. It carries no event and no prose.
|
|
94
|
+
*
|
|
95
|
+
* WHY THE REQUEST TYPES ARE AN INPUT AND NOT LOOKED UP HERE. The types live
|
|
96
|
+
* in the request artifacts, and the repository has ONE reader for them — the
|
|
97
|
+
* CLI's `hotspotRequestTypes`. A second lookup inside this module would be a
|
|
98
|
+
* second copy of a reader that drifts, and a drifted copy attributes
|
|
99
|
+
* historical failures against the wrong prerequisite list. So the caller
|
|
100
|
+
* supplies the map, and this module passes it to both the near-miss metric
|
|
101
|
+
* and the hotspot aggregation.
|
|
102
|
+
*
|
|
103
|
+
* WITHOUT THEM THE ROW MISREPORTS TWICE. The near-miss denominator would
|
|
104
|
+
* name "the prereq verdict was never recorded" instead of the cause — the
|
|
105
|
+
* types whose passes were never gated at all — and the hotspot ranking would
|
|
106
|
+
* hold no retro-attributed row, so the count would read as "no hotspot" on a
|
|
107
|
+
* history that has some.
|
|
108
|
+
*/
|
|
109
|
+
export declare function buildSessionMetricRow(opts: {
|
|
110
|
+
readonly sessionId: string;
|
|
111
|
+
readonly events: readonly ObservabilityEvent[];
|
|
112
|
+
readonly requestTypes?: HotspotRequestTypes;
|
|
113
|
+
readonly skillsBlobSha?: string;
|
|
114
|
+
readonly compliance?: readonly SessionComplianceReading[];
|
|
115
|
+
}): SessionMetricRow;
|
|
116
|
+
/**
|
|
117
|
+
* The absolute path of a session's tracked row.
|
|
118
|
+
*
|
|
119
|
+
* The row lives OUTSIDE the session directory, so it cannot route through
|
|
120
|
+
* the session-dir resolver; the SAME predicate is used, so the two cannot
|
|
121
|
+
* disagree about what a legal session id is.
|
|
122
|
+
*
|
|
123
|
+
* WHY NOT THE SESSION-DIR RESOLVER. The row is tracked ON PURPOSE — the
|
|
124
|
+
* underscore convention makes a non-underscore `.peaks/` segment git-tracked
|
|
125
|
+
* source of truth, and `.peaks/_runtime/<sid>/` is gitignored. The row is
|
|
126
|
+
* the artifact a CI runner or a fresh clone compares a session against, so
|
|
127
|
+
* putting it in the runtime tree would make it untrackable and the row
|
|
128
|
+
* pointless. The session id here names a FILE inside a tracked directory, not
|
|
129
|
+
* a session runtime directory.
|
|
130
|
+
*
|
|
131
|
+
* `SESSION_METRIC_ROWS_RELATIVE_PATH` is the same path written relatively;
|
|
132
|
+
* a test pins the two together, so they cannot drift.
|
|
133
|
+
*/
|
|
134
|
+
export declare function sessionMetricRowPath(projectRoot: string, sessionId: string): string;
|
|
135
|
+
/** Publish a session's row. The write is atomic: a reader sees it whole. */
|
|
136
|
+
export declare function writeSessionMetricRow(projectRoot: string, row: SessionMetricRow): void;
|
|
137
|
+
/**
|
|
138
|
+
* The tracked row for a session, or null when the project has none.
|
|
139
|
+
*
|
|
140
|
+
* A row this build cannot read is an ERROR, not an absence: a file that is
|
|
141
|
+
* there and unreadable is a different fact from a file that is not there,
|
|
142
|
+
* and reading it as "no row" would hide a version this build does not know.
|
|
143
|
+
*/
|
|
144
|
+
export declare function readSessionMetricRow(projectRoot: string, sessionId: string): SessionMetricRow | null;
|
|
145
|
+
/**
|
|
146
|
+
* The git object id of the `skills/` tree, or undefined when there is none.
|
|
147
|
+
*
|
|
148
|
+
* The id is the skills version a session ran against, so a later run can
|
|
149
|
+
* tell whether two sessions measured the same skills. A directory that is
|
|
150
|
+
* not a git repository — or one with no committed `skills/` tree — has no
|
|
151
|
+
* version to report, and "no version" is an answer the caller can read.
|
|
152
|
+
*/
|
|
153
|
+
export declare function readSkillsBlobSha(projectRoot: string): string | undefined;
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/session-metric-rows.ts`
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS FILE EXISTS. The raw event stream lives in gitignored session
|
|
5
|
+
* state, so a CI runner and a fresh clone have nothing to compare against.
|
|
6
|
+
* The per-session row is the TRACKED artifact that makes the numbers
|
|
7
|
+
* comparable across machines and across time: one JSON file per session,
|
|
8
|
+
* holding that session's aggregate numbers.
|
|
9
|
+
*
|
|
10
|
+
* WHAT THE ROW CARRIES, AND WHAT IT REFUSES TO CARRY. Counts and rates, and
|
|
11
|
+
* nothing else: no event, no free-text reason, no tool input or output. The
|
|
12
|
+
* event stream's `reason` field holds paths and code fragments, and a
|
|
13
|
+
* tracked file is the one place in this program where such text would
|
|
14
|
+
* outlive the session that produced it.
|
|
15
|
+
*
|
|
16
|
+
* WHY THE COMPLIANCE READING IS COMPUTED HERE. The compliance judge asks
|
|
17
|
+
* whether an artifact exists, and the paths it asks about carry an
|
|
18
|
+
* UNRESOLVED `<rid>` placeholder: the judge hands the declared path through
|
|
19
|
+
* verbatim, and the CALLER substitutes the request id. A caller that probes
|
|
20
|
+
* the raw string asks the filesystem about a path that contains the literal
|
|
21
|
+
* `<rid>`, every step misses, and the rate reads 0 without a single error.
|
|
22
|
+
* The substitution is therefore not left to the caller of this module: the
|
|
23
|
+
* reading is produced here, through the repository's own path resolver.
|
|
24
|
+
*
|
|
25
|
+
* WHY THE ROW IS PUBLISHED THROUGH THE SHARED ATOMIC WRITER. A tracked file
|
|
26
|
+
* that a later run reads must never be observed half-written, so the row is
|
|
27
|
+
* written to a temporary file in the same directory and renamed over the
|
|
28
|
+
* target — the same guarantee the lease store gives.
|
|
29
|
+
*/
|
|
30
|
+
import { execFileSync } from 'node:child_process';
|
|
31
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
32
|
+
import { join } from 'node:path';
|
|
33
|
+
import { resolvePrerequisiteAbsolutePathWithFallback, sessionRootsFor } from '../artifacts/prerequisite-path-resolver.js';
|
|
34
|
+
import { atomicWriteJson } from '../ide/shared/atomic-json.js';
|
|
35
|
+
import { isSinglePathSegment } from '../session/getSessionDir.js';
|
|
36
|
+
import { judgeCompliance } from './compliance-judge.js';
|
|
37
|
+
import { aggregateHotspots } from './hotspots.js';
|
|
38
|
+
import { computeNearMiss } from './near-miss.js';
|
|
39
|
+
/** Where a session's tracked row lives, relative to the project root. */
|
|
40
|
+
export const SESSION_METRIC_ROWS_RELATIVE_PATH = '.peaks/observability/sessions/<sessionId>.json';
|
|
41
|
+
/** The row's schema version. */
|
|
42
|
+
export const SESSION_METRIC_ROW_SCHEMA_VERSION = 1;
|
|
43
|
+
/** The shape of a git object id. */
|
|
44
|
+
const GIT_OBJECT_ID_RE = /^[0-9a-f]{40}$/;
|
|
45
|
+
/**
|
|
46
|
+
* Judge one slice against one compliance spec, in this session's directory.
|
|
47
|
+
*
|
|
48
|
+
* THE SUBSTITUTION HAPPENS HERE, NOT AT THE CALL SITE. The declared paths
|
|
49
|
+
* carry the `<rid>` placeholder, and the request id is put in before the
|
|
50
|
+
* filesystem is asked — through the repository's own path resolver, which
|
|
51
|
+
* also honours the numbered filename prefix the request writer stamps on.
|
|
52
|
+
*
|
|
53
|
+
* The rate is the share of the spec's REQUIRED steps that ran. A spec that
|
|
54
|
+
* declares no required step demonstrates no compliance and reads 0, which is
|
|
55
|
+
* the judge's own rule and is not restated here.
|
|
56
|
+
*/
|
|
57
|
+
export async function judgeSessionCompliance(opts) {
|
|
58
|
+
assertSinglePathSegment(opts.sessionId);
|
|
59
|
+
const roots = sessionRootsFor(opts.projectRoot, opts.sessionId);
|
|
60
|
+
const present = new Set();
|
|
61
|
+
for (const step of opts.spec.steps) {
|
|
62
|
+
const resolved = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, { relativePath: step.verify.artifactExists, description: step.description }, opts.sliceRid);
|
|
63
|
+
if (resolved !== null)
|
|
64
|
+
present.add(step.verify.artifactExists);
|
|
65
|
+
}
|
|
66
|
+
const judged = judgeCompliance(opts.spec, (artifactPath) => present.has(artifactPath));
|
|
67
|
+
return {
|
|
68
|
+
specId: judged.specId,
|
|
69
|
+
sliceRid: opts.sliceRid,
|
|
70
|
+
complianceRate: judged.complianceRate
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Build a session's row from its events.
|
|
75
|
+
*
|
|
76
|
+
* The row carries the metrics a later run compares: the near-miss rate with
|
|
77
|
+
* the two counts behind it, the size of the hotspot ranking, and the
|
|
78
|
+
* compliance readings the caller judged. It carries no event and no prose.
|
|
79
|
+
*
|
|
80
|
+
* WHY THE REQUEST TYPES ARE AN INPUT AND NOT LOOKED UP HERE. The types live
|
|
81
|
+
* in the request artifacts, and the repository has ONE reader for them — the
|
|
82
|
+
* CLI's `hotspotRequestTypes`. A second lookup inside this module would be a
|
|
83
|
+
* second copy of a reader that drifts, and a drifted copy attributes
|
|
84
|
+
* historical failures against the wrong prerequisite list. So the caller
|
|
85
|
+
* supplies the map, and this module passes it to both the near-miss metric
|
|
86
|
+
* and the hotspot aggregation.
|
|
87
|
+
*
|
|
88
|
+
* WITHOUT THEM THE ROW MISREPORTS TWICE. The near-miss denominator would
|
|
89
|
+
* name "the prereq verdict was never recorded" instead of the cause — the
|
|
90
|
+
* types whose passes were never gated at all — and the hotspot ranking would
|
|
91
|
+
* hold no retro-attributed row, so the count would read as "no hotspot" on a
|
|
92
|
+
* history that has some.
|
|
93
|
+
*/
|
|
94
|
+
export function buildSessionMetricRow(opts) {
|
|
95
|
+
const requestTypes = opts.requestTypes ?? new Map();
|
|
96
|
+
const nearMiss = computeNearMiss(opts.events, requestTypes);
|
|
97
|
+
const hotspots = aggregateHotspots(opts.events, requestTypes);
|
|
98
|
+
return {
|
|
99
|
+
schemaVersion: SESSION_METRIC_ROW_SCHEMA_VERSION,
|
|
100
|
+
sessionId: opts.sessionId,
|
|
101
|
+
generatedAt: new Date().toISOString(),
|
|
102
|
+
nearMissRate: nearMiss.nearMissRate,
|
|
103
|
+
passedSliceCount: nearMiss.passedSliceCount,
|
|
104
|
+
nearMissSliceCount: nearMiss.nearMissSliceCount,
|
|
105
|
+
hotspotCount: hotspots.length,
|
|
106
|
+
typesWithoutVerdictPrerequisite: nearMiss.denominator.difference?.typesWithoutVerdictPrerequisite ?? [],
|
|
107
|
+
compliance: opts.compliance ?? [],
|
|
108
|
+
...(opts.skillsBlobSha === undefined ? {} : { skillsBlobSha: opts.skillsBlobSha })
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* The absolute path of a session's tracked row.
|
|
113
|
+
*
|
|
114
|
+
* The row lives OUTSIDE the session directory, so it cannot route through
|
|
115
|
+
* the session-dir resolver; the SAME predicate is used, so the two cannot
|
|
116
|
+
* disagree about what a legal session id is.
|
|
117
|
+
*
|
|
118
|
+
* WHY NOT THE SESSION-DIR RESOLVER. The row is tracked ON PURPOSE — the
|
|
119
|
+
* underscore convention makes a non-underscore `.peaks/` segment git-tracked
|
|
120
|
+
* source of truth, and `.peaks/_runtime/<sid>/` is gitignored. The row is
|
|
121
|
+
* the artifact a CI runner or a fresh clone compares a session against, so
|
|
122
|
+
* putting it in the runtime tree would make it untrackable and the row
|
|
123
|
+
* pointless. The session id here names a FILE inside a tracked directory, not
|
|
124
|
+
* a session runtime directory.
|
|
125
|
+
*
|
|
126
|
+
* `SESSION_METRIC_ROWS_RELATIVE_PATH` is the same path written relatively;
|
|
127
|
+
* a test pins the two together, so they cannot drift.
|
|
128
|
+
*/
|
|
129
|
+
export function sessionMetricRowPath(projectRoot, sessionId) {
|
|
130
|
+
assertSinglePathSegment(sessionId);
|
|
131
|
+
return join(projectRoot, '.peaks', 'observability', 'sessions', `${sessionId}.json`);
|
|
132
|
+
}
|
|
133
|
+
/** Publish a session's row. The write is atomic: a reader sees it whole. */
|
|
134
|
+
export function writeSessionMetricRow(projectRoot, row) {
|
|
135
|
+
atomicWriteJson(sessionMetricRowPath(projectRoot, row.sessionId), row);
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The tracked row for a session, or null when the project has none.
|
|
139
|
+
*
|
|
140
|
+
* A row this build cannot read is an ERROR, not an absence: a file that is
|
|
141
|
+
* there and unreadable is a different fact from a file that is not there,
|
|
142
|
+
* and reading it as "no row" would hide a version this build does not know.
|
|
143
|
+
*/
|
|
144
|
+
export function readSessionMetricRow(projectRoot, sessionId) {
|
|
145
|
+
const path = sessionMetricRowPath(projectRoot, sessionId);
|
|
146
|
+
if (!existsSync(path))
|
|
147
|
+
return null;
|
|
148
|
+
const row = JSON.parse(readFileSync(path, 'utf8'));
|
|
149
|
+
const version = row.schemaVersion;
|
|
150
|
+
if (version !== SESSION_METRIC_ROW_SCHEMA_VERSION) {
|
|
151
|
+
throw new Error(`session metric row ${path} declares schema version ${String(version)}, ` +
|
|
152
|
+
'which this build does not read');
|
|
153
|
+
}
|
|
154
|
+
return row;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* The git object id of the `skills/` tree, or undefined when there is none.
|
|
158
|
+
*
|
|
159
|
+
* The id is the skills version a session ran against, so a later run can
|
|
160
|
+
* tell whether two sessions measured the same skills. A directory that is
|
|
161
|
+
* not a git repository — or one with no committed `skills/` tree — has no
|
|
162
|
+
* version to report, and "no version" is an answer the caller can read.
|
|
163
|
+
*/
|
|
164
|
+
export function readSkillsBlobSha(projectRoot) {
|
|
165
|
+
let sha = '';
|
|
166
|
+
try {
|
|
167
|
+
sha = execFileSync('git', ['rev-parse', 'HEAD:skills'], {
|
|
168
|
+
cwd: projectRoot,
|
|
169
|
+
encoding: 'utf8',
|
|
170
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
171
|
+
windowsHide: true
|
|
172
|
+
}).trim();
|
|
173
|
+
}
|
|
174
|
+
catch {
|
|
175
|
+
sha = '';
|
|
176
|
+
}
|
|
177
|
+
return GIT_OBJECT_ID_RE.test(sha) ? sha : undefined;
|
|
178
|
+
}
|
|
179
|
+
/** Refuse a session id that is not a single path segment. */
|
|
180
|
+
function assertSinglePathSegment(sessionId) {
|
|
181
|
+
if (!isSinglePathSegment(sessionId)) {
|
|
182
|
+
throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
|
|
183
|
+
}
|
|
184
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.23",
|
|
4
4
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
5
5
|
"author": "SquabbyZ",
|
|
6
6
|
"keywords": [
|
|
@@ -132,10 +132,10 @@
|
|
|
132
132
|
"picomatch": "4.0.7",
|
|
133
133
|
"yaml": "^2.9.1",
|
|
134
134
|
"zod": "^4.6.7",
|
|
135
|
-
"peaks-loop-internal-runtime": "0.0.
|
|
136
|
-
"peaks-loop-mut": "0.1.
|
|
137
|
-
"peaks-loop-shared": "0.0.
|
|
138
|
-
"peaks-loop-shared-channel": "0.0.
|
|
135
|
+
"peaks-loop-internal-runtime": "0.0.63",
|
|
136
|
+
"peaks-loop-mut": "0.1.77",
|
|
137
|
+
"peaks-loop-shared": "0.0.112",
|
|
138
|
+
"peaks-loop-shared-channel": "0.0.80"
|
|
139
139
|
},
|
|
140
140
|
"devDependencies": {
|
|
141
141
|
"@changesets/cli": "2.31.1",
|