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,211 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The gate layer's event vocabulary: the stable ids the RD transition gates
|
|
3
|
+
* are known by, and the ONE function that writes a gate decision into the
|
|
4
|
+
* observability stream.
|
|
5
|
+
*
|
|
6
|
+
* WHY THE IDS ARE STABLE STRINGS. A gate decision is only useful if a reader
|
|
7
|
+
* can ask "which gate blocked?" — across sessions, and across versions of
|
|
8
|
+
* this repository. A reader that has to recognise the CODE that produced the
|
|
9
|
+
* event cannot ask that question at all, which is how the gate layer stayed
|
|
10
|
+
* invisible until now.
|
|
11
|
+
*
|
|
12
|
+
* WHY THE EMITTER LIVES HERE AND NOT IN THE OBSERVABILITY SERVICE. The service
|
|
13
|
+
* module is at its file-size cap, and this file owns the gate vocabulary: the
|
|
14
|
+
* ids, the outcomes, and the prose the bypass note uses for them. The service
|
|
15
|
+
* keeps the schema-and-write half it has always owned.
|
|
16
|
+
*
|
|
17
|
+
* THE RECORDER IS CURRIED. One transition has ONE identity — the project, the
|
|
18
|
+
* session, the slice and the phase — and every decision it makes shares it.
|
|
19
|
+
* The recorder binds that identity once, so a decision costs one line at the
|
|
20
|
+
* call site and cannot forget which slice it belongs to.
|
|
21
|
+
*
|
|
22
|
+
* FIRE-AND-FORGET BY CONTRACT. The gate's verdict must not change because an
|
|
23
|
+
* event could not be written, so nothing here throws.
|
|
24
|
+
*/
|
|
25
|
+
import { emitObservabilityEvent } from '../observability/observability-service.js';
|
|
26
|
+
import { OBSERVABILITY_SCHEMA_VERSION } from '../observability/observability-schema.js';
|
|
27
|
+
/**
|
|
28
|
+
* Every gate id, as a list.
|
|
29
|
+
*
|
|
30
|
+
* A consumer that has to RECOGNISE a gate id cannot re-type the union: a
|
|
31
|
+
* second copy of the vocabulary is a list that rots, and it rots silently —
|
|
32
|
+
* a gate id added upstream would not be in the copy, so a gate that PASSED
|
|
33
|
+
* would be read as "not a gate we know" and never counted as evaluated.
|
|
34
|
+
*/
|
|
35
|
+
export const RD_GATE_IDS = [
|
|
36
|
+
'file-size-ratchet',
|
|
37
|
+
'declared-type-corroboration',
|
|
38
|
+
'claim-table'
|
|
39
|
+
];
|
|
40
|
+
/**
|
|
41
|
+
* Every gate outcome, as a list.
|
|
42
|
+
*
|
|
43
|
+
* A consumer that has to RECOGNISE an outcome cannot re-type the union: a
|
|
44
|
+
* second copy of the vocabulary is a list that rots, and it rots SILENTLY —
|
|
45
|
+
* an outcome added upstream would not be in the copy, so the reader would
|
|
46
|
+
* treat a `pass` as "not a pass" and report a slice that evaluated every gate
|
|
47
|
+
* as one that skipped one.
|
|
48
|
+
*/
|
|
49
|
+
export const RD_GATE_OUTCOMES = ['pass', 'block', 'bypass'];
|
|
50
|
+
/**
|
|
51
|
+
* Whether a value is one of the gate outcomes this build knows.
|
|
52
|
+
*
|
|
53
|
+
* An outcome this build does not know is UNREADABLE, not "not evaluated" —
|
|
54
|
+
* the two are different facts, and only the second one is a finding.
|
|
55
|
+
*/
|
|
56
|
+
export function isRdGateOutcome(value) {
|
|
57
|
+
return typeof value === 'string' && RD_GATE_OUTCOMES.includes(value);
|
|
58
|
+
}
|
|
59
|
+
/** The prose each gate id carries in the bypass note. */
|
|
60
|
+
const GATE_LABELS = {
|
|
61
|
+
'file-size-ratchet': 'file-size ratchet',
|
|
62
|
+
'declared-type-corroboration': 'declared-type corroboration',
|
|
63
|
+
'claim-table': 'claim table'
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* The gates the bypass NOTE names, per phase. This is NOT the live set: the
|
|
67
|
+
* note names the gates a reader is TOLD about, while `liveGateIds` is the set
|
|
68
|
+
* of checks that were actually APPLICABLE — a gate that was live and skipped
|
|
69
|
+
* has to be recorded even when the note does not name it.
|
|
70
|
+
*
|
|
71
|
+
* The note and this list are two readings of ONE table: the note's prose is
|
|
72
|
+
* built from these ids, so the text that names the skipped gates cannot drift
|
|
73
|
+
* from the prose the artifact carries.
|
|
74
|
+
*/
|
|
75
|
+
const NOTED_GATE_IDS = {
|
|
76
|
+
implemented: ['file-size-ratchet', 'declared-type-corroboration'],
|
|
77
|
+
'qa-handoff': ['declared-type-corroboration'],
|
|
78
|
+
'handed-off': ['declared-type-corroboration']
|
|
79
|
+
};
|
|
80
|
+
/** The ids of the gates the bypass note names, in the note's order. */
|
|
81
|
+
export function notedGateIds(phase) {
|
|
82
|
+
return NOTED_GATE_IDS[phase];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* The gates that are LIVE for a transition: the checks that WOULD run if the
|
|
86
|
+
* transition were not bypassed.
|
|
87
|
+
*
|
|
88
|
+
* A live gate that produced no verdict was SKIPPED; a gate that is not live
|
|
89
|
+
* was never applicable to that transition. The two must be tellable apart, or
|
|
90
|
+
* a skipped gate is indistinguishable from a gate that does not exist for the
|
|
91
|
+
* slice — the invisible state this stream exists to remove.
|
|
92
|
+
*
|
|
93
|
+
* DERIVED FROM THE SOURCE, not from the note. `runRdTransitionGates` runs the
|
|
94
|
+
* size ratchet at `implemented` and, for a declared type that is NOT
|
|
95
|
+
* tooling-only, runs NOTHING else — the type rule is a no-op there and the
|
|
96
|
+
* claim table is never read. For a tooling-only declared type the type rule
|
|
97
|
+
* and the claim table run at every phase, and the size ratchet joins them at
|
|
98
|
+
* `implemented`.
|
|
99
|
+
*/
|
|
100
|
+
const LIVE_GATE_IDS = {
|
|
101
|
+
implemented: {
|
|
102
|
+
tooling: ['file-size-ratchet', 'declared-type-corroboration', 'claim-table'],
|
|
103
|
+
product: ['file-size-ratchet']
|
|
104
|
+
},
|
|
105
|
+
'qa-handoff': {
|
|
106
|
+
tooling: ['declared-type-corroboration', 'claim-table'],
|
|
107
|
+
product: []
|
|
108
|
+
},
|
|
109
|
+
'handed-off': {
|
|
110
|
+
tooling: ['declared-type-corroboration', 'claim-table'],
|
|
111
|
+
product: []
|
|
112
|
+
}
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* The gates that are live for a transition, by its phase and by whether the
|
|
116
|
+
* declared type is tooling-only.
|
|
117
|
+
*/
|
|
118
|
+
export function liveGateIds(phase, judged) {
|
|
119
|
+
return LIVE_GATE_IDS[phase][judged ? 'tooling' : 'product'];
|
|
120
|
+
}
|
|
121
|
+
/** The prose the bypass note uses for one gate id. */
|
|
122
|
+
export function gateLabel(gateId) {
|
|
123
|
+
return GATE_LABELS[gateId];
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* What each gate was NOT able to check, when the transition was bypassed.
|
|
127
|
+
*/
|
|
128
|
+
const BYPASS_DETAIL = {
|
|
129
|
+
'file-size-ratchet': ', so no file was measured against the cap',
|
|
130
|
+
'declared-type-corroboration': ', so the declared type was never judged against the change set',
|
|
131
|
+
'claim-table': ', so no rid claim was checked against the working tree'
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* Why ONE gate did not run, when the transition was bypassed.
|
|
135
|
+
*
|
|
136
|
+
* PER GATE, not the shared note: the note the artifact carries names the
|
|
137
|
+
* skipped gates in prose, and it does not name every gate that stood down —
|
|
138
|
+
* so it cannot be the reason for all of them. The note stays the prose; this
|
|
139
|
+
* is the machine-facing explanation.
|
|
140
|
+
*/
|
|
141
|
+
export function bypassReason(gateId, phase) {
|
|
142
|
+
return (`the ${gateLabel(gateId)} was not evaluated: --allow-incomplete bypassed the rd ` +
|
|
143
|
+
`${phase} gates${BYPASS_DETAIL[gateId]}`);
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Why the claim table could not be evaluated. The causes are DIFFERENT facts
|
|
147
|
+
* — no artifact at all, or a table some rid never filled in — and a consumer
|
|
148
|
+
* has to be able to tell them apart. (The third cause, a diff that could not
|
|
149
|
+
* be obtained, is a `block` with its own `violationKind`.)
|
|
150
|
+
*/
|
|
151
|
+
export function claimTableReason(artifactCount, missingCount) {
|
|
152
|
+
if (artifactCount === 0) {
|
|
153
|
+
return ('the claim table could not be evaluated: the session has no RD artifact, so no rid ' +
|
|
154
|
+
'declares the paths it touched and an unclaimed source change cannot be ruled out');
|
|
155
|
+
}
|
|
156
|
+
return (`the claim table could not be evaluated: ${missingCount} of ${artifactCount} RD artifacts ` +
|
|
157
|
+
'declare no "## Changed paths" section, and an incomplete table cannot prove that no ' +
|
|
158
|
+
'source change is unclaimed');
|
|
159
|
+
}
|
|
160
|
+
/** Bind the transition's identity, once. */
|
|
161
|
+
export function rdGateRecorder(context) {
|
|
162
|
+
return (gateId, outcome, decision) => {
|
|
163
|
+
emitRdGateEvent({
|
|
164
|
+
...context,
|
|
165
|
+
gateId,
|
|
166
|
+
outcome,
|
|
167
|
+
violationKind: decision?.violationKind,
|
|
168
|
+
reason: decision?.reason
|
|
169
|
+
});
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Record ONE gate decision in the session's observability stream.
|
|
174
|
+
*
|
|
175
|
+
* The detail carries the DECLARED TYPE, not a derived "was this slice
|
|
176
|
+
* tooling-only" boolean: the type is the more informative datum, and a consumer
|
|
177
|
+
* that has to re-read the request artifact to learn whether a gate was live
|
|
178
|
+
* cannot reproduce the answer from the events alone.
|
|
179
|
+
*
|
|
180
|
+
* The optional fields carry `| undefined` on purpose: this repository
|
|
181
|
+
* compiles with `exactOptionalPropertyTypes`, so a caller that forwards a
|
|
182
|
+
* possibly-absent value could not pass it to a plain optional property.
|
|
183
|
+
*/
|
|
184
|
+
export function emitRdGateEvent(opts) {
|
|
185
|
+
const detail = {
|
|
186
|
+
gateId: opts.gateId,
|
|
187
|
+
phase: opts.phase,
|
|
188
|
+
declaredType: opts.declaredType,
|
|
189
|
+
outcome: opts.outcome
|
|
190
|
+
};
|
|
191
|
+
if (opts.violationKind !== undefined)
|
|
192
|
+
detail['violationKind'] = opts.violationKind;
|
|
193
|
+
if (opts.reason !== undefined)
|
|
194
|
+
detail['reason'] = opts.reason;
|
|
195
|
+
try {
|
|
196
|
+
emitObservabilityEvent({
|
|
197
|
+
schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
|
|
198
|
+
ts: new Date().toISOString(),
|
|
199
|
+
sessionId: opts.sessionId,
|
|
200
|
+
category: 'gate',
|
|
201
|
+
sliceRid: opts.sliceRid,
|
|
202
|
+
detail
|
|
203
|
+
}, { projectRoot: opts.projectRoot });
|
|
204
|
+
}
|
|
205
|
+
catch (error) {
|
|
206
|
+
// Fire-and-forget: the gate's verdict must not change because the event
|
|
207
|
+
// could not be written. `error` is held so the block is not an empty
|
|
208
|
+
// catch — swallowing it IS the contract, not an oversight.
|
|
209
|
+
void error;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
@@ -24,6 +24,12 @@
|
|
|
24
24
|
* table cannot prove "nobody claimed it", and guessing there would blame one
|
|
25
25
|
* slice for another's change. When it does not run, the returned note says so:
|
|
26
26
|
* a silently skipped check is indistinguishable from a passing one.
|
|
27
|
+
*
|
|
28
|
+
* EVERY DECISION IS RECORDED. Each gate that runs emits one `gate` event
|
|
29
|
+
* carrying its stable id, the phase, the declared type and what it decided
|
|
30
|
+
* (`pass` / `block` / `bypass`), so the layer that decides can be read back
|
|
31
|
+
* instead of inferred from the absence of an error. A refusal is recorded
|
|
32
|
+
* BEFORE it is thrown.
|
|
27
33
|
*/
|
|
28
34
|
import type { RequestType } from './artifact-prerequisites.js';
|
|
29
35
|
import { type RequestArtifactState } from './request-artifact-state-helpers.js';
|
|
@@ -6,6 +6,7 @@ import { isArtifactWorkspaceFile } from '../scan/type-sanity-service.js';
|
|
|
6
6
|
import { listSessionRdArtifactIds, readRidChangeClaims } from '../scan/rid-change-claims.js';
|
|
7
7
|
import { slugifyDescription } from '../../shared/incrementing-number.js';
|
|
8
8
|
import { normalizePath } from '../../shared/path-utils.js';
|
|
9
|
+
import { bypassReason, claimTableReason, gateLabel, liveGateIds, notedGateIds, rdGateRecorder } from './rd-gate-event.js';
|
|
9
10
|
/**
|
|
10
11
|
* True for the three states the RD gates judge. A type PREDICATE, so a caller
|
|
11
12
|
* that filters on it keeps the narrowed state — the old inline `||` chain did
|
|
@@ -28,19 +29,36 @@ export class TypeCorroborationViolationError extends Error {
|
|
|
28
29
|
/** Written into the artifact when `--allow-incomplete` skips a gate that COULD
|
|
29
30
|
* have judged this type: a silent bypass is indistinguishable from a pass. */
|
|
30
31
|
export function rdGatesBypassNote(phase) {
|
|
31
|
-
const gates = phase
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
const gates = notedGateIds(phase)
|
|
33
|
+
.map((gateId) => gateLabel(gateId))
|
|
34
|
+
.join(', ');
|
|
34
35
|
return (`bypassed the rd ${phase} gates (${gates}) via --allow-incomplete; ` +
|
|
35
36
|
'none of them was evaluated');
|
|
36
37
|
}
|
|
38
|
+
/** The gates a bypassed transition skipped, each with its own event: every
|
|
39
|
+
* gate that was LIVE for the transition and did not run. The live set is not
|
|
40
|
+
* the note's list — see `liveGateIds`. */
|
|
41
|
+
function reportBypass(record, phase, judged) {
|
|
42
|
+
for (const gateId of liveGateIds(phase, judged)) {
|
|
43
|
+
record(gateId, 'bypass', { reason: bypassReason(gateId, phase) });
|
|
44
|
+
}
|
|
45
|
+
return judged ? rdGatesBypassNote(phase) : null;
|
|
46
|
+
}
|
|
37
47
|
/** The shared read, or the fail-closed verdict built from the same message. */
|
|
38
|
-
function readOrRefuse(projectRoot, declaredType) {
|
|
48
|
+
function readOrRefuse(record, projectRoot, declaredType) {
|
|
39
49
|
try {
|
|
40
50
|
return readGitChangeSet(projectRoot, 'HEAD');
|
|
41
51
|
}
|
|
42
52
|
catch {
|
|
43
|
-
|
|
53
|
+
const verdict = diffUnavailableVerdict(declaredType);
|
|
54
|
+
// BEFORE the throw: after it the event would never fire, and "the diff
|
|
55
|
+
// could not be read" is one of the facts this stream exists to keep. IT IS
|
|
56
|
+
// THE CLAIM TABLE'S BLOCK, because the criterion is which gate could not be
|
|
57
|
+
// EVALUATED: the working-tree diff is the precondition the claim table
|
|
58
|
+
// needs. The verdict function living in the type-corroboration module is
|
|
59
|
+
// incidental.
|
|
60
|
+
record('claim-table', 'block', { violationKind: 'diff-unavailable', reason: verdict.message });
|
|
61
|
+
throw new TypeCorroborationViolationError(declaredType, verdict);
|
|
44
62
|
}
|
|
45
63
|
}
|
|
46
64
|
/** The note written when the anti-lie fallback could not run. */
|
|
@@ -85,15 +103,21 @@ function judgeDeclaredType(options) {
|
|
|
85
103
|
if (tableComplete) {
|
|
86
104
|
const unclaimed = unclaimedSourcePaths(options.worktreePaths, claims);
|
|
87
105
|
if (unclaimed.length > 0) {
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
};
|
|
106
|
+
const message = unclaimedMessage(options.declaredType, unclaimed);
|
|
107
|
+
options.record('claim-table', 'block', {
|
|
108
|
+
violationKind: 'source-unclaimed',
|
|
109
|
+
reason: message
|
|
110
|
+
});
|
|
111
|
+
return { ok: false, kind: 'source-unclaimed', message };
|
|
93
112
|
}
|
|
113
|
+
options.record('claim-table', 'pass');
|
|
94
114
|
}
|
|
95
115
|
else {
|
|
96
116
|
note = fallbackDisabledNote(options.sessionId, missing.length, artifactIds.length);
|
|
117
|
+
// The fallback STOOD DOWN — it did not pass. A bypass says so; a pass
|
|
118
|
+
// would claim a check that never ran, and the reason says WHICH stand-down.
|
|
119
|
+
const standDown = claimTableReason(artifactIds.length, missing.length);
|
|
120
|
+
options.record('claim-table', 'bypass', { reason: standDown });
|
|
97
121
|
}
|
|
98
122
|
// (B) The rid's own declaration; the whole working tree when it declared none.
|
|
99
123
|
const scope = own ?? options.worktreePaths;
|
|
@@ -107,27 +131,49 @@ function judgeDeclaredType(options) {
|
|
|
107
131
|
// anti-lie fallback stood down, a reader of the refusal alone must not be
|
|
108
132
|
// left thinking it was in force.
|
|
109
133
|
const message = note === null ? verdict.message : `${verdict.message} ${note}`;
|
|
134
|
+
const refusal = { violationKind: verdict.kind, reason: message };
|
|
135
|
+
options.record('declared-type-corroboration', 'block', refusal);
|
|
110
136
|
return { ok: false, kind: verdict.kind, message };
|
|
111
137
|
}
|
|
138
|
+
options.record('declared-type-corroboration', 'pass');
|
|
112
139
|
return { ok: true, note };
|
|
113
140
|
}
|
|
141
|
+
/** The size ratchet, and the event that records what it decided. The refusal
|
|
142
|
+
* is recorded BEFORE the throw — after it the event would never fire. */
|
|
143
|
+
function runSizeRatchet(record, projectRoot, changedFiles) {
|
|
144
|
+
const size = changedFiles === undefined
|
|
145
|
+
? scanFileSize({ projectRoot })
|
|
146
|
+
: scanFileSize({ projectRoot, changedFiles });
|
|
147
|
+
if (!size.ok) {
|
|
148
|
+
const error = new FileSizeViolationError(size.violations);
|
|
149
|
+
record('file-size-ratchet', 'block', { reason: error.message });
|
|
150
|
+
throw error;
|
|
151
|
+
}
|
|
152
|
+
record('file-size-ratchet', 'pass');
|
|
153
|
+
}
|
|
114
154
|
export function runRdTransitionGates(options) {
|
|
155
|
+
const record = rdGateRecorder({
|
|
156
|
+
projectRoot: options.projectRoot,
|
|
157
|
+
sessionId: options.sessionId,
|
|
158
|
+
sliceRid: options.requestId,
|
|
159
|
+
phase: options.phase,
|
|
160
|
+
declaredType: options.declaredType
|
|
161
|
+
});
|
|
115
162
|
const judged = isToolingOnlyDeclaredType(options.declaredType);
|
|
116
|
-
if (options.allowIncomplete)
|
|
117
|
-
return
|
|
163
|
+
if (options.allowIncomplete) {
|
|
164
|
+
return reportBypass(record, options.phase, judged);
|
|
165
|
+
}
|
|
118
166
|
if (!judged) {
|
|
119
167
|
// The size ratchet still runs at implemented; the type rule is a no-op here.
|
|
120
|
-
if (options.phase === 'implemented')
|
|
121
|
-
|
|
122
|
-
if (!size.ok)
|
|
123
|
-
throw new FileSizeViolationError(size.violations);
|
|
124
|
-
}
|
|
168
|
+
if (options.phase === 'implemented')
|
|
169
|
+
runSizeRatchet(record, options.projectRoot);
|
|
125
170
|
return null;
|
|
126
171
|
}
|
|
127
172
|
// ONE enumeration for the whole transition: the type rule judges the rid's own
|
|
128
173
|
// paths against the same working-tree read the size ratchet measures.
|
|
129
|
-
const changeSet = readOrRefuse(options.projectRoot, options.declaredType);
|
|
174
|
+
const changeSet = readOrRefuse(record, options.projectRoot, options.declaredType);
|
|
130
175
|
const verdict = judgeDeclaredType({
|
|
176
|
+
record,
|
|
131
177
|
projectRoot: options.projectRoot,
|
|
132
178
|
declaredType: options.declaredType,
|
|
133
179
|
requestId: options.requestId,
|
|
@@ -137,12 +183,7 @@ export function runRdTransitionGates(options) {
|
|
|
137
183
|
if (!verdict.ok)
|
|
138
184
|
throw new TypeCorroborationViolationError(options.declaredType, verdict);
|
|
139
185
|
if (options.phase === 'implemented') {
|
|
140
|
-
|
|
141
|
-
projectRoot: options.projectRoot,
|
|
142
|
-
changedFiles: changeSet.changedFiles
|
|
143
|
-
});
|
|
144
|
-
if (!size.ok)
|
|
145
|
-
throw new FileSizeViolationError(size.violations);
|
|
186
|
+
runSizeRatchet(record, options.projectRoot, changeSet.changedFiles);
|
|
146
187
|
}
|
|
147
188
|
return verdict.note;
|
|
148
189
|
}
|
|
@@ -16,6 +16,16 @@ export type StatusAggregate = {
|
|
|
16
16
|
totalSlices: number;
|
|
17
17
|
successCount: number;
|
|
18
18
|
failCount: number;
|
|
19
|
+
/**
|
|
20
|
+
* Slices that reached a state which is neither a success terminal state nor
|
|
21
|
+
* a terminal failure — the ones stuck mid-flight, e.g. at `qa-handoff`.
|
|
22
|
+
*
|
|
23
|
+
* The three outcome counts partition the slice set, so
|
|
24
|
+
* `successCount + failCount + stalledCount === totalSlices` holds for every
|
|
25
|
+
* event set. A slice whose transitions recorded no final state at all also
|
|
26
|
+
* lands here: it reached no terminal outcome either.
|
|
27
|
+
*/
|
|
28
|
+
readonly stalledCount: number;
|
|
19
29
|
repairCyclePeak: number;
|
|
20
30
|
fanoutCostTotal: number;
|
|
21
31
|
};
|
|
@@ -30,6 +40,17 @@ export type SliceRollup = {
|
|
|
30
40
|
repairCycleCount: number;
|
|
31
41
|
success: boolean;
|
|
32
42
|
};
|
|
43
|
+
/**
|
|
44
|
+
* How one slice ended.
|
|
45
|
+
*
|
|
46
|
+
* The three outcomes PARTITION the slice set: a slice that reached a
|
|
47
|
+
* terminal success state, a slice that reached a terminal failure state, and
|
|
48
|
+
* a slice that reached NEITHER — it advanced partway and stopped (at
|
|
49
|
+
* `qa-handoff`, typically). `stalled` is not a failure: the work was never
|
|
50
|
+
* concluded, and the counts must say so rather than drop the slice from the
|
|
51
|
+
* accounting.
|
|
52
|
+
*/
|
|
53
|
+
export type SliceOutcome = 'success' | 'failed' | 'stalled';
|
|
33
54
|
export type FanoutBreakdown = {
|
|
34
55
|
total: number;
|
|
35
56
|
perRole: Record<ObservabilitySubagentRole, number>;
|
|
@@ -14,11 +14,21 @@
|
|
|
14
14
|
* builds the read-side surface so Slice C is purely additive.
|
|
15
15
|
*/
|
|
16
16
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
17
|
-
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
17
|
+
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceOutcome, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
18
18
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
19
19
|
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
20
20
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
21
|
-
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
|
+
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceOutcome, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
22
|
+
/**
|
|
23
|
+
* How one slice ended, from its rollup.
|
|
24
|
+
*
|
|
25
|
+
* ONE spelling of the three outcomes, shared by the status counts and by the
|
|
26
|
+
* report's slice table: a slice that reached a terminal success state, a slice
|
|
27
|
+
* that reached a terminal failure state, and a slice that reached NEITHER — it
|
|
28
|
+
* advanced partway and stopped (at `qa-handoff`, typically). The last is not a
|
|
29
|
+
* failure, so it is not counted as one and is not drawn as one.
|
|
30
|
+
*/
|
|
31
|
+
export declare function sliceOutcome(rollup: SliceRollup): SliceOutcome;
|
|
22
32
|
export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
|
|
23
33
|
export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
|
|
24
34
|
export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
|
|
@@ -70,6 +70,22 @@ function rollupSlices(events) {
|
|
|
70
70
|
return bySlice;
|
|
71
71
|
}
|
|
72
72
|
// ----- public aggregations -----
|
|
73
|
+
/**
|
|
74
|
+
* How one slice ended, from its rollup.
|
|
75
|
+
*
|
|
76
|
+
* ONE spelling of the three outcomes, shared by the status counts and by the
|
|
77
|
+
* report's slice table: a slice that reached a terminal success state, a slice
|
|
78
|
+
* that reached a terminal failure state, and a slice that reached NEITHER — it
|
|
79
|
+
* advanced partway and stopped (at `qa-handoff`, typically). The last is not a
|
|
80
|
+
* failure, so it is not counted as one and is not drawn as one.
|
|
81
|
+
*/
|
|
82
|
+
export function sliceOutcome(rollup) {
|
|
83
|
+
if (rollup.success)
|
|
84
|
+
return 'success';
|
|
85
|
+
if (rollup.finalState !== null && TERMINAL_FAIL_STATES.has(rollup.finalState))
|
|
86
|
+
return 'failed';
|
|
87
|
+
return 'stalled';
|
|
88
|
+
}
|
|
73
89
|
export function aggregateStatus(events) {
|
|
74
90
|
const bySlice = rollupSlices(events);
|
|
75
91
|
const metrics = computeSliceRepairMetrics(events);
|
|
@@ -80,14 +96,22 @@ export function aggregateStatus(events) {
|
|
|
80
96
|
if (cycles > repairCyclePeak)
|
|
81
97
|
repairCyclePeak = cycles;
|
|
82
98
|
}
|
|
83
|
-
|
|
84
|
-
|
|
99
|
+
// The three outcome buckets come from the ONE outcome spelling above, so
|
|
100
|
+
// they partition the slice set: every slice lands in exactly one bucket and
|
|
101
|
+
// `successCount + failCount + stalledCount === totalSlices` holds for every
|
|
102
|
+
// event set. Before the third bucket existed, a slice stuck at `qa-handoff`
|
|
103
|
+
// was in NEITHER the success nor the fail count and the summary reported
|
|
104
|
+
// fewer outcomes than the slice table showed rows.
|
|
105
|
+
const successCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'success').length;
|
|
106
|
+
const failCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'failed').length;
|
|
107
|
+
const stalledCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'stalled').length;
|
|
85
108
|
const fanoutCostTotal = events.filter((e) => e.category === 'dispatch').length;
|
|
86
109
|
return {
|
|
87
110
|
totalEvents: events.length,
|
|
88
111
|
totalSlices: bySlice.size,
|
|
89
112
|
successCount,
|
|
90
113
|
failCount,
|
|
114
|
+
stalledCount,
|
|
91
115
|
repairCyclePeak,
|
|
92
116
|
fanoutCostTotal
|
|
93
117
|
};
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/compliance-judge.ts`
|
|
3
|
+
*
|
|
4
|
+
* The judge: given a compliance spec and a way to ask whether an artifact
|
|
5
|
+
* exists, report which declared steps actually ran.
|
|
6
|
+
*
|
|
7
|
+
* WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
|
|
8
|
+
* compliance rate says "the checks the skill PROMISED ran". The difference is
|
|
9
|
+
* the point of the campaign: a slice can pass its gate while a step the skill
|
|
10
|
+
* declared never happened, and only the second reading sees that.
|
|
11
|
+
*
|
|
12
|
+
* THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
|
|
13
|
+
* is asked through the `exists` callback the caller supplies. That is what
|
|
14
|
+
* makes one spec judgeable against a real workspace, a fixture, or a
|
|
15
|
+
* hypothetical — and it is why the rules below are statements about RULES
|
|
16
|
+
* rather than about a machine's state.
|
|
17
|
+
*
|
|
18
|
+
* THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
|
|
19
|
+
* `afterStep: X` cannot be credited on the strength of its own artifact when X
|
|
20
|
+
* did not run: the audit that exists without the handoff it read is not
|
|
21
|
+
* evidence of an audit. Demoting one step can invalidate whatever depended on
|
|
22
|
+
* it, so the demotion is applied repeatedly until nothing changes — and since
|
|
23
|
+
* demotion only ever removes a pass, the loop terminates.
|
|
24
|
+
*
|
|
25
|
+
* STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
|
|
26
|
+
* demotion looks a prerequisite up by id, so two steps sharing one id would be
|
|
27
|
+
* judged against each other — and each would overwrite the other's presence
|
|
28
|
+
* in the judge's bookkeeping, so both would report the same verdict. That is
|
|
29
|
+
* a silently wrong compliance number, which is the exact failure this
|
|
30
|
+
* campaign exists to prevent, so a spec that declares one id twice is
|
|
31
|
+
* REJECTED with an error naming the id rather than scored.
|
|
32
|
+
*/
|
|
33
|
+
import type { ComplianceSpec } from './compliance-spec.js';
|
|
34
|
+
/** What the judge concluded about one declared step. */
|
|
35
|
+
export type StepResult = {
|
|
36
|
+
/** The step's id, so a reader can find it in the spec. */
|
|
37
|
+
readonly stepId: string;
|
|
38
|
+
/** Whether the step's artifact was there. */
|
|
39
|
+
readonly executed: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Why the step did not execute. Present exactly when `executed` is false;
|
|
42
|
+
* absent when it is true, because a passing step has nothing to explain.
|
|
43
|
+
*/
|
|
44
|
+
readonly failureReason?: string;
|
|
45
|
+
};
|
|
46
|
+
/** The verdict for one spec. */
|
|
47
|
+
export type ComplianceResult = {
|
|
48
|
+
/** The spec's id. */
|
|
49
|
+
readonly specId: string;
|
|
50
|
+
/** One entry per declared step, in the order the spec declares them. */
|
|
51
|
+
readonly steps: readonly StepResult[];
|
|
52
|
+
/**
|
|
53
|
+
* The share of REQUIRED steps that executed. A spec that declares no
|
|
54
|
+
* required step demonstrates no compliance, so the rate is 0 rather than a
|
|
55
|
+
* vacuous 1: the reading that lets a spec declaring nothing read as
|
|
56
|
+
* perfect compliance is the one this metric exists to refuse.
|
|
57
|
+
*/
|
|
58
|
+
readonly complianceRate: number;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Judge one spec.
|
|
62
|
+
*
|
|
63
|
+
* @param spec the declared steps to judge.
|
|
64
|
+
* @param exists asked whether a session-relative artifact path is present.
|
|
65
|
+
* THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
|
|
66
|
+
* the declared path through verbatim; the CALLER substitutes the request id
|
|
67
|
+
* before probing the filesystem. A caller that probes the raw string gets
|
|
68
|
+
* the literal `<rid>` as a path, every step misses, and the rate reads 0
|
|
69
|
+
* without a single error — so the substitution is the caller's job, and it
|
|
70
|
+
* is stated here because that is where the callback is declared.
|
|
71
|
+
*
|
|
72
|
+
* @throws Error when two steps of the spec share one id. The judge's
|
|
73
|
+
* bookkeeping is keyed by step id, so a repeated id would make two steps
|
|
74
|
+
* overwrite each other's presence and report the same verdict — a silently
|
|
75
|
+
* wrong compliance number. A malformed spec is refused rather than scored.
|
|
76
|
+
*/
|
|
77
|
+
export declare function judgeCompliance(spec: ComplianceSpec, exists: (artifactPath: string) => boolean): ComplianceResult;
|