mandrel 2.22.0 → 2.24.0

package/.agents/scripts/lib/escomplex-ast-compat.js

@@ -0,0 +1,360 @@
+/**
+ * escomplex-ast-compat.js — reconcile the `typhonjs-escomplex` code generator
+ * with the Babel AST that `typhonjs-escomplex`'s own default parser emits.
+ *
+ * ## The upstream defect
+ *
+ * `typhonjs-escomplex` parses with `@typhonjs/babel-parser`, so every AST it
+ * analyses is a **Babel** AST. But `typhonjs-escomplex-commons`'
+ * `utils/ast/astSyntax.js` — the code generator that `ASTGenerator` drives —
+ * was written against **ESTree**. The two disagree on node names
+ * (`OptionalMemberExpression` vs a `MemberExpression` with `optional: true`)
+ * and on node shapes (Babel's `RegExpLiteral` carries `pattern`/`flags`
+ * directly; ESTree wraps them in a `regex` object on a `Literal`).
+ *
+ * That mismatch is invisible for most code because the metric traversal runs
+ * off the syntax plugin's trait tables, not off `astSyntax`. `astSyntax` is
+ * only reached where a trait re-serialises a **sub-AST** to synthesise a
+ * Halstead operand or a function signature — nine traits do this:
+ * `For`/`ForIn`/`ForOf` heads, `Function`/`FunctionExpression`/
+ * `ArrowFunctionExpression` parameter lists, `Class`/`ClassExpression`
+ * bodies, and `YieldExpression` arguments.
+ *
+ * Reach one of those with a Babel-only node and `analyzeModule()` throws —
+ * aborting the whole module, not just the sub-expression. The constructs that
+ * trip it are ordinary modern JavaScript:
+ *
+ * ```js
+ * for (const t of s.split(/[^a-z]+/)) {}   // TypeError: …reading 'pattern'
+ * for (const t of await xs()) {}           // …generator[node.type] is not a function
+ * for (const t of a?.b) {}                 // …generator[node.type] is not a function
+ * function f(a = () => import('x')) {}     // …this[node.callee.type] is not a function
+ * function f(a = { ...b }) {}              // TypeError: …reading 'type'
+ * function f(a = { m() {} }) {}            // TypeError: …reading 'generator'
+ * function f(a = class { m() {} }) {}      // …this[statement.type] is not a function
+ * ```
+ *
+ * The `{ ...b }` case is upstream issue #24, open and untouched since
+ * 2020-12-16 with a byte-identical stack trace. The package last published in
+ * June 2022 and the repo that holds the defective file has issues *disabled*,
+ * so waiting for an upstream release is not a plan. Consumers of this kernel
+ * previously absorbed the breakage as an allowlist of "unscorable" files that
+ * grew every time someone wrote a `?.` in a loop head.
+ *
+ * ## What this module does
+ *
+ * Installs the missing handlers and repairs the two shape assumptions, on the
+ * shared `astSyntax` table, once per process. Every patch is **conditional**:
+ * a handler is only installed where the table lacks one, and the two repairs
+ * wrap the original rather than replacing its behaviour. If a future kernel
+ * bump fixes any of this upstream, the corresponding patch silently stops
+ * applying and `install()` reports a shorter list — which
+ * `tests/lib/escomplex-ast-compat.test.js` asserts on, so the shrinkage is
+ * visible rather than silent.
+ *
+ * Nothing here changes the score of a file that already parses: the patched
+ * paths are exactly the paths that previously threw.
+ *
+ * @see https://github.com/typhonjs-node-escomplex/typhonjs-escomplex/issues/24
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/** Marker set on every function this module installs, for idempotency. */
+const PATCH_MARKER = Symbol.for('mandrel.escomplexAstCompat');
+
+/** Memoised result of the one-time install. */
+let installResult = null;
+
+/**
+ * Resolve the shared `astSyntax` generator table.
+ *
+ * This is a deep import into a transitive dependency's `dist/`, which is
+ * exactly as fragile as it looks — hence the soft failure. If upstream ever
+ * restructures, `install()` reports `available: false` and the engine falls
+ * back to today's behaviour (unscorable files, now reported explicitly by
+ * the engine rather than silently scored 0).
+ *
+ * The patch must land on the *same* `typhonjs-escomplex-commons` instance the
+ * kernel loads, so `commons` is resolved **through `typhonjs-escomplex`'s own
+ * resolution** rather than from here. Resolving it directly would be a coin
+ * flip: under a hoisting installer it usually finds the same copy, but under
+ * pnpm's isolated layout — or as soon as anything declares `commons` directly —
+ * it can find a *different* physical copy, and the patch then lands on a table
+ * nobody reads while `install()` cheerfully reports success. Anchoring makes
+ * that failure mode unreachable.
+ *
+ * `requireFn` is the test seam: a cross-checkout verification harness passes
+ * its own `createRequire` so the anchor starts from that checkout's escomplex.
+ *
+ * @param {NodeJS.Require} [requireFn]
+ * @returns {Record<string, Function>|null}
+ */
+function resolveSyntaxTable(requireFn = require) {
+  try {
+    const fromKernel = createRequire(requireFn.resolve('typhonjs-escomplex'));
+    const mod = fromKernel(
+      'typhonjs-escomplex-commons/dist/utils/ast/astSyntax.js',
+    );
+    const table = mod?.default ?? mod;
+    if (!table || typeof table !== 'object') return null;
+    // Sanity-check that this is the table we think it is before mutating it.
+    if (typeof table.MemberExpression !== 'function') return null;
+    if (Object.isFrozen(table)) return null;
+    return table;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tag a handler as ours so a second `install()` is a no-op.
+ *
+ * @template {Function} F
+ * @param {F} fn
+ * @returns {F}
+ */
+function mark(fn) {
+  fn[PATCH_MARKER] = true;
+  return fn;
+}
+
+/**
+ * Install `name` only if the table has no handler for it. Returns whether the
+ * install happened, so the caller can report the applied surface.
+ *
+ * @param {Record<string, Function>} table
+ * @param {string} name
+ * @param {Function} handler
+ * @returns {boolean}
+ */
+function addMissing(table, name, handler) {
+  if (typeof table[name] === 'function') return false;
+  table[name] = mark(handler);
+  return true;
+}
+
+/**
+ * Build an ESTree-shaped stand-in for a Babel `ObjectMethod` / `ClassMethod`,
+ * whose function bits sit on the node itself rather than under `value`.
+ * `MethodDefinition` reads `node.value.{generator,params,body}`, so handing it
+ * a synthesized `value` lets the original handler do the work unchanged.
+ *
+ * @param {object} node
+ * @returns {object}
+ */
+function asMethodDefinition(node) {
+  return {
+    ...node,
+    kind:
+      typeof node.kind === 'string' && node.kind.length > 0
+        ? node.kind
+        : 'init',
+    value: {
+      type: 'FunctionExpression',
+      generator: Boolean(node.generator),
+      async: Boolean(node.async),
+      params: node.params ?? [],
+      body: node.body,
+    },
+  };
+}
+
+/**
+ * Patch the shared `astSyntax` table. Idempotent; safe to call from every
+ * entry point that is about to run `analyzeModule`.
+ *
+ * @param {{ requireFn?: NodeJS.Require, memoise?: boolean }} [options] Test
+ *   seam only — see {@link resolveSyntaxTable}. Production callers pass
+ *   nothing.
+ * @returns {{ available: boolean, applied: string[] }} `available` is false
+ *   when the upstream internals could not be resolved. `applied` names each
+ *   patch that was actually needed, so an upstream fix shows up as a
+ *   shorter list.
+ */
+export function install(options = {}) {
+  const { requireFn, memoise = true } = options;
+  if (memoise && installResult !== null) return installResult;
+
+  const table = resolveSyntaxTable(requireFn);
+  if (table === null) {
+    const unavailable = { available: false, applied: [] };
+    if (memoise) installResult = unavailable;
+    return unavailable;
+  }
+
+  const applied = [];
+  const add = (name, handler) => {
+    if (addMissing(table, name, handler)) applied.push(name);
+  };
+
+  // ---- Repair 1: Babel's RegExpLiteral shape -------------------------------
+  // Upstream reads `node.regex.pattern`, which only exists on an ESTree
+  // `Literal`. Babel puts `pattern`/`flags` on the node. Wrapped rather than
+  // replaced so the ESTree delegate path (`Literal` → `RegExpLiteral`) keeps
+  // its exact original output.
+  if (
+    typeof table.RegExpLiteral === 'function' &&
+    !table.RegExpLiteral[PATCH_MARKER]
+  ) {
+    const original = table.RegExpLiteral;
+    table.RegExpLiteral = mark(function RegExpLiteral(node, state) {
+      if (node?.regex === undefined) {
+        state.output.write(
+          `new RegExp(${JSON.stringify(node?.pattern ?? '')}, ` +
+            `${JSON.stringify(node?.flags ?? '')})`,
+        );
+        return;
+      }
+      return original.call(this, node, state);
+    });
+    applied.push('RegExpLiteral');
+  }
+
+  // ---- Repair 2: ObjectExpression's hard `this.Property()` dispatch --------
+  // `ObjectExpression` calls `this.Property(el)` on every element regardless
+  // of the element's actual type. Two Babel shapes get mis-routed by that:
+  //
+  //   `{ ...b }`    → a `SpreadElement` lands in `Property`, which reads
+  //                   `node.key.type` and throws. Upstream issue #24.
+  //   `{ m() {} }`  → an `ObjectMethod` has `kind: 'method'`, so `Property`'s
+  //                   `node.kind[0] !== 'i'` test sends the raw Babel node to
+  //                   `MethodDefinition`, which reads `node.value.generator`
+  //                   and throws.
+  //
+  // Patching `Property` rather than `ObjectExpression` keeps the patch small
+  // and leaves the indentation-sensitive object serialisation untouched:
+  // anything arriving here that is not actually a property node gets
+  // re-dispatched on its real type.
+  //
+  // `Property` and `ObjectProperty` are excluded from re-dispatch because the
+  // table aliases `ObjectProperty` to `Property` — re-dispatching either would
+  // recurse into this wrapper forever.
+  if (typeof table.Property === 'function' && !table.Property[PATCH_MARKER]) {
+    const original = table.Property;
+    const PROPERTY_TYPES = new Set(['Property', 'ObjectProperty']);
+    table.Property = mark(function Property(node, state) {
+      const type = node?.type;
+      if (
+        typeof type === 'string' &&
+        !PROPERTY_TYPES.has(type) &&
+        typeof this[type] === 'function'
+      ) {
+        return this[type](node, state);
+      }
+      return original.call(this, node, state);
+    });
+    applied.push('Property');
+  }
+
+  // ---- Missing handlers: Babel-only node types ----------------------------
+
+  // `await x` — mirrors upstream's `YieldExpression`.
+  add('AwaitExpression', function AwaitExpression(node, state) {
+    const output = state.output;
+    output.write('await ');
+    output.operators.push('await');
+    if (node.argument) this[node.argument.type](node.argument, state);
+  });
+
+  // `a?.b` / `a?.[b]` — mirrors upstream's `MemberExpression`, with `?.`
+  // recorded as its own operator so optional access is not counted as plain
+  // member access.
+  add(
+    'OptionalMemberExpression',
+    function OptionalMemberExpression(node, state) {
+      const output = state.output;
+      this[node.object.type](node.object, state);
+      if (node.computed) {
+        output.write('?.[');
+        this[node.property.type](node.property, state);
+        output.write(']');
+        output.operators.push('?.[]');
+      } else {
+        output.write('?.');
+        output.operators.push('?.');
+        this[node.property.type](node.property, state);
+      }
+    },
+  );
+
+  // `a?.()` — mirrors upstream's `CallExpression`.
+  add('OptionalCallExpression', function OptionalCallExpression(node, state) {
+    this[node.callee.type](node.callee, state);
+    state.output.write('?.');
+    state.output.operators.push('?.()');
+    ASTUtil().formatSequence(node.arguments ?? [], state, this);
+  });
+
+  // The callee node of a dynamic `import(...)`. Babel models the `import`
+  // keyword as its own node type; ESTree has no equivalent.
+  add('Import', function Import(_node, state) {
+    state.output.write('import');
+    state.output.operators.push('import()');
+  });
+
+  // `{ m() {} }` / `{ get m() {} }` — Babel's ObjectMethod.
+  add('ObjectMethod', function ObjectMethod(node, state) {
+    return this.MethodDefinition(asMethodDefinition(node), state);
+  });
+
+  // `class { m() {} }` — Babel's ClassMethod (ESTree: MethodDefinition).
+  add('ClassMethod', function ClassMethod(node, state) {
+    return this.MethodDefinition(asMethodDefinition(node), state);
+  });
+
+  // `class { p = 1 }` — Babel's ClassProperty (ESTree: PropertyDefinition).
+  const classProperty = function ClassProperty(node, state) {
+    const output = state.output;
+    if (node.static) {
+      output.write('static ');
+      output.operators.push('static');
+    }
+    if (node.computed) {
+      output.write('[');
+      this[node.key.type](node.key, state);
+      output.write(']');
+    } else {
+      this[node.key.type](node.key, state);
+    }
+    if (node.value) {
+      output.write(' = ');
+      output.operators.push('=');
+      this[node.value.type](node.value, state);
+    }
+    output.write(';');
+  };
+  add('ClassProperty', classProperty);
+  add('PropertyDefinition', classProperty);
+
+  const result = { available: true, applied };
+  if (memoise) installResult = result;
+  return result;
+}
+
+/**
+ * `ASTUtil` is only needed by the `OptionalCallExpression` handler, and only at
+ * call time — resolving it lazily keeps `install()` free of a second deep
+ * import that could fail at module load. Anchored through the kernel for the
+ * same reason as {@link resolveSyntaxTable}.
+ *
+ * `formatSequence` is a pure helper that takes the traveler and state as
+ * arguments, so which copy answers is immaterial — but resolving it the same
+ * way keeps one rule in this file rather than two.
+ *
+ * @returns {{ formatSequence: Function }}
+ */
+function ASTUtil() {
+  const fromKernel = createRequire(require.resolve('typhonjs-escomplex'));
+  const mod = fromKernel(
+    'typhonjs-escomplex-commons/dist/utils/ast/ASTUtil.js',
+  );
+  return mod?.default ?? mod;
+}
+
+// A test that needs to re-run the install against the already-patched table
+// passes `{ memoise: false }` rather than resetting module state — the patches
+// are self-detecting via PATCH_MARKER, so a non-memoised re-run is exactly the
+// idempotency assertion worth making.

package/.agents/scripts/lib/maintainability-engine.js

@@ -1,25 +1,80 @@
 import fs from 'node:fs';
 import escomplex from 'typhonjs-escomplex';
+import { install as installAstCompat } from './escomplex-ast-compat.js';
 import { transpileIfNeeded } from './transpile.js';
 
 /**
  * Calculates the maintainability score of a JavaScript source file or string.
  * Uses `typhonjs-escomplex` internally, which provides a maintainability index
  * based on the Halstead Volume, Cyclomatic Complexity, and Lines of Code.
+ *
+ * The kernel's code generator predates the Babel AST its own parser emits, so
+ * ordinary modern syntax (`?.`, `await` in a loop head, a regex in a loop
+ * head, object spread in a default parameter) aborts the whole analysis.
+ * `escomplex-ast-compat` repairs that before any scoring runs — see that
+ * module for the defect and the upstream status.
+ */
+installAstCompat();
+
+/**
+ * Sentinel score for a file the kernel cannot analyse.
+ *
+ * A real maintainability index never reaches 0 for runnable code — the
+ * escomplex floor is ~10–20 — so 0 has long been used as an out-of-band
+ * "unscorable" marker. That overload is the bug: consumers drop `mi === 0`
+ * rows, so an unscorable file silently vanishes from the baseline instead of
+ * being reported, and no amount of re-seeding can ever give it a row.
+ *
+ * Deliberately module-private. The numeric return is kept for backwards
+ * compatibility, but the *value* is not something a caller should branch on —
+ * that is the overload this change exists to stop propagating. Callers that
+ * need to tell "unscorable" from "genuinely terrible" read the `unscorable`
+ * flag from {@link scoreSource} / {@link scoreFile}.
+ */
+const UNSCORABLE = 0;
+
+/**
+ * Score a raw string, distinguishing "the kernel could not analyse this" from
+ * "this scored badly".
+ *
+ * @param {string} sourceCode The JavaScript source code.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ *   `score` is {@link UNSCORABLE} when `unscorable` is true; `reason` carries
+ *   the kernel's own error message so a consumer can report *why* rather than
+ *   just omitting the file.
+ */
+export function scoreSource(sourceCode) {
+  try {
+    const score = escomplex.analyzeModule(sourceCode)?.maintainability;
+    return Number.isFinite(score)
+      ? { score, unscorable: false, reason: null }
+      : unscorable(`kernel returned a non-finite index (${String(score)})`);
+  } catch (err) {
+    return unscorable(
+      `${err?.constructor?.name ?? 'Error'}: ${err?.message ?? 'unknown kernel failure'}`,
+    );
+  }
+}
+
+/**
+ * @param {string} reason
+ * @returns {{ score: number, unscorable: boolean, reason: string }}
  */
+function unscorable(reason) {
+  return { score: UNSCORABLE, unscorable: true, reason };
+}
+
 /**
  * Calculate score for a raw string of source code.
+ *
+ * Returns 0 for unscorable input, which is ambiguous by construction — see
+ * {@link UNSCORABLE}. Prefer {@link scoreSource} in new code.
+ *
  * @param {string} sourceCode The JavaScript source code.
  * @returns {number} Score between 0 and 171. Higher is better.
  */
 export function calculateForSource(sourceCode) {
-  try {
-    const result = escomplex.analyzeModule(sourceCode);
-    return result.maintainability;
-  } catch (_err) {
-    // Return 0 if the parser fails (e.g. invalid syntax)
-    return 0;
-  }
+  return scoreSource(sourceCode).score;
 }
 
 /**
@@ -34,17 +89,34 @@ export function calculateForSource(sourceCode) {
  *   be parsed (escomplex parse error or TS transpile failure).
  */
 export function calculateForFile(filePath) {
+  return scoreFile(filePath).score;
+}
+
+/**
+ * Score a file, distinguishing "unscorable" from "scored badly".
+ *
+ * The transpile-failure and kernel-failure cases are reported separately
+ * because they need different fixes: a transpile failure is usually the
+ * consumer's own syntax or `tsconfig`, whereas a kernel failure is the
+ * upstream generator gap described in `escomplex-ast-compat.js`.
+ *
+ * @param {string} filePath Path to the JS/TS source file.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ */
+export function scoreFile(filePath) {
+  let sourceCode;
   try {
-    const sourceCode = fs.readFileSync(filePath, 'utf-8');
-    const prepared = transpileIfNeeded(filePath, sourceCode);
-    if (prepared === null) return 0;
-    return calculateForSource(prepared);
+    sourceCode = fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
     if (err.code === 'ENOENT') {
       throw new Error(`File not found: ${filePath}`);
     }
     throw err;
   }
+
+  const prepared = transpileIfNeeded(filePath, sourceCode);
+  if (prepared === null) return unscorable('TypeScript transpile failed');
+  return scoreSource(prepared);
 }
 
 /**

package/.agents/scripts/lib/maintainability-unscorable.js

@@ -0,0 +1,60 @@
+/**
+ * maintainability-unscorable.js — reporting for files the MI kernel cannot
+ * analyse.
+ *
+ * A file the kernel throws on has no maintainability index, so it gets no
+ * baseline row — a phantom `mi: 0` would poison the `min`/p50 rollup and let
+ * real regressions hide behind it. Dropping the row is therefore correct; doing
+ * it *silently* is not. Without a report, an unscorable file is
+ * indistinguishable from a file nobody added yet: the scorer emits nothing, the
+ * scope gate sees an absence it cannot explain, and re-seeding the baseline can
+ * never produce the missing row no matter how many times it runs.
+ *
+ * Kept separate from `maintainability-utils.js` so the scoring path stays about
+ * scoring and this stays about explaining.
+ */
+
+import { Logger } from './Logger.js';
+
+/**
+ * Report every unscorable file, then summarise.
+ *
+ * @param {Array<{ relPath: string, unscorable?: boolean, reason?: string|null }>} perFile
+ * @returns {number} how many files were unscorable, for the caller's own use.
+ */
+export function reportUnscorable(perFile) {
+  const unscorable = (perFile ?? []).filter((entry) => entry?.unscorable);
+  if (unscorable.length === 0) return 0;
+
+  for (const { relPath, reason } of unscorable) {
+    Logger.error(
+      `[Maintainability] UNSCORABLE ${relPath}: ${reason ?? 'unknown kernel failure'}`,
+    );
+  }
+  Logger.error(
+    `[Maintainability] ${unscorable.length} file(s) could not be scored and will have ` +
+      'no baseline row, so the maintainability gate cannot see them. If the cause is a ' +
+      'kernel AST gap, add a handler in lib/escomplex-ast-compat.js rather than an ' +
+      'allowlist entry.',
+  );
+  return unscorable.length;
+}
+
+/**
+ * Whether a per-file entry carries a real maintainability index and so belongs
+ * in the baseline.
+ *
+ * An unscorable entry carries the sentinel score, not an index — letting it
+ * through would write an `mi: 0` phantom and drag the rollup floor down with it
+ * (Story #2467). `score === null` is the separate I/O-failure case.
+ *
+ * Tests for a *number* rather than `score !== null`, because the latter passes
+ * anything absent: `undefined !== null` is true, so a missing entry or one with
+ * no `score` key at all would have been treated as scored.
+ *
+ * @param {{ score?: number|null, unscorable?: boolean }} entry
+ * @returns {boolean}
+ */
+export function isScored(entry) {
+  return typeof entry?.score === 'number' && !entry.unscorable;
+}

package/.agents/scripts/lib/maintainability-utils.js

@@ -4,7 +4,8 @@ import { minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
-import { calculateForFile } from './maintainability-engine.js';
+import { scoreFile } from './maintainability-engine.js';
+import { isScored, reportUnscorable } from './maintainability-unscorable.js';
 
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
@@ -128,6 +129,13 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * worker-side per-item failures surface as a `null` score that is
  * filtered out before assembly.
  *
+ * A file the kernel cannot analyse is also dropped — a phantom `mi: 0` row
+ * poisons the rollup — but it is **reported** on the way out, with the
+ * kernel's own error text, and the count is summarised at the end of the run.
+ * Silently omitting these is what let a file sit unmeasured indefinitely: the
+ * scorer emitted no row, so no amount of re-seeding could ever produce one,
+ * and nothing said so.
+ *
  * @param {string[]} paths
  * @returns {Promise<Record<string, number>>}
  */
@@ -142,7 +150,7 @@ export async function calculateAll(paths) {
   if (indexed.length < SERIAL_THRESHOLD) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
-        return { relPath, score: calculateForFile(abs) };
+        return { relPath, ...scoreFile(abs) };
       } catch (err) {
         Logger.error(
           `[Maintainability] Failed to process ${abs}: ${err.message}`,
@@ -166,7 +174,7 @@ export async function calculateAll(paths) {
       if (r.score === null && r.error) {
         Logger.error(`[Maintainability] Failed to process ${abs}: ${r.error}`);
       }
-      return { relPath, score: r.score };
+      return { relPath, ...r };
     });
   }
 
@@ -174,9 +182,10 @@ export async function calculateAll(paths) {
     a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
   );
 
+  reportUnscorable(perFile);
+
   const scores = {};
-  for (const { relPath, score } of perFile) {
-    if (score === null) continue;
+  for (const { relPath, score } of perFile.filter(isScored)) {
     scores[relPath] = score;
   }
   return scores;

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -75,6 +75,14 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
    * reflect code findings only.
    */
   TOOL_DEGRADED: 'tool-degraded',
+  /**
+   * The light delivery path refused a scope — a suitability-gate `ask-operator`
+   * or a blocked diff backstop. Story #4856 added it because neither rejection
+   * emitted anything, so an over-tight ceiling could only reach the framework
+   * as anecdote; the roll-up aggregating these by category is what makes the
+   * ceilings recalibratable from recorded evidence.
+   */
+  LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */
@@ -355,9 +363,18 @@ export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
  * `tool-degraded` from the scoped-lint runner from one out of lens
  * materialization. It is descriptive, never a routing key.
  *
+ * `ts` joined the shape in Story #4850, and it joined it **here** rather than
+ * in a second read beside the run-scope gather. The composer had no notion of
+ * *when* its corpus happened, so it borrowed the triggering run as the window
+ * and titled every proposal with a claim the evidence block below it already
+ * contradicted. Carrying the timestamp through the one shared normalizer is
+ * what lets the recurrence window be both bounded and describable; re-reading
+ * it beside one of the two gathers is precisely the drift that made the
+ * recovery-netting unreachable in Story #4649.
+ *
  * @param {unknown} parsed          One parsed NDJSON row.
  * @param {number}  fallbackStoryId Stream owner, used when the row has none.
- * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, details: object }|null}
+ * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, tool: string, ts: string|null, details: object }|null}
  */
 export function normalizeGatheredSignal(parsed, fallbackStoryId) {
   if (!parsed || typeof parsed !== 'object') return null;
@@ -374,6 +391,7 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
     source: parsed.source === 'framework' ? 'framework' : 'consumer',
     storyId: Number.isInteger(recordStoryId) ? recordStoryId : fallbackStoryId,
     tool: typeof emitterTool === 'string' ? emitterTool.trim() : '',
+    ts: parsableTimestamp(parsed.ts),
     details:
       parsed.details && typeof parsed.details === 'object'
         ? parsed.details
@@ -381,6 +399,24 @@ export function normalizeGatheredSignal(parsed, fallbackStoryId) {
   };
 }
 
+/**
+ * The row's `ts` when it is a string a `Date` can read, else `null`.
+ *
+ * `signal-event.schema.json` requires `ts`, and both producers stamp
+ * `new Date().toISOString()` — but the gathers read whatever survives on disk,
+ * including rows a truncated write left half-formed. Resolving to `null`
+ * rather than guessing a time is what lets the recurrence window exclude an
+ * undateable row explicitly instead of aging it in as "recent".
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function parsableTimestamp(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return Number.isFinite(Date.parse(trimmed)) ? trimmed : null;
+}
+
 /**
  * Pure predicate: is this signal a recovery marker for its own category?
  * Shared with the retro composer so the "recovered" discriminator is read