@goodbones/campaigns 0.1.1-beta.1 → 0.1.1-beta.3

package/src/core/campaigns.ts

@@ -28,12 +28,16 @@ import type {
   CampaignUnit,
   Detector,
   Holdout,
+  Measure,
+  MeasureDirection,
+  MeasureSource,
   ObjectiveRule,
   OnTouch,
   PerimeterRule,
   PhaseRule,
   ReportFormat,
 } from "../domain/config.js";
+import type { CampaignMeasure } from "../ports/campaign-measure.js";
 import type { CampaignPredicate, Range } from "../ports/campaign-predicate.js";
 import type { ReportSource, ReportSpec } from "../ports/report-source.js";
 
@@ -139,19 +143,48 @@ export type CompiledSectorTerm =
   | { readonly kind: "oneRoot" }
   | { readonly kind: "oneHost"; readonly hosts: ReadonlyArray<RegExp> };
 
+// Where a scalar objective's number comes from, per file. A `report` source
+// is its report term compiled as a detector and counted at `match`, and an
+// `fn` source is an `fn` detector read as a number — so both reach the
+// function loading, the report pre-reading and the syntax parse by the
+// paths every detector does.
+export type CompiledMeasureSource =
+  | { readonly kind: "lines" }
+  | { readonly kind: "files" }
+  | { readonly kind: "report"; readonly detect: CompiledDetector }
+  | { readonly kind: "fn"; readonly detect: CompiledDetector & { readonly kind: "fn" } };
+
+export type CompiledMeasure =
+  | { readonly kind: "sum"; readonly of: CompiledMeasureSource }
+  | {
+      readonly kind: "ratio";
+      readonly of: CompiledMeasureSource;
+      readonly per: CompiledMeasureSource;
+      readonly scale: number;
+    }
+  | { readonly kind: "command"; readonly command: string; readonly pattern: RegExp | null };
+
 export type CompiledObjective = {
   readonly name: string;
   readonly id: string;
   readonly campaign: string;
   readonly message: string;
   readonly why: string | null;
-  readonly holdout: Holdout;
+  // `null` for a scalar objective, which holds nothing out.
+  readonly holdout: Holdout | null;
   // The unit a per-file detector answers at; `declaration` for the
   // objectives no per-file detector answers, whose entries are `file#subject`.
   readonly unit: CampaignUnit;
   readonly detect: CompiledDetector | null;
   readonly sector: CompiledSectorTerm | null;
   readonly endState: { readonly phase: string; readonly family: string } | null;
+  // A scalar objective: its number, which way is better, the slack either
+  // side of the record, and the value at which it is met (`null` for a
+  // standing measure, which only ratchets).
+  readonly measure: CompiledMeasure | null;
+  readonly direction: MeasureDirection;
+  readonly tolerance: number;
+  readonly target: number | null;
   readonly until: string | null;
   readonly probes: {
     readonly fires: ReadonlyArray<CampaignProbe>;
@@ -376,6 +409,51 @@ const compileDetector = (
   return Result.succeed({ kind: "fn", name: detector.fn });
 };
 
+const compileMeasureSource = (
+  name: string,
+  source: MeasureSource,
+): Result.Result<CompiledMeasureSource, PatternInvalid> => {
+  if ("lines" in source) return Result.succeed({ kind: "lines" });
+  if ("files" in source) return Result.succeed({ kind: "files" });
+  if ("fn" in source)
+    return Result.succeed({ kind: "fn", detect: { kind: "fn", name: source.fn } });
+  const detect = compileDetector(name, source);
+  return Result.isFailure(detect)
+    ? Result.fail(detect.failure)
+    : Result.succeed({ kind: "report", detect: detect.success });
+};
+
+const compileMeasure = (
+  name: string,
+  measure: Measure,
+): Result.Result<CompiledMeasure, PatternInvalid> => {
+  if ("command" in measure) {
+    const pattern = compilePatterns(name, "measure.pattern", measure.pattern);
+    if (Result.isFailure(pattern)) return Result.fail(pattern.failure);
+    return Result.succeed({
+      kind: "command",
+      command: measure.command,
+      pattern: pattern.success[0] ?? null,
+    });
+  }
+  if ("ratio" in measure) {
+    const of = compileMeasureSource(name, measure.ratio.of);
+    if (Result.isFailure(of)) return Result.fail(of.failure);
+    const per = compileMeasureSource(name, measure.ratio.per);
+    if (Result.isFailure(per)) return Result.fail(per.failure);
+    return Result.succeed({
+      kind: "ratio",
+      of: of.success,
+      per: per.success,
+      scale: measure.ratio.scale,
+    });
+  }
+  const of = compileMeasureSource(name, measure);
+  return Result.isFailure(of)
+    ? Result.fail(of.failure)
+    : Result.succeed({ kind: "sum", of: of.success });
+};
+
 export const compileObjective = (
   rule: ObjectiveRule,
 ): Result.Result<CompiledObjective, PatternInvalid> => {
@@ -399,17 +477,28 @@ export const compileObjective = (
       sector = { kind: "oneHost", hosts: hosts.success };
     }
   }
+  let measure: CompiledMeasure | null = null;
+  if (rule.measure !== undefined) {
+    const compiled = compileMeasure(rule.name, rule.measure);
+    if (Result.isFailure(compiled)) return Result.fail(compiled.failure);
+    measure = compiled.success;
+  }
+  const holdout = rule.holdout ?? null;
   return Result.succeed({
     name: rule.name,
     id: rule.id,
     campaign: rule.campaign,
     message: rule.message,
     why: rule.why ?? null,
-    holdout: rule.holdout,
-    unit: rule.holdout === "sector" ? "declaration" : rule.holdout,
+    holdout,
+    unit: holdout === null || holdout === "sector" ? "declaration" : holdout,
     detect,
     sector,
     endState: rule.endState ?? null,
+    measure,
+    direction: rule.direction ?? "down",
+    tolerance: rule.tolerance ?? 0,
+    target: rule.target ?? null,
     until: rule.until ?? null,
     probes: rule.probes,
   });
@@ -1087,6 +1176,7 @@ export const reportSpecsOf = (
     for (const objective of rule.objectives) {
       if (objective.detect !== null) walk(objective.detect);
       if (objective.sector?.kind === "has") walk(objective.sector.detect);
+      for (const detect of measureDetectorsOf(objective)) walk(detect);
     }
     if (rule.perimeter?.kind === "match") walk(rule.perimeter.detect);
   }
@@ -1098,6 +1188,119 @@ export const evaluateObjectives = (
   input: CampaignInput,
 ): ReadonlyArray<CampaignHit> => selected.flatMap((rule) => evaluateObjective(rule, input));
 
+// ---------------------------------------------------------------------------
+// Scalar objectives: a number per file, summed per sector.
+
+const measureSourcesOf = (measure: CompiledMeasure): ReadonlyArray<CompiledMeasureSource> =>
+  measure.kind === "sum" ? [measure.of] : measure.kind === "ratio" ? [measure.of, measure.per] : [];
+
+// The detectors a scalar objective reads a file through: its report and
+// function sources, so the loader holds its functions, the host reads its
+// reports ahead and parses the file when either needs the tree.
+export const measureDetectorsOf = (
+  objective: CompiledObjective,
+): ReadonlyArray<CompiledDetector> =>
+  objective.measure === null
+    ? []
+    : measureSourcesOf(objective.measure).flatMap((source) =>
+        source.kind === "report" || source.kind === "fn" ? [source.detect] : [],
+      );
+
+// The scalar objectives a host measures file by file: all but a command's,
+// which measures the repository once.
+export const perFileMeasuresOf = (rule: CompiledCampaign): ReadonlyArray<CompiledObjective> =>
+  rule.objectives.filter(
+    (objective) => objective.measure !== null && objective.measure.kind !== "command",
+  );
+
+// Six decimals: enough for a density, and few enough that a ratio reads the
+// same on every run and the ledger's arithmetic compares exactly.
+export const roundMeasure = (value: number): number => Math.round(value * 1e6) / 1e6;
+
+const NON_BLANK = /\S/;
+
+const measureSource = (source: CompiledMeasureSource, input: CampaignInput): number => {
+  switch (source.kind) {
+    case "lines": {
+      let lines = 0;
+      for (const line of input.text.split("\n")) if (NON_BLANK.test(line)) lines += 1;
+      return lines;
+    }
+    case "files":
+      return 1;
+    case "report":
+      return candidatesOf(source.detect, "match", input).length;
+    case "fn": {
+      // The loader holds whatever the manifest named; a measure reads its
+      // answer as a number, and anything else — a boolean, a list, a
+      // negative or non-finite number — is `NaN`, which `check` refuses.
+      const found = input.functions.get(source.detect.name) as
+        ((...args: Parameters<CampaignMeasure>) => unknown) | undefined;
+      if (found === undefined) return Number.NaN;
+      const answer = found({
+        file: input.file,
+        text: input.text,
+        facts: input.facts,
+        syntax: input.syntax,
+      });
+      return typeof answer === "number" && Number.isFinite(answer) && answer >= 0
+        ? answer
+        : Number.NaN;
+    }
+  }
+};
+
+// What one file contributes: to the sum, or to a ratio's two sums.
+export type MeasureParts = { readonly of: number; readonly per: number };
+
+export const ZERO_PARTS: MeasureParts = { of: 0, per: 0 };
+
+export const measureFile = (measure: CompiledMeasure, input: CampaignInput): MeasureParts =>
+  measure.kind === "ratio"
+    ? { of: measureSource(measure.of, input), per: measureSource(measure.per, input) }
+    : measure.kind === "sum"
+      ? { of: measureSource(measure.of, input), per: 0 }
+      : ZERO_PARTS;
+
+export const addParts = (left: MeasureParts, right: MeasureParts): MeasureParts => ({
+  of: left.of + right.of,
+  per: left.per + right.per,
+});
+
+// A sector's value from its files' parts: the sum, or `scale × Σof / Σper`
+// (0 where the denominator is).
+export const valueOfParts = (measure: CompiledMeasure, parts: MeasureParts): number => {
+  if (measure.kind !== "ratio") return roundMeasure(parts.of);
+  if (parts.per === 0) return Number.isNaN(parts.of) ? Number.NaN : 0;
+  return roundMeasure((measure.scale * parts.of) / parts.per);
+};
+
+// A command's output as a number: the whole of it, trimmed, or the `value`
+// group of the first match of the pattern. `NaN` when neither reads as one.
+export const numberFromOutput = (measure: CompiledMeasure, output: string): number => {
+  if (measure.kind !== "command") return Number.NaN;
+  const text =
+    measure.pattern === null ? output.trim() : measure.pattern.exec(output)?.groups?.value;
+  if (text === undefined || text.trim() === "") return Number.NaN;
+  const value = Number(text.trim());
+  return Number.isFinite(value) ? roundMeasure(value) : Number.NaN;
+};
+
+// How far a scalar is from being met: the distance to its target in the
+// direction it improves, 0 once there — and 0 for a standing measure, which
+// has no target and is never residue. This is the scalar's dimension of the
+// residue vector, so a phase is left when it reaches 0 as when a holdout
+// count does.
+export const distanceToTarget = (objective: CompiledObjective, value: number): number => {
+  if (objective.target === null) return 0;
+  // A number that did not measure holds the sector where it is — `check`
+  // refuses it — rather than letting it pass a phase it has not met.
+  if (Number.isNaN(value)) return 1;
+  const distance =
+    objective.direction === "down" ? value - objective.target : objective.target - value;
+  return Math.max(0, roundMeasure(distance));
+};
+
 // One line per leaf term: how it reads, and what it answered for this file —
 // every leaf evaluated, with no short-circuit, since the point is to show
 // which one is not saying what the author thinks it says.
@@ -1239,6 +1442,8 @@ export type FailedProbe = {
   readonly admittedBy?: string;
   // For a probe outside the campaign's own scope.
   readonly outOfScope?: boolean;
+  // For a scalar objective's probe: what the file measured.
+  readonly measured?: number;
 };
 
 // Every objective must fire on each of its `fires` probes and stay silent
@@ -1283,6 +1488,30 @@ export const campaignsFailingTheirProbe = (
       return input;
     };
     for (const objective of rule.objectives) {
+      const measure = objective.measure;
+      if (measure !== null) {
+        // A scalar's probe is proven on the number the file contributes:
+        // the probe's `value` when it states one, above zero when it does
+        // not, and zero for an `ignores` probe.
+        const prove = (probe: CampaignProbe, expected: "fires" | "ignores"): void => {
+          if (!anyMatches(rule.scope, probe.path)) {
+            failed.push({ name: objective.name, probe, expected, outOfScope: true });
+            return;
+          }
+          const input = probeInputOf(probe, extractor, matcherFor(probe.path), functions);
+          const measured = valueOfParts(measure, measureFile(measure, input));
+          const holds =
+            expected === "ignores"
+              ? measured === 0
+              : probe.value === undefined
+                ? measured > 0
+                : measured === roundMeasure(probe.value);
+          if (!holds) failed.push({ name: objective.name, probe, expected, measured });
+        };
+        for (const probe of objective.probes.fires) prove(probe, "fires");
+        for (const probe of objective.probes.ignores) prove(probe, "ignores");
+        continue;
+      }
       const detect = detectorOf(objective);
       if (detect === null) continue;
       const unit = objective.sector?.kind === "has" ? "file" : objective.unit;

package/src/core/ledger.ts

@@ -1,8 +1,9 @@
+import { type Standing, standingOf } from "@goodbones/core";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 
-import type { CampaignUnit } from "../domain/config.js";
-import type { CompiledCampaign } from "./campaigns.js";
+import type { CampaignUnit, MeasureDirection } from "../domain/config.js";
+import { type CompiledCampaign, roundMeasure } from "./campaigns.js";
 import { isDefinedPhase, type SectorPosition } from "./phases.js";
 import { IMPLICIT_SECTOR } from "./sectors.js";
 
@@ -447,6 +448,267 @@ export const isStalled = (
   return now - Date.parse(last) > rule.staleAfter;
 };
 
+// ---------------------------------------------------------------------------
+// A scalar objective's ledger: a number per sector, the best value `clear`
+// has recorded for it, and every rise conceded. The same file, a second
+// schema — told apart by `kind`, which the holdout ledger does not carry, so
+// every ledger written before scalars existed decodes as it did.
+//
+//   - `check` holds each sector in window to `recorded`, within the
+//     objective's tolerance: a value worse by more is unrecorded growth,
+//     and a value better by more is progress `clear` has not written yet —
+//     stale, as a holdout that stopped firing is.
+//   - `clear` writes an improvement: `recorded` moves to the value and the
+//     difference joins `improved`. `concede` writes a rise, with a reason.
+//   - The arithmetic, per sector, in the direction that is worse:
+//     `recorded = initial + Σ rise − improved`.
+//   - A sector leaving the window is `closed` at the value it left with;
+//     nothing after that counts.
+
+const MeasureSectorLedger = Schema.Struct({
+  entered: Schema.String,
+  // The value the day the sector entered the window.
+  initial: Schema.Finite,
+  // The value the sector is held to.
+  recorded: Schema.Finite,
+  // Every improvement `clear` recorded, summed, as a magnitude.
+  improved: Schema.Finite,
+  // The value the sector left the window with, or `null` while inside it.
+  closed: Schema.NullOr(Schema.Finite),
+  // When `recorded` last improved — what the stall clock reads.
+  lastImproved: Schema.String,
+});
+
+// A rise conceded with a reason, or a re-baseline a phase concession
+// authorized: the recorded value before and after.
+const MeasureConcession = Schema.Struct({
+  sector: Schema.String,
+  at: Schema.String,
+  by: Schema.String,
+  from: Schema.Finite,
+  to: Schema.Finite,
+  reason: Schema.String,
+});
+
+export const MeasureLedger = Schema.Struct({
+  version: Schema.Literal(2),
+  kind: Schema.Literal("measure"),
+  campaign: Schema.String,
+  objective: Schema.String,
+  created: Schema.String,
+  direction: Schema.Literals(["down", "up"]),
+  sectors: Schema.Record(Schema.String, MeasureSectorLedger),
+  concessions: Schema.Array(MeasureConcession),
+});
+
+export type MeasureLedger = typeof MeasureLedger.Type;
+export type MeasureSectorLedger = typeof MeasureSectorLedger.Type;
+export type MeasureConcession = typeof MeasureConcession.Type;
+
+const decodeMeasure = Schema.decodeUnknownResult(MeasureLedger, {
+  errors: "all",
+  onExcessProperty: "error",
+});
+
+export const isMeasureLedger = (raw: unknown): boolean =>
+  typeof raw === "object" &&
+  raw !== null &&
+  (raw as { readonly kind?: unknown }).kind === "measure";
+
+export const decodeMeasureLedger = (raw: unknown): Result.Result<MeasureLedger, string> => {
+  const decoded = decodeMeasure(raw);
+  return Result.isFailure(decoded)
+    ? Result.fail(String(decoded.failure.issue))
+    : Result.succeed(decoded.success);
+};
+
+export const EMPTY_MEASURE_LEDGER = (
+  campaign: string,
+  objective: string,
+  direction: MeasureDirection,
+  now: number,
+): MeasureLedger => ({
+  version: 2,
+  kind: "measure",
+  campaign,
+  objective,
+  created: new Date(now).toISOString(),
+  direction,
+  sectors: {},
+  concessions: [],
+});
+
+export const serializeMeasureLedger = (ledger: MeasureLedger): string =>
+  `${JSON.stringify(ledger, null, 2)}\n`;
+
+// How much worse `to` is than `from`, in the ledger's direction.
+const worseBy = (direction: MeasureDirection, from: number, to: number): number =>
+  direction === "down" ? to - from : from - to;
+
+// Sums of rounded numbers carry float error; the arithmetic is exact to
+// well under the six decimals a value is measured to.
+const EPSILON = 1e-6;
+
+export const measureArithmeticHolds = (ledger: MeasureLedger, sector: string): boolean => {
+  const risen = ledger.concessions
+    .filter((one) => one.sector === sector)
+    .reduce((sum, one) => sum + worseBy(ledger.direction, one.from, one.to), 0);
+  const own = ledger.sectors[sector];
+  if (own === undefined) return Math.abs(risen) < EPSILON;
+  const expected = worseBy(ledger.direction, own.initial, own.recorded);
+  return Math.abs(expected - (risen - own.improved)) < EPSILON;
+};
+
+export const measureLedgerArithmeticHolds = (ledger: MeasureLedger): boolean =>
+  [
+    ...new Set([...Object.keys(ledger.sectors), ...ledger.concessions.map((one) => one.sector)]),
+  ].every((sector) => measureArithmeticHolds(ledger, sector));
+
+// Where a sector's value stands against what its ledger holds it to.
+export const measureStandingOf = (
+  ledger: MeasureLedger,
+  sector: string,
+  value: number,
+  tolerance: number,
+): Standing | "unrecorded" => {
+  const own = ledger.sectors[sector];
+  if (own === undefined || own.closed !== null) return "unrecorded";
+  return standingOf({ direction: ledger.direction, limit: own.recorded, tolerance }, value);
+};
+
+// `clear` for one sector, in one of three positions: entering the window
+// (recorded at its value), inside it (an improvement past the tolerance
+// becomes the record), or past it (closed at the value it left with).
+export const clearedMeasure = (
+  ledger: MeasureLedger,
+  sector: string,
+  value: number,
+  tolerance: number,
+  now: number,
+  window: "inside" | "outside",
+  by = "objectives clear",
+): MeasureLedger => {
+  const at = new Date(now).toISOString();
+  const own = ledger.sectors[sector];
+  if (window === "outside") {
+    if (own === undefined || own.closed !== null) return ledger;
+    return {
+      ...ledger,
+      sectors: {
+        ...ledger.sectors,
+        [sector]: { ...own, closed: Number.isNaN(value) ? own.recorded : value },
+      },
+    };
+  }
+  if (Number.isNaN(value)) return ledger;
+  if (own === undefined) {
+    return {
+      ...ledger,
+      sectors: {
+        ...ledger.sectors,
+        [sector]: {
+          entered: at,
+          initial: value,
+          recorded: value,
+          improved: 0,
+          closed: null,
+          lastImproved: at,
+        },
+      },
+    };
+  }
+  if (own.closed !== null) {
+    // A sector born again after it was closed — its marker restored, say —
+    // enters again at its value, and the move from its old record is a
+    // concession, so the arithmetic still holds and the jump is in the file.
+    return {
+      ...ledger,
+      sectors: { ...ledger.sectors, [sector]: { ...own, recorded: value, closed: null } },
+      concessions:
+        own.recorded === value
+          ? ledger.concessions
+          : [
+              ...ledger.concessions,
+              { sector, at, by, from: own.recorded, to: value, reason: "entered the window again" },
+            ],
+    };
+  }
+  if (
+    standingOf({ direction: ledger.direction, limit: own.recorded, tolerance }, value) !==
+    "surpassed"
+  ) {
+    return ledger;
+  }
+  return {
+    ...ledger,
+    sectors: {
+      ...ledger.sectors,
+      [sector]: {
+        ...own,
+        recorded: value,
+        improved: roundMeasure(own.improved - worseBy(ledger.direction, own.recorded, value)),
+        lastImproved: at,
+      },
+    },
+  };
+};
+
+// `concede`, or a re-baseline: the sector is held to its value from now,
+// and a concession records the move with its reason. A sector the ledger
+// has not recorded is `clear`'s to enter, not a concession's.
+export const concededMeasure = (
+  ledger: MeasureLedger,
+  sector: string,
+  value: number,
+  record: ConcessionRecord,
+): MeasureLedger => {
+  const own = ledger.sectors[sector];
+  if (own === undefined || own.closed !== null || Number.isNaN(value)) return ledger;
+  if (own.recorded === value) return ledger;
+  return {
+    ...ledger,
+    sectors: { ...ledger.sectors, [sector]: { ...own, recorded: value } },
+    concessions: [
+      ...ledger.concessions,
+      {
+        sector,
+        at: new Date(record.at).toISOString(),
+        by: record.by,
+        from: own.recorded,
+        to: value,
+        reason: record.reason,
+      },
+    ],
+  };
+};
+
+// What the ledger holds the open sectors to, summed.
+export const recordedOf = (ledger: MeasureLedger): number =>
+  roundMeasure(
+    Object.values(ledger.sectors)
+      .filter((one) => one.closed === null)
+      .reduce((sum, one) => sum + one.recorded, 0),
+  );
+
+export const lastImprovedOf = (ledger: MeasureLedger): string | null => {
+  const stamps = Object.values(ledger.sectors).map((one) => one.lastImproved);
+  return stamps.length === 0 ? null : stamps.reduce((a, b) => (a > b ? a : b));
+};
+
+// How far the open sectors have come from where they entered toward the
+// target: `1` at it, `0` where they started. A standing measure has no
+// target to come toward, and reads as its improvement over its initial.
+export const measureProgressOf = (ledger: MeasureLedger, target: number | null): number => {
+  const open = Object.values(ledger.sectors).filter((one) => one.closed === null);
+  if (open.length === 0) return 1;
+  const initial = open.reduce((sum, one) => sum + one.initial, 0);
+  const recorded = open.reduce((sum, one) => sum + one.recorded, 0);
+  const goal = target === null ? 0 : target * open.length;
+  const span = worseBy(ledger.direction, goal, initial);
+  if (span <= 0) return 1;
+  return Math.min(1, Math.max(0, 1 - worseBy(ledger.direction, goal, recorded) / span));
+};
+
 // ---------------------------------------------------------------------------
 // The per-sector record: what derivation cannot say about a sector — the
 // furthest phase it has reached, the phases attested for it, and the notes

package/src/domain/config.ts

@@ -182,6 +182,9 @@ export const CampaignProbe = Schema.Struct({
   edges: Schema.optionalKey(Schema.Record(Schema.String, ImportProbeTarget)),
   files: Schema.optionalKey(Schema.Array(Schema.String)),
   report: Schema.optionalKey(Schema.Array(ProbeDiagnostic)),
+  // A scalar objective's probe only: the number the file contributes. A
+  // `fires` probe without one asserts only that it is above zero.
+  value: Schema.optionalKey(Schema.Finite),
 });
 
 export const CampaignProbes = Schema.Struct({
@@ -189,12 +192,43 @@ export const CampaignProbes = Schema.Struct({
   ignores: Schema.Array(CampaignProbe),
 });
 
+// Where a scalar objective's number comes from, per file: its non-blank
+// lines, the file itself (so a sector's value is its file count), the
+// diagnostics a report puts on it, or what a `module#export` function
+// answers for it. A sector's value is the sum over its files.
+export const MeasureSource = Schema.Union([
+  Schema.Struct({ lines: Schema.Literal(true) }),
+  Schema.Struct({ files: Schema.Literal(true) }),
+  Schema.Struct({ report: ReportTerm }),
+  Schema.Struct({ fn: Schema.String }),
+]);
+export type MeasureSource = (typeof MeasureSource)["Type"];
+
+// A scalar objective's number: one source summed, a ratio of two sums
+// (`scale × Σof / Σper`, 0 where `per` sums to 0), or — for a campaign with
+// no perimeter, whose scope is its one sector — a command whose output is
+// the number, read whole or through a `pattern` with a `value` group.
+export const Measure = Schema.Union([
+  MeasureSource,
+  Schema.Struct({
+    ratio: Schema.Struct({ of: MeasureSource, per: MeasureSource, scale: Schema.Finite }),
+  }),
+  Schema.Struct({ command: Schema.String, pattern: Schema.optionalKey(Schema.String) }),
+]);
+export type Measure = (typeof Measure)["Type"];
+
+// Which way a scalar objective's number is better.
+export const MeasureDirection = Schema.Literals(["down", "up"]);
+export type MeasureDirection = (typeof MeasureDirection)["Type"];
+
 // An objective: a detector, a granularity, probes, and a ledger that only
 // shrinks on its own. Owned by one campaign; named by at most one phase (an
 // objective no phase names is in window in every phase). Exactly one of
-// `match` (a per-file detector, evaluated by both hosts) and `sector` (a
-// term over the sector's files, evaluated by the CLI) — or, for the
-// objectives an `endState` expands into, `endState` naming the family.
+// `match` (a per-file detector, evaluated by both hosts), `sector` (a term
+// over the sector's files, evaluated by the CLI) and `measure` (a number
+// per sector, evaluated by the CLI and read off its ledger by the plugin) —
+// or, for the objectives an `endState` expands into, `endState` naming the
+// family.
 export const ObjectiveRule = Schema.Struct({
   // `campaign/<campaign>/<objective>`, the rule name a violation carries.
   name: Schema.String,
@@ -203,9 +237,17 @@ export const ObjectiveRule = Schema.Struct({
   // The `how`: what a reader at a holdout does about it.
   message: Schema.String,
   why: Schema.optionalKey(Schema.String),
-  holdout: Holdout,
+  // Absent for a scalar objective, which holds nothing out.
+  holdout: Schema.optionalKey(Holdout),
   match: Schema.optionalKey(Detector),
   sector: Schema.optionalKey(SectorTerm),
+  // A scalar objective: a number per sector with a direction, held to the
+  // value its ledger last recorded within `tolerance`, and met — for the
+  // phase that names it — at `target`.
+  measure: Schema.optionalKey(Measure),
+  direction: Schema.optionalKey(MeasureDirection),
+  tolerance: Schema.optionalKey(Schema.Finite),
+  target: Schema.optionalKey(Schema.Finite),
   endState: Schema.optionalKey(
     Schema.Struct({
       phase: Schema.String,