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.
Files changed (72) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +82 -0
  3. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  4. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  5. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  6. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  8. package/dist/cli/commands/observability-commands-queries.js +88 -47
  9. package/dist/cli/commands/observability-commands.js +79 -20
  10. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  11. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  12. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  13. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  14. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  15. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  16. package/dist/services/artifacts/rd-gate-event.js +211 -0
  17. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  18. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  19. package/dist/services/observability/aggregation-types.d.ts +21 -0
  20. package/dist/services/observability/aggregation.d.ts +12 -2
  21. package/dist/services/observability/aggregation.js +26 -2
  22. package/dist/services/observability/compliance-judge.d.ts +77 -0
  23. package/dist/services/observability/compliance-judge.js +143 -0
  24. package/dist/services/observability/compliance-spec.d.ts +96 -0
  25. package/dist/services/observability/compliance-spec.js +29 -0
  26. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  27. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  28. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  29. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  30. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  31. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  32. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  33. package/dist/services/observability/hotspot-rows.js +89 -0
  34. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  35. package/dist/services/observability/hotspot-shared.js +122 -0
  36. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  37. package/dist/services/observability/hotspot-sources.js +142 -0
  38. package/dist/services/observability/hotspots.d.ts +47 -0
  39. package/dist/services/observability/hotspots.js +47 -0
  40. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  41. package/dist/services/observability/near-miss-attempts.js +223 -0
  42. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  43. package/dist/services/observability/near-miss-coverage.js +108 -0
  44. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  45. package/dist/services/observability/near-miss-denominator.js +75 -0
  46. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  47. package/dist/services/observability/near-miss-difference.js +132 -0
  48. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  49. package/dist/services/observability/near-miss-facts.js +101 -0
  50. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  51. package/dist/services/observability/near-miss-gate-events.js +106 -0
  52. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  53. package/dist/services/observability/near-miss-gates.js +135 -0
  54. package/dist/services/observability/near-miss-records.d.ts +93 -0
  55. package/dist/services/observability/near-miss-records.js +87 -0
  56. package/dist/services/observability/near-miss.d.ts +148 -0
  57. package/dist/services/observability/near-miss.js +196 -0
  58. package/dist/services/observability/observability-schema.d.ts +17 -2
  59. package/dist/services/observability/observability-schema.js +21 -1
  60. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  61. package/dist/services/observability/owner-skill-map.js +144 -0
  62. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  63. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  64. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  65. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  66. package/dist/services/observability/report-formatter.d.ts +49 -3
  67. package/dist/services/observability/report-formatter.js +55 -14
  68. package/dist/services/observability/retro-attribution.d.ts +129 -0
  69. package/dist/services/observability/retro-attribution.js +134 -0
  70. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  71. package/dist/services/observability/session-metric-rows.js +184 -0
  72. 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.22",
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.62",
136
- "peaks-loop-mut": "0.1.76",
137
- "peaks-loop-shared": "0.0.111",
138
- "peaks-loop-shared-channel": "0.0.79"
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",