peaks-loop 4.1.20 → 4.1.21
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 +89 -0
- package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
- package/dist/cli/commands/observability-commands-baseline.js +74 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
- package/dist/cli/commands/observability-commands-queries.js +8 -1
- package/dist/cli/commands/observability-commands.d.ts +7 -1
- package/dist/cli/commands/observability-commands.js +19 -3
- package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
- package/dist/services/artifacts/repair-cycle-service.js +23 -0
- package/dist/services/observability/aggregation-helpers.d.ts +12 -8
- package/dist/services/observability/aggregation-helpers.js +12 -25
- package/dist/services/observability/aggregation-types.d.ts +40 -0
- package/dist/services/observability/aggregation.d.ts +2 -1
- package/dist/services/observability/aggregation.js +16 -25
- package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
- package/dist/services/observability/repair-cycle-metric.js +223 -0
- package/dist/services/observability/report-formatter.d.ts +1 -1
- package/dist/services/observability/report-formatter.js +16 -4
- package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
- package/dist/services/observability/results-baseline-artifact.js +80 -0
- package/dist/services/observability/results-baseline-rows.d.ts +33 -0
- package/dist/services/observability/results-baseline-rows.js +127 -0
- package/dist/services/observability/results-baseline.d.ts +115 -0
- package/dist/services/observability/results-baseline.js +101 -0
- package/package.json +7 -5
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/results-baseline.ts`
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS MODULE EXISTS — the results layer had no baseline at all, and the
|
|
5
|
+
* constraint that shapes what a baseline can be here is that the DATA IS NOT
|
|
6
|
+
* IN GIT.
|
|
7
|
+
*
|
|
8
|
+
* Observability data lives at `.peaks/_runtime/<sessionId>/metrics/slices.jsonl`
|
|
9
|
+
* and every such path is gitignored (verified with `git check-ignore`). A CI
|
|
10
|
+
* runner has no session data, therefore a results-layer baseline CANNOT be a
|
|
11
|
+
* CI gate. Pretending otherwise would produce a green CI job that checks
|
|
12
|
+
* nothing, so the tracked artifact says in machine-readable form that it is
|
|
13
|
+
* not CI-enforceable and why, and this module never wires itself into CI.
|
|
14
|
+
*
|
|
15
|
+
* What it IS: a tracked artifact (`.peaks/observability/results-baseline.json`)
|
|
16
|
+
* that records the current results-layer numbers as RATES and PEAKS — never
|
|
17
|
+
* as raw counts that grow with the number of slices ever recorded — is
|
|
18
|
+
* regenerable on demand (`peaks observability baseline --write`) and can be
|
|
19
|
+
* compared during a local run or a slice review (`--check`).
|
|
20
|
+
*
|
|
21
|
+
* The artifact also carries the old-vs-new comparison of the repair-cycle
|
|
22
|
+
* metric, because the historical numbers were a DIFFERENT MEASUREMENT and not
|
|
23
|
+
* a regression: version 1 counted qa-role transition events, version 2 counts
|
|
24
|
+
* repair cycles.
|
|
25
|
+
*/
|
|
26
|
+
/** The tracked artifact's path, relative to the project root. */
|
|
27
|
+
export declare const RESULTS_BASELINE_RELATIVE_PATH = ".peaks/observability/results-baseline.json";
|
|
28
|
+
export declare const RESULTS_BASELINE_SCHEMA_VERSION = 1;
|
|
29
|
+
/**
|
|
30
|
+
* Machine-readable statement that this artifact is NOT a CI gate, and why.
|
|
31
|
+
* A reader who finds the file must not assume a CI job enforces it.
|
|
32
|
+
*/
|
|
33
|
+
export declare const CI_ENFORCEABLE_REASON: string;
|
|
34
|
+
/**
|
|
35
|
+
* The drift `--check` tolerates per row kind. Absolute, not relative: the
|
|
36
|
+
* baseline rows are rates and peaks, and a relative band on a rate that is
|
|
37
|
+
* near zero would be meaningless.
|
|
38
|
+
*/
|
|
39
|
+
export declare const RESULTS_BASELINE_TOLERANCE: {
|
|
40
|
+
readonly rate: 0.02;
|
|
41
|
+
readonly peak: 1;
|
|
42
|
+
readonly mean: 0.5;
|
|
43
|
+
};
|
|
44
|
+
export type BaselineRowKind = 'rate' | 'peak' | 'mean';
|
|
45
|
+
export type BaselineRow = {
|
|
46
|
+
id: string;
|
|
47
|
+
kind: BaselineRowKind;
|
|
48
|
+
value: number;
|
|
49
|
+
unit: string;
|
|
50
|
+
description: string;
|
|
51
|
+
};
|
|
52
|
+
export type BaselineTolerance = {
|
|
53
|
+
rate: number;
|
|
54
|
+
peak: number;
|
|
55
|
+
mean: number;
|
|
56
|
+
note: string;
|
|
57
|
+
};
|
|
58
|
+
export type BaselinePopulation = {
|
|
59
|
+
scope: string;
|
|
60
|
+
sessionIds: string[];
|
|
61
|
+
sessionCount: number;
|
|
62
|
+
sliceCount: number;
|
|
63
|
+
sliceTransitionEventCount: number;
|
|
64
|
+
measuredAt: string;
|
|
65
|
+
};
|
|
66
|
+
export type MetricComparisonSide = {
|
|
67
|
+
metric: string;
|
|
68
|
+
metricVersion: number;
|
|
69
|
+
total: number;
|
|
70
|
+
peak: number;
|
|
71
|
+
slicesMeasured: number;
|
|
72
|
+
slicesAtOrOverCap: number;
|
|
73
|
+
distribution: Record<string, number>;
|
|
74
|
+
};
|
|
75
|
+
export type ResultsBaseline = {
|
|
76
|
+
schemaVersion: number;
|
|
77
|
+
metricVersion: number;
|
|
78
|
+
generatedAt: string;
|
|
79
|
+
ciEnforceable: false;
|
|
80
|
+
ciEnforceableReason: string;
|
|
81
|
+
tolerance: BaselineTolerance;
|
|
82
|
+
baselineRows: BaselineRow[];
|
|
83
|
+
population: BaselinePopulation;
|
|
84
|
+
populationDescriptors: {
|
|
85
|
+
note: string;
|
|
86
|
+
totalSlices: number;
|
|
87
|
+
totalSliceTransitionEvents: number;
|
|
88
|
+
totalRepairCycles: number;
|
|
89
|
+
totalQaRounds: number;
|
|
90
|
+
totalLegacyQaEvents: number;
|
|
91
|
+
};
|
|
92
|
+
metricComparison: {
|
|
93
|
+
note: string;
|
|
94
|
+
v1QaEventCount: MetricComparisonSide;
|
|
95
|
+
v2RepairCycles: MetricComparisonSide;
|
|
96
|
+
};
|
|
97
|
+
};
|
|
98
|
+
export type BaselineDrift = {
|
|
99
|
+
rowId: string;
|
|
100
|
+
kind: 'row-missing' | 'value-drift' | 'metric-version-mismatch';
|
|
101
|
+
tracked: number | null;
|
|
102
|
+
computed: number | null;
|
|
103
|
+
tolerance: number | null;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* Compute the baseline over the WHOLE recorded history of a project. This is
|
|
107
|
+
* the population the tracked artifact describes; a session-scoped run would
|
|
108
|
+
* measure a different population and could not be compared with it.
|
|
109
|
+
*/
|
|
110
|
+
export declare function computeResultsBaseline(projectRoot: string): ResultsBaseline;
|
|
111
|
+
/**
|
|
112
|
+
* `src/services/observability/results-baseline-artifact.ts` holds the
|
|
113
|
+
* tracked artifact's on-disk side: reading it, writing it, and reporting
|
|
114
|
+
* drift against a freshly computed baseline.
|
|
115
|
+
*/
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/results-baseline.ts`
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS MODULE EXISTS — the results layer had no baseline at all, and the
|
|
5
|
+
* constraint that shapes what a baseline can be here is that the DATA IS NOT
|
|
6
|
+
* IN GIT.
|
|
7
|
+
*
|
|
8
|
+
* Observability data lives at `.peaks/_runtime/<sessionId>/metrics/slices.jsonl`
|
|
9
|
+
* and every such path is gitignored (verified with `git check-ignore`). A CI
|
|
10
|
+
* runner has no session data, therefore a results-layer baseline CANNOT be a
|
|
11
|
+
* CI gate. Pretending otherwise would produce a green CI job that checks
|
|
12
|
+
* nothing, so the tracked artifact says in machine-readable form that it is
|
|
13
|
+
* not CI-enforceable and why, and this module never wires itself into CI.
|
|
14
|
+
*
|
|
15
|
+
* What it IS: a tracked artifact (`.peaks/observability/results-baseline.json`)
|
|
16
|
+
* that records the current results-layer numbers as RATES and PEAKS — never
|
|
17
|
+
* as raw counts that grow with the number of slices ever recorded — is
|
|
18
|
+
* regenerable on demand (`peaks observability baseline --write`) and can be
|
|
19
|
+
* compared during a local run or a slice review (`--check`).
|
|
20
|
+
*
|
|
21
|
+
* The artifact also carries the old-vs-new comparison of the repair-cycle
|
|
22
|
+
* metric, because the historical numbers were a DIFFERENT MEASUREMENT and not
|
|
23
|
+
* a regression: version 1 counted qa-role transition events, version 2 counts
|
|
24
|
+
* repair cycles.
|
|
25
|
+
*/
|
|
26
|
+
import { aggregateRepairCycles, aggregateStatus, readAllSessionEvents } from './aggregation.js';
|
|
27
|
+
import { listSessionDirsWithMetrics } from './jsonl-store.js';
|
|
28
|
+
import { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
29
|
+
import { baselineRows, metricComparison } from './results-baseline-rows.js';
|
|
30
|
+
/** The tracked artifact's path, relative to the project root. */
|
|
31
|
+
export const RESULTS_BASELINE_RELATIVE_PATH = '.peaks/observability/results-baseline.json';
|
|
32
|
+
export const RESULTS_BASELINE_SCHEMA_VERSION = 1;
|
|
33
|
+
/**
|
|
34
|
+
* Machine-readable statement that this artifact is NOT a CI gate, and why.
|
|
35
|
+
* A reader who finds the file must not assume a CI job enforces it.
|
|
36
|
+
*/
|
|
37
|
+
export const CI_ENFORCEABLE_REASON = 'NOT CI-ENFORCEABLE. The source data lives in .peaks/_runtime/<sessionId>/metrics/slices.jsonl, ' +
|
|
38
|
+
'and every such path is gitignored — a CI runner has no session data, so there is nothing there to ' +
|
|
39
|
+
'compare against. This file is a local review artifact: regenerate it with ' +
|
|
40
|
+
'`peaks observability baseline --write` on a machine that has session data and compare it with ' +
|
|
41
|
+
'`peaks observability baseline --check` during a local run or a slice review.';
|
|
42
|
+
/**
|
|
43
|
+
* The drift `--check` tolerates per row kind. Absolute, not relative: the
|
|
44
|
+
* baseline rows are rates and peaks, and a relative band on a rate that is
|
|
45
|
+
* near zero would be meaningless.
|
|
46
|
+
*/
|
|
47
|
+
export const RESULTS_BASELINE_TOLERANCE = {
|
|
48
|
+
rate: 0.02,
|
|
49
|
+
peak: 1,
|
|
50
|
+
mean: 0.5
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Compute the baseline over the WHOLE recorded history of a project. This is
|
|
54
|
+
* the population the tracked artifact describes; a session-scoped run would
|
|
55
|
+
* measure a different population and could not be compared with it.
|
|
56
|
+
*/
|
|
57
|
+
export function computeResultsBaseline(projectRoot) {
|
|
58
|
+
const events = readAllSessionEvents(projectRoot);
|
|
59
|
+
const status = aggregateStatus(events);
|
|
60
|
+
const cycles = aggregateRepairCycles(events);
|
|
61
|
+
const sessionIds = listSessionDirsWithMetrics(projectRoot).map((entry) => entry.sessionId);
|
|
62
|
+
const sliceTransitionEventCount = events.filter((event) => event.category === 'slice-transition').length;
|
|
63
|
+
const slices = status.totalSlices;
|
|
64
|
+
const generatedAt = new Date().toISOString();
|
|
65
|
+
return {
|
|
66
|
+
schemaVersion: RESULTS_BASELINE_SCHEMA_VERSION,
|
|
67
|
+
metricVersion: REPAIR_CYCLE_METRIC_VERSION,
|
|
68
|
+
generatedAt,
|
|
69
|
+
ciEnforceable: false,
|
|
70
|
+
ciEnforceableReason: CI_ENFORCEABLE_REASON,
|
|
71
|
+
tolerance: {
|
|
72
|
+
...RESULTS_BASELINE_TOLERANCE,
|
|
73
|
+
note: 'Absolute drift allowed per row kind when `peaks observability baseline --check` compares ' +
|
|
74
|
+
'the tracked artifact with the freshly computed baseline.'
|
|
75
|
+
},
|
|
76
|
+
baselineRows: baselineRows(status, cycles, slices),
|
|
77
|
+
population: {
|
|
78
|
+
scope: 'all-sessions',
|
|
79
|
+
sessionIds,
|
|
80
|
+
sessionCount: sessionIds.length,
|
|
81
|
+
sliceCount: slices,
|
|
82
|
+
sliceTransitionEventCount,
|
|
83
|
+
measuredAt: generatedAt
|
|
84
|
+
},
|
|
85
|
+
populationDescriptors: {
|
|
86
|
+
note: 'Population descriptors, NOT baseline rows: these grow with the number of slices ever ' +
|
|
87
|
+
'recorded and must never be gated on. The baseline rows above are rates and peaks.',
|
|
88
|
+
totalSlices: slices,
|
|
89
|
+
totalSliceTransitionEvents: sliceTransitionEventCount,
|
|
90
|
+
totalRepairCycles: cycles.totalCycles,
|
|
91
|
+
totalQaRounds: cycles.qaRounds.total,
|
|
92
|
+
totalLegacyQaEvents: cycles.legacyQaEventCount.total
|
|
93
|
+
},
|
|
94
|
+
metricComparison: metricComparison(cycles, slices)
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* `src/services/observability/results-baseline-artifact.ts` holds the
|
|
99
|
+
* tracked artifact's on-disk side: reading it, writing it, and reporting
|
|
100
|
+
* drift against a freshly computed baseline.
|
|
101
|
+
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peaks-loop",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.21",
|
|
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-
|
|
136
|
-
"peaks-loop-
|
|
137
|
-
"peaks-loop-shared": "0.0.
|
|
138
|
-
"peaks-loop-shared-channel": "0.0.
|
|
135
|
+
"peaks-loop-mut": "0.1.75",
|
|
136
|
+
"peaks-loop-internal-runtime": "0.0.61",
|
|
137
|
+
"peaks-loop-shared": "0.0.110",
|
|
138
|
+
"peaks-loop-shared-channel": "0.0.78"
|
|
139
139
|
},
|
|
140
140
|
"devDependencies": {
|
|
141
141
|
"@changesets/cli": "2.31.1",
|
|
@@ -183,6 +183,8 @@
|
|
|
183
183
|
"test:audit:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
|
|
184
184
|
"test:ci": "node ./scripts/sync-version.mjs && node ./scripts/lint/silent-warning-detector.mjs && vitest run --coverage",
|
|
185
185
|
"test:changed": "node scripts/test-changed.mjs",
|
|
186
|
+
"bench:phase-a": "node node_modules/tsx/dist/cli.mjs benchmarks/runtime-detached/baseline.ts",
|
|
187
|
+
"bench:resource-budget": "node node_modules/tsx/dist/cli.mjs benchmarks/runtime-detached/resource-budget-bench.ts",
|
|
186
188
|
"lint:silent-warning": "node ./scripts/lint/silent-warning-detector.mjs",
|
|
187
189
|
"test:race": "vitest run --no-file-parallelism packages/peaks-loop-shared-channel/tests/shared-channel.test.ts tests/unit/services/dispatch/dispatch-record-writer.test.ts",
|
|
188
190
|
"test:replay": "node scripts/fixture-capture-setup.mjs && vitest run tests/unit/services/dispatch/conflict-replay.test.ts tests/unit/services/dispatch/e2e-fixtures.test.ts",
|