mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/observability/perf-aggregator.js

@@ -8,12 +8,10 @@
  *   - `computeStoryPerfSummary(events, opts)` → `<!-- structured:story-perf-summary -->`
  *   - `computeEpicPerfReport(perStorySummaries, opts)` → `<!-- structured:epic-perf-report -->`
  *
- * Plus streaming counterparts that consume the canonical
- * `lib/signals/read` iterator directly, so the aggregator owns its own
- * NDJSON ingestion through the shared reader (Task #1460 AC):
- *
- *   - `computeStoryPerfSummaryFromStore({ storyId, epicId, config? })`
- *   - `computeEpicPerfReportFromStore({ epicId, perStorySummaries, config? })`
+ * Both take a materialised event iterable; the caller (`analyze-execution.js`)
+ * owns NDJSON ingestion via `lib/signals/read.js`. (The former
+ * streaming store-reading variants were retired in the Epic #4406
+ * signal-contract cutover — they had no callers.)
  *
  * Schemas:
  *   - `.agents/schemas/story-perf-summary.schema.json`
@@ -39,7 +37,6 @@
  */
 
 import { isObject } from '../json-utils.js';
-import { read as readSignals } from '../signals/read.js';
 import { EVENT_KINDS } from '../signals/schema.js';
 
 const FRICTION_KIND = EVENT_KINDS.FRICTION;
@@ -69,7 +66,10 @@ function nonNegativeNumber(v) {
 
 /**
  * Pull friction-by-category counts off a list of NDJSON events. Keys are
- * the `details.category` strings; values ≥ 0 integers.
+ * the **top-level** `category` strings (Epic #4406 canonical shape); a
+ * record with no top-level category buckets under `Unknown`. Reading the
+ * top-level key (not `details.category`) is what un-zeroes the report —
+ * every writer emits `category` at the envelope top level.
  *
  * @param {Iterable<object>} events
  * @returns {Object<string, number>}
@@ -79,8 +79,8 @@ function frictionByCategory(events) {
   for (const evt of events) {
     if (!isObject(evt) || evt.kind !== FRICTION_KIND) continue;
     const category =
-      isObject(evt.details) && typeof evt.details.category === 'string'
-        ? evt.details.category
+      typeof evt.category === 'string' && evt.category.length > 0
+        ? evt.category
         : 'Unknown';
     out[category] = (out[category] ?? 0) + 1;
   }
@@ -125,7 +125,10 @@ function topSlowPhasesVsBaseline(events, opts = {}) {
 /**
  * Build the `reworkScore` object: `{ filesEditedBeyondThreshold, topPath?,
  * topPathEdits? }`. We aggregate `kind: 'rework'` signals whose details
- * carry a `path` and an `edits` count. When the input has no rework
+ * carry a `targetHash` and an `editCount` — the exact keys
+ * `detectors/rework.js` emits (Epic #4406 canonical shape). `topPath` is
+ * the offending `targetHash` (a sha256; the raw path never reaches the
+ * aggregator by the privacy contract). When the input has no rework
  * signals we return the zero-shape: `{ filesEditedBeyondThreshold: 0 }`.
  *
  * @param {Iterable<object>} events
@@ -136,9 +139,12 @@ function reworkScore(events) {
   for (const evt of events) {
     if (!isObject(evt) || evt.kind !== REWORK_KIND) continue;
     const d = isObject(evt.details) ? evt.details : {};
-    const p = typeof d.path === 'string' && d.path.length > 0 ? d.path : null;
+    const p =
+      typeof d.targetHash === 'string' && d.targetHash.length > 0
+        ? d.targetHash
+        : null;
     if (!p) continue;
-    const edits = nonNegativeInt(d.edits);
+    const edits = nonNegativeInt(d.editCount);
     editsByPath.set(p, Math.max(editsByPath.get(p) ?? 0, edits));
   }
   if (editsByPath.size === 0) {
@@ -161,24 +167,27 @@ function reworkScore(events) {
 
 /**
  * Build the `retryDensity` object: `{ retries, uniqueCommands }`. Sums
- * `kind: 'retry'` signals; `uniqueCommands` is the number of distinct
- * `details.command` strings observed. Zero-shape on empty input.
+ * `kind: 'retry'` signals; `uniqueCommands` is the hash-cardinality of the
+ * distinct `details.commandHash` values observed — the exact key
+ * `detectors/retry.js` emits (Epic #4406 canonical shape). The raw command
+ * never reaches the aggregator by the privacy contract, so we count
+ * distinct hashes. Zero-shape on empty input.
  *
  * @param {Iterable<object>} events
  * @returns {{ retries: number, uniqueCommands: number }}
  */
 function retryDensity(events) {
   let retries = 0;
-  const commands = new Set();
+  const commandHashes = new Set();
   for (const evt of events) {
     if (!isObject(evt) || evt.kind !== RETRY_KIND) continue;
     const d = isObject(evt.details) ? evt.details : {};
     retries += 1;
-    if (typeof d.command === 'string' && d.command.length > 0) {
-      commands.add(d.command);
+    if (typeof d.commandHash === 'string' && d.commandHash.length > 0) {
+      commandHashes.add(d.commandHash);
     }
   }
-  return { retries, uniqueCommands: commands.size };
+  return { retries, uniqueCommands: commandHashes.size };
 }
 
 /**
@@ -375,7 +384,7 @@ const DEFAULT_VERIFY_CONCURRENCY_CAP = 4;
 const DEFAULT_WAVE_CONCURRENCY_CAP = 2;
 
 function tsOf(evt) {
-  return evt?.ts ?? evt?.timestamp ?? null;
+  return evt?.ts ?? null;
 }
 
 function tsToMs(ts) {
@@ -385,8 +394,7 @@ function tsToMs(ts) {
 }
 
 function storyIdOf(evt) {
-  const raw = evt?.story ?? evt?.storyId;
-  const n = Number(raw);
+  const n = Number(evt?.storyId);
   return Number.isInteger(n) && n > 0 ? n : null;
 }
 
@@ -803,85 +811,3 @@ export function computeEpicPerfReport(perStorySummaries, opts) {
     mostFrictionStories,
   };
 }
-
-// ---------------------------------------------------------------------------
-// Streaming entry-points (Epic #1181 / Story #1438 / Task #1460)
-// ---------------------------------------------------------------------------
-
-/**
- * Streaming variant of `computeStoryPerfSummary` that ingests events
- * directly from `lib/signals/read.js` rather than expecting the caller
- * to materialise the iterable upstream. The aggregation logic is
- * identical — we collect the events through the shared reader and then
- * delegate to `computeStoryPerfSummary`.
- *
- * Use this when the caller is the analyzer and already has the
- * `{ epicId, storyId, config }` triple; use the pure
- * `computeStoryPerfSummary(events, opts)` when the caller already
- * holds an in-memory event array (tests, mock injections).
- *
- * @param {{
- *   storyId: number,
- *   epicId: number,
- *   closedAt?: string,
- *   phaseTiming?: object|null,
- *   config?: object,
- * }} opts
- * @returns {Promise<object>} StoryPerfSummary payload.
- */
-export async function computeStoryPerfSummaryFromStore(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('computeStoryPerfSummaryFromStore: opts is required');
-  }
-  const { storyId, epicId, config } = opts;
-  const events = [];
-  for await (const evt of readSignals({
-    epic: Number(epicId),
-    story: Number(storyId),
-    config,
-  })) {
-    events.push(evt);
-  }
-  return computeStoryPerfSummary(events, {
-    storyId,
-    epicId,
-    closedAt: opts.closedAt,
-    phaseTiming: opts.phaseTiming,
-  });
-}
-
-/**
- * Streaming variant of `computeEpicPerfReport` that ingests the
- * raw-event roll-up directly from `lib/signals/read.js` (across every
- * Story under the Epic). Per-Story summaries are still passed in by
- * the caller — those are the canonical per-Story payloads upserted
- * onto each Story ticket and not derivable from the raw stream alone
- * (they fold in phase-timer data).
- *
- * @param {{
- *   epicId: number,
- *   perStorySummaries?: Iterable<object>,
- *   generatedAt?: string,
- *   waveParallelism?: Array<object>,
- *   topHotspots?: Array<object>,
- *   config?: object,
- * }} opts
- * @returns {Promise<object>} EpicPerfReport payload.
- */
-export async function computeEpicPerfReportFromStore(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('computeEpicPerfReportFromStore: opts is required');
-  }
-  const { epicId, perStorySummaries, config } = opts;
-  const events = [];
-  for await (const evt of readSignals({ epic: Number(epicId), config })) {
-    events.push(evt);
-  }
-  return computeEpicPerfReport(perStorySummaries ?? [], {
-    epicId,
-    generatedAt: opts.generatedAt,
-    events,
-    waveParallelism: opts.waveParallelism,
-    topHotspots: opts.topHotspots,
-  });
-}

package/.agents/scripts/lib/observability/perf-report-readers.js

@@ -274,7 +274,7 @@ export async function aggregateBaselineFrictionFromSignals({
         ) {
           return;
         }
-        const ts = Date.parse(record.timestamp);
+        const ts = Date.parse(record.ts);
         if (Number.isFinite(ts) && ts < cutoffMs) return;
 
         totalRecords += 1;

package/.agents/scripts/lib/observability/signal-validator.js

@@ -0,0 +1,204 @@
+/**
+ * signal-validator.js — write-time validation of NDJSON signal records
+ * against the canonical `signal-event.schema.json` (Epic #4406 /
+ * Story #4413).
+ *
+ * The signals writer calls {@link validateSignal} before appending a
+ * record so a schema-invalid line is dropped with a `Logger.warn` naming
+ * the violating field rather than polluting the stream (and defeating the
+ * downstream consumers that assume the canonical shape). Validation is
+ * best-effort: the writer contract (Tech Spec #1032) is preserved —
+ * observability MUST NOT throw into the runner, so every helper here
+ * swallows its own faults and degrades to "treat as valid" only when the
+ * validator itself cannot be constructed.
+ *
+ * The AJV instance compiles the on-disk schema **once** at module load so
+ * the writer and the contract test validate against the exact same
+ * document (no hand-rolled drift). `strict: false` matches the repo's
+ * other draft-07 validators (see `tests/schemas/signal-schemas.test.js`).
+ *
+ * A per-Epic reject tally is persisted under the Epic temp tree
+ * (`temp/epic-<eid>/signal-rejects.json`) so a cross-process reader (the
+ * loop-health check, a follow-on Story) can surface how many records were
+ * dropped. The tally is read-modify-written best-effort; a lost increment
+ * under a write race is acceptable for a diagnostic counter.
+ */
+
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+import { epicArtifactPath } from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'signal-event.schema.json',
+);
+
+const REJECT_TALLY_BASENAME = 'signal-rejects.json';
+
+/**
+ * Compile the signal-event schema once. Returns `null` when the schema
+ * cannot be read or compiled — the caller then treats every record as
+ * valid (fail-open) so a packaging error never silently drops all
+ * signals.
+ *
+ * @returns {import('ajv').ValidateFunction | null}
+ */
+function buildValidator() {
+  try {
+    const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    return ajv.compile(schema);
+  } catch (err) {
+    Logger.warn(
+      `signal-validator: failed to compile signal-event schema (${
+        err instanceof Error ? err.message : String(err)
+      }); write-time validation disabled for this process.`,
+    );
+    return null;
+  }
+}
+
+const _validate = buildValidator();
+
+/**
+ * Derive a human-readable "violating field" label from the first AJV
+ * error. Prefers the missing property name (required errors) or the
+ * instance path, falling back to the raw message.
+ *
+ * @param {import('ajv').ErrorObject[] | null | undefined} errors
+ * @returns {string}
+ */
+function violatingFieldOf(errors) {
+  const first = Array.isArray(errors) && errors.length > 0 ? errors[0] : null;
+  if (!first) return 'unknown';
+  if (first.keyword === 'required' && first.params?.missingProperty) {
+    return String(first.params.missingProperty);
+  }
+  if (typeof first.instancePath === 'string' && first.instancePath.length > 0) {
+    return first.instancePath.replace(/^\//, '').replace(/\//g, '.');
+  }
+  if (
+    first.keyword === 'additionalProperties' &&
+    first.params?.additionalProperty
+  ) {
+    return String(first.params.additionalProperty);
+  }
+  return first.message ?? 'unknown';
+}
+
+/**
+ * Validate a signal record against the canonical schema.
+ *
+ * Fail-open: when the validator could not be compiled the record is
+ * reported valid (the writer keeps working). A non-object record is
+ * reported invalid without invoking AJV.
+ *
+ * @param {unknown} record
+ * @returns {{ valid: boolean, violatingField: string|null, message: string|null }}
+ */
+export function validateSignal(record) {
+  if (_validate === null) {
+    return { valid: true, violatingField: null, message: null };
+  }
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    return {
+      valid: false,
+      violatingField: 'record',
+      message: 'signal record must be a plain object',
+    };
+  }
+  const valid = _validate(record);
+  if (valid) return { valid: true, violatingField: null, message: null };
+  const field = violatingFieldOf(_validate.errors);
+  const message = _validate.errors?.[0]?.message ?? 'schema validation failed';
+  return { valid: false, violatingField: field, message };
+}
+
+/**
+ * Increment the per-Epic reject tally persisted under the Epic temp tree.
+ * Best-effort and never throws: a missing/corrupt tally file resets to a
+ * count of 1. When `epicId` is not a positive integer (e.g. a standalone
+ * friction record with `epicId: null`) the tally write is skipped — there
+ * is no Epic temp tree to anchor it to.
+ *
+ * @param {{ epicId: number|null|undefined, config?: object, field?: string|null }} args
+ * @returns {Promise<number|null>} the new count, or null when skipped/failed.
+ */
+export async function recordSignalReject({ epicId, config, field }) {
+  if (!Number.isInteger(epicId) || epicId <= 0) return null;
+  let target;
+  try {
+    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+  } catch {
+    return null;
+  }
+  try {
+    let prior = { count: 0, lastField: null };
+    try {
+      const raw = await fs.readFile(target, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === 'object' &&
+        Number.isFinite(parsed.count)
+      ) {
+        prior = { count: parsed.count, lastField: parsed.lastField ?? null };
+      }
+    } catch {
+      // Missing or corrupt file → start a fresh tally.
+    }
+    const next = {
+      count: prior.count + 1,
+      lastField: field ?? prior.lastField ?? null,
+      updatedAt: new Date().toISOString(),
+    };
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, `${JSON.stringify(next)}\n`, 'utf8');
+    return next.count;
+  } catch (err) {
+    Logger.warn(
+      `signal-validator: failed to persist reject tally for epic-${epicId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Read the current per-Epic reject count. Cross-process readable
+ * counterpart to {@link recordSignalReject}. Returns 0 when the tally
+ * file is absent or unreadable.
+ *
+ * @param {{ epicId: number, config?: object }} args
+ * @returns {Promise<number>}
+ */
+export async function readSignalRejectCount({ epicId, config }) {
+  if (!Number.isInteger(epicId) || epicId <= 0) return 0;
+  let target;
+  try {
+    target = epicArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
+  } catch {
+    return 0;
+  }
+  try {
+    const raw = await fs.readFile(target, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && Number.isFinite(parsed.count) ? parsed.count : 0;
+  } catch {
+    return 0;
+  }
+}