@trazum/core 1.55.0 → 1.56.1

package/src/history.ts

@@ -60,6 +60,58 @@ export interface HistoryRun {
   /** First and last values of the run, so the reader judges the size. */
   from: number;
   to: number;
+  /**
+   * Days inside this run's stretch that no report covers.
+   *
+   * A run is *consecutive reports*, and until this field existed it read as
+   * *consecutive time*. Four reports with a three-week hole between the second
+   * and the third is not "climbing for four periods" in any sense a reader
+   * would act on — the climb may have reversed and come back inside the hole,
+   * and nothing here can see it. The caveat travels with the finding rather
+   * than living in another field the reader has to cross-reference, because a
+   * finding that needs a second lookup to be read correctly will be read
+   * incorrectly.
+   */
+  unmeasuredDays: number;
+}
+
+/**
+ * A stretch of calendar time no stored report covers.
+ *
+ * Arithmetic on the spans, not an inference about a schedule: this module has
+ * no idea how often somebody meant to run anything, and guessing a cadence in
+ * order to call a gap late would be the tool deciding what the reader's
+ * routine is. A hole between one report's end and the next one's start is a
+ * fact about the reports.
+ *
+ * It is also the whole of what "nobody produced this series on a schedule"
+ * looks like from inside the data: a cron that died three weeks ago does not
+ * announce itself, it just stops adding points — and a shorter series and a
+ * series with a hole in it read identically until somebody says which.
+ */
+export interface UnmeasuredStretch {
+  fromMs: number;
+  toMs: number;
+  days: number;
+  /** The report that ends where the hole begins. */
+  afterName: string;
+  /** The report that begins where the hole ends. */
+  beforeName: string;
+}
+
+/**
+ * Two reports covering some of the same calendar time.
+ *
+ * `history` never sums `totalUsd` across periods, but a reader with the
+ * document in a spreadsheet will, and two reports over the same fortnight
+ * count that fortnight twice. Named rather than merged: which of the two is
+ * the better measurement is not knowable from here, and picking one would be
+ * throwing away money on a guess.
+ */
+export interface OverlappingReports {
+  a: string;
+  b: string;
+  days: number;
 }
 
 /** The same action planned again and again: a decision nobody is executing. */
@@ -91,10 +143,87 @@ export interface HistoryDocument {
    * named here and in no series above, never silently absorbed.
    */
   undatedReports: string[];
+  /**
+   * Calendar time between the first report's start and the last one's end
+   * that no report covers, oldest first.
+   *
+   * The series is stated with its holes rather than closed over them: a
+   * scheduled run that stopped three weeks ago produces a series that looks
+   * exactly like a shorter one, and only this field tells the two apart.
+   */
+  unmeasured: UnmeasuredStretch[];
+  /** The same calendar time covered by two reports. Named, never merged. */
+  overlappingReports: OverlappingReports[];
 }
 
 export const MIN_RUN = 3;
 
