peaks-loop 4.1.20 → 4.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +198 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
  6. package/dist/cli/commands/observability-commands-baseline.js +74 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
  8. package/dist/cli/commands/observability-commands-queries.js +8 -1
  9. package/dist/cli/commands/observability-commands.d.ts +7 -1
  10. package/dist/cli/commands/observability-commands.js +19 -3
  11. package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
  12. package/dist/services/artifacts/repair-cycle-service.js +23 -0
  13. package/dist/services/distribution/json-layout.d.ts +20 -0
  14. package/dist/services/distribution/json-layout.js +195 -0
  15. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  16. package/dist/services/distribution/plugin-manifest.js +40 -4
  17. package/dist/services/observability/aggregation-helpers.d.ts +12 -8
  18. package/dist/services/observability/aggregation-helpers.js +12 -25
  19. package/dist/services/observability/aggregation-types.d.ts +40 -0
  20. package/dist/services/observability/aggregation.d.ts +2 -1
  21. package/dist/services/observability/aggregation.js +16 -25
  22. package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
  23. package/dist/services/observability/repair-cycle-metric.js +223 -0
  24. package/dist/services/observability/report-formatter.d.ts +1 -1
  25. package/dist/services/observability/report-formatter.js +16 -4
  26. package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
  27. package/dist/services/observability/results-baseline-artifact.js +80 -0
  28. package/dist/services/observability/results-baseline-rows.d.ts +33 -0
  29. package/dist/services/observability/results-baseline-rows.js +127 -0
  30. package/dist/services/observability/results-baseline.d.ts +115 -0
  31. package/dist/services/observability/results-baseline.js +101 -0
  32. package/package.json +7 -5
@@ -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.20",
3
+ "version": "4.1.22",
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.60",
136
- "peaks-loop-mut": "0.1.74",
137
- "peaks-loop-shared": "0.0.109",
138
- "peaks-loop-shared-channel": "0.0.77"
135
+ "peaks-loop-internal-runtime": "0.0.62",
136
+ "peaks-loop-mut": "0.1.76",
137
+ "peaks-loop-shared": "0.0.111",
138
+ "peaks-loop-shared-channel": "0.0.79"
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",