+const DAY_MS = 86_400_000;
+
+/**
+ * Whole days between two instants, never negative and never rounded up.
+ *
+ * Rounded down deliberately: a gap this module calls three days must be at
+ * least three days. A ceiling would make the smallest possible hole read as a
+ * day of missing measurement, which is the flattering direction inverted —
+ * alarming rather than reassuring, and just as wrong.
+ */
+const daysBetween = (fromMs: number, toMs: number): number =>
+  Math.max(0, Math.floor((toMs - fromMs) / DAY_MS));
+
+/**
+ * The holes and the overlaps in a set of dated reports.
+ *
+ * One sweep in start order. A report that ends before the furthest end seen so
+ * far is contained in what is already covered and moves nothing; one that
+ * starts after it opens a hole; one that starts before it overlaps.
+ */
+function coverageOf(
+  dated: { name: string; fromMs: number; toMs: number }[],
+): { unmeasured: UnmeasuredStretch[]; overlaps: OverlappingReports[] } {
+  const unmeasured: UnmeasuredStretch[] = [];
+  const overlaps: OverlappingReports[] = [];
+  if (dated.length === 0) return { unmeasured, overlaps };
+
+  let coveredTo = dated[0]!.toMs;
+  let coveredBy = dated[0]!.name;
+  for (let i = 1; i < dated.length; i += 1) {
+    const report = dated[i]!;
+    if (report.fromMs > coveredTo) {
+      const days = daysBetween(coveredTo, report.fromMs);
+      // A hole shorter than a whole day is the seam between two adjacent
+      // exports, not a stretch nobody measured.
+      if (days > 0) {
+        unmeasured.push({
+          fromMs: coveredTo,
+          toMs: report.fromMs,
+          days,
+          afterName: coveredBy,
+          beforeName: report.name,
+        });
+      }
+    } else if (report.fromMs < coveredTo) {
+      const days = daysBetween(report.fromMs, Math.min(coveredTo, report.toMs));
+      if (days > 0) overlaps.push({ a: coveredBy, b: report.name, days });
+    }
+    if (report.toMs > coveredTo) {
+      coveredTo = report.toMs;
+      coveredBy = report.name;
+    }
+  }
+  return { unmeasured, overlaps };
+}
+
+/** Days of hole inside a stretch of the timeline. */
+const unmeasuredWithin = (
+  unmeasured: UnmeasuredStretch[],
+  fromMs: number,
+  toMs: number,
+): number =>
+  unmeasured
+    .filter((hole) => hole.fromMs >= fromMs && hole.toMs <= toMs)
+    .reduce((sum, hole) => sum + hole.days, 0);
+
 /** The longest run of strictly consecutive movement ending anywhere in the series. */
 function longestRun(
   points: (number | null)[],
@@ -152,6 +281,12 @@ export function buildHistory(
 
   const cacheShareSeries = dated.map((r) => r.cacheReadShare);
 
+  const { unmeasured, overlaps: overlappingReports } = coverageOf(periods);
+
+  /** The unmeasured days a run spans, from the report it starts in to the one it ends in. */
+  const holeIn = (start: number, length: number): number =>
+    unmeasuredWithin(unmeasured, periods[start]!.fromMs, periods[start + length]!.toMs);
+
   const runs: HistoryRun[] = [];
   for (const series of labelSeries) {
     const run = longestRun(series.points, 1);
@@ -163,6 +298,7 @@ export function buildHistory(
       sinceName: periods[run.start]!.name,
       from: series.points[run.start]!,
       to: series.points[run.start + run.length]!,
+      unmeasuredDays: holeIn(run.start, run.length),
     });
   }
   for (const series of modelShareSeries) {
@@ -175,6 +311,7 @@ export function buildHistory(
       sinceName: periods[run.start]!.name,
       from: series.points[run.start]!,
       to: series.points[run.start + run.length]!,
+      unmeasuredDays: holeIn(run.start, run.length),
     });
   }
   {
@@ -187,6 +324,7 @@ export function buildHistory(
         sinceName: periods[run.start]!.name,
         from: cacheShareSeries[run.start]!,
         to: cacheShareSeries[run.start + run.length]!,
+        unmeasuredDays: holeIn(run.start, run.length),
       });
     }
   }
@@ -232,6 +370,8 @@ export function buildHistory(
     runs,
     repeatedPlanActions,
     undatedReports,
+    unmeasured,
+    overlappingReports,
   };
 }
 

package/src/index.ts

@@ -51,6 +51,8 @@ export { explainGateFailure, gateMargin, GATE_MARGIN_TIGHT } from './gate-explai
 export { measuredUsage, labelCoverage, MIN_SCALE_DAYS, SCALE_TO_DAYS } from './measured-profile.js';
 export { assignSources, fleetRollup } from './fleet.js';
 export { rollUp } from './rollup.js';
+export { heartbeats } from './heartbeat.js';
+export { ruleYield } from './rule-yield.js';
 export { buildPlan, planLabelName, parsePlanDocument, PLAN_ACTION_KINDS } from './plan.js';
 export type { PlanParseFailure, PlanParseResult } from './plan.js';
 export type { PlanAction, PlanActionKind, PlanAssumption, PlanDocument } from './plan.js';
@@ -245,9 +247,24 @@ export type {
   UnavailableFinding,
   UsageBucket,
 } from './connector.js';
-export type { HistoryDocument, HistoryRun, RepeatedPlanAction, StoredReport } from './history.js';
+export type {
+  HistoryDocument,
+  HistoryRun,
+  RepeatedPlanAction,
+  StoredReport,
+  UnmeasuredStretch,
+  OverlappingReports,
+} from './history.js';
 export type { CannotTellReason, PlanVerification, VerifiedAction, VerifyOutcome } from './verify.js';
 export type { FleetSource, FleetRollup } from './fleet.js';
+export type { RuleYield, RuleYieldReport } from './rule-yield.js';
+export type {
+  Heartbeat,
+  HeartbeatInput,
+  HeartbeatKind,
+  HeartbeatReport,
+  HeartbeatVerdict,
+} from './heartbeat.js';
 export type {
   RollupInput,
   RollupDocument,

package/src/rule-yield.ts

@@ -0,0 +1,205 @@
+/**
+ * Which rules actually recover anything, and how much.
+ *
+ * The README says plainly that the deterministic rules recover about one per
+ * cent, and that is the fair complaint about this tool. It is also an
+ * **aggregate**, and an aggregate is where a distribution goes to hide: seven
+ * rules recovering one per cent between them could be seven rules each doing a
+ * seventh of the work, or two rules doing all of it beside five that have never
+ * changed a byte of anybody's prompt.
+ *
+ * Nobody here had measured which. That is the wrong place to start an arc
+ * about raising the ceiling — what to add on the model's side of the line is a
+ * question about what the dictionary side already covers, and "about one per
+ * cent" does not answer it.
+ *
+ * **Two numbers per rule, and they are not the same number.**
+ *
+ * - **Alone** is what the rule saves when it is the only one running.
+ * - **Marginal** is what the whole set loses when the rule is removed.
+ *
+ * They diverge exactly where rules overlap, which is most of the interesting
+ * cases: `duplicate-lines` and `duplicate-blocks` both find a repeated stanza,
+ * so each has a real `alone` and a `marginal` near zero. Reporting either
+ * figure by itself would be wrong in a different direction — `alone` alone
+ * makes an overlapping rule look load-bearing, and `marginal` alone makes it
+ * look inert. The report carries both and **never reconciles them into one**,
+ * for the same reason a measurement and a projection are never added here.
+ *
+ * **Inert is a fact about the corpus, never about the rule.** A rule that finds
+ * nothing across twenty-one files has not been shown to be useless; it has been
+ * shown that these twenty-one files do not contain what it looks for. The
+ * distinction is the whole difference between "delete this rule" and "measure
+ * it on something else", and this module refuses to make the first claim.
+ *
+ * Browser-safe: prompts in, arithmetic out, no filesystem.
+ */
+
+import { optimize } from './optimize.js';
+import type { OptimizeOptions, RuleId } from './types.js';
+
+export interface RuleYield {
+  id: RuleId;
+  /** Tokens saved when this rule is the only one running, across every prompt. */
+  alone: number;
+  /**
+   * Tokens the full set loses when this rule is removed.
+   *
+   * Zero with a non-zero `alone` means every token it finds is found by
+   * something else too — an overlap, not a defect, and not a reason to delete
+   * anything without knowing which rule is the better one to keep.
+   */
+  marginal: number;
+  /** How many prompts it changed at all, running alone. */
+  prompts: number;
+}
+
+export interface RuleYieldReport {
+  schemaVersion: 1;
+  /** Prompts measured. */
+  prompts: number;
+  /** Tokens across every prompt before any rule ran. */
+  tokensBefore: number;
+  /**
+   * Tokens **the rules** save across every prompt.
+   *
+   * The whole run's saving minus the floor below, because they are not the
+   * same thing and the first version of this module reported the difference as
+   * if it were the rules' work. Run over a corpus the rules do not touch, that
+   * version said the optimiser saved twenty-one tokens and every rule was
+   * redundant — a sentence assembled out of somebody else's arithmetic.
+   */
+  tokensSaved: number;
+  /**
+   * Tokens the optimiser saves with **every rule disabled**.
+   *
+   * Normalisation the optimiser does regardless of the rule set. Named rather
+   * than folded in: it is a real saving and it is not a rule's, and a report
+   * that credited it to the rules would be flattering exactly the thing this
+   * measurement exists to be honest about.
+   */
+  floor: number;
+  /** Per rule, largest `marginal` first, then largest `alone`. */
+  rules: RuleYield[];
+  /**
+   * `alone` summed over every rule.
+   *
+   * Stated beside `tokensSaved` and deliberately not reconciled with it: the
+   * gap between them **is** the overlap, and a single "total" would be the one
+   * number that cannot be true. Larger than `tokensSaved` means rules are
+   * finding the same tokens; equal means they are disjoint on this corpus.
+   */
+  sumOfAlone: number;
+  /**
+   * Rules that save something alone and nothing at the margin — every token
+   * they find, another rule finds too. On **this corpus**.
+   */
+  redundantHere: RuleId[];
+  /**
+   * Rules that changed nothing at all — they never fired. On **this corpus**,
+   * which is the only claim the arithmetic supports: a rule that finds nothing
+   * in these files has not been shown to find nothing anywhere.
+   */
+  inertHere: RuleId[];
+  /**
+   * Rules that **fired and recovered nothing**: they changed the prompt and
+   * the token count did not move.
+   *
+   * Kept apart from `inertHere`, because the two look identical in a saving
+   * column and mean opposite things. A rule that never fires has not been
+   * exercised; a rule that fires and saves nothing has been exercised and is
+   * altering somebody's prompt for no measured benefit — which is a finding
+   * about the rule rather than about the corpus, and the one this measurement
+   * was least likely to produce and most worth producing.
+   *
+   * `emphasis` lands here on a prompt whose shouted words it lowercases: same
+   * words, same count, different instruction.
+   */
+  firedWithoutSavingHere: RuleId[];
+  /**
+   * How the tokens were counted, so the reader knows the margin.
+   *
+   * `heuristic` carries the estimator's documented band, and every figure here
+   * inherits it — a rule whose marginal yield is a handful of tokens is inside
+   * the noise, and the report says which counter it used rather than leaving
+   * somebody to assume an exact one.
+   */
+  tokenSource: 'heuristic' | 'external';
+}
+
+/**
+ * Measures each rule's yield over a set of prompts.
+ *
+ * `rules` is the full set to measure — the caller passes it rather than this
+ * module reaching for the catalogue, so a subset can be measured and so the
+ * list has one home. Every run uses the same options, so the level and the
+ * token counter are the caller's and not this module's assumption.
+ */
+export function ruleYield(
+  prompts: string[],
+  rules: readonly RuleId[],
+  options: OptimizeOptions = {},
+): RuleYieldReport {
+  const run = (disableRules: RuleId[]) =>
+    prompts.map((prompt) => optimize(prompt, { ...options, disableRules }));
+
+  const whole = run([]);
+  const tokensBefore = whole.reduce((sum, result) => sum + result.tokensBefore, 0);
+  const wholeSaved = whole.reduce((sum, result) => sum + result.tokensSaved, 0);
+
+  /**
+   * What the optimiser saves with every rule off.
+   *
+   * Whitespace normalisation and the like happen either way, and crediting
+   * them to the rules is how "the rules recover about one per cent" survives
+   * on a corpus where the rules recover nothing.
+   */
+  const floorResults = run([...rules]);
+  const floor = floorResults.reduce((sum, result) => sum + result.tokensSaved, 0);
+  const tokensSaved = Math.max(0, wholeSaved - floor);
+
+  const measured: RuleYield[] = rules.map((id) => {
+    // Alone: everything else off.
+    const only = run(rules.filter((other) => other !== id));
+    const alone = Math.max(0, only.reduce((sum, result) => sum + result.tokensSaved, 0) - floor);
+    // Changed against the floor's own output, not against the original: the
+    // normalisation changes every prompt, and counting that as this rule
+    // having fired is how every rule came back as touching every file.
+    const changed = only.filter(
+      (result, index) => result.optimized !== floorResults[index]?.optimized,
+    ).length;
+
+    // Marginal: everything on but this one.
+    const without = run([id]);
+    const withoutSaved = without.reduce((sum, result) => sum + result.tokensSaved, 0);
+
+    return {
+      id,
+      alone,
+      // Never negative: removing a rule cannot make the set save more, and a
+      // rounding artefact that said it did would be a finding nobody could act
+      // on. Clamped rather than reported, because the clamp is the honest
+      // reading of a difference inside the counter's own noise.
+      marginal: Math.max(0, wholeSaved - withoutSaved),
+      prompts: changed,
+    };
+  });
+
+  measured.sort((a, b) => b.marginal - a.marginal || b.alone - a.alone);
+
+  return {
+    schemaVersion: 1,
+    prompts: prompts.length,
+    tokensBefore,
+    tokensSaved,
+    floor,
+    rules: measured,
+    sumOfAlone: measured.reduce((sum, rule) => sum + rule.alone, 0),
+    redundantHere: measured.filter((rule) => rule.alone > 0 && rule.marginal === 0).map((rule) => rule.id),
+    inertHere: measured.filter((rule) => rule.prompts === 0).map((rule) => rule.id),
+    firedWithoutSavingHere: measured
+      .filter((rule) => rule.prompts > 0 && rule.alone === 0)
+      .map((rule) => rule.id),
+    tokenSource: whole[0]?.tokenSource ?? 'heuristic',
+  };
+}

package/src/rules.ts

@@ -300,9 +300,28 @@ const nearDuplicateBlocksRule: Rule = {
   },
 };
 
-/** Every rule, in the order they must run. */
+/**
+ * Every rule, in the order they must run.
+ *
+ * **The order decides what the reader is told, not just how fast this runs.**
+ * A repeated stanza is a repeated *block* and also a set of repeated *lines*,
+ * so all three of the deletion rules can find it and whichever runs first
+ * takes it. Coarsest first means the report says "one repeated paragraph"
+ * rather than "three repeated lines" for the same saving — the same number
+ * attached to a sentence somebody can act on instead of three they have to
+ * reassemble.
+ *
+ * That was an unstated consequence until `rules --measure` made the overlap
+ * visible: the leave-one-out measurement credits each of the three with the
+ * whole saving, because each of them *would* have caught it alone. The applied
+ * run credits exactly one, and this list is what picks which.
+ *
+ * `rules.test.js` pins both facts, so a reorder that quietly changes the
+ * attribution fails the build rather than changing what users read.
+ */
 export const RULES: readonly Rule[] = [
-  // Whole-block deletions first, so the rest works over less text.
+  // Whole-block deletions first: less text for the rest to walk, and the
+  // coarsest description of what was removed.
   duplicateBlocksRule,
   nearDuplicateBlocksRule,
   duplicateLinesRule,