IF Commons GitHub

pure/objectives

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-quality-evidence FR-037

Quality objectives (commons 0001-quality-evidence FR-037 to FR-039): a success criterion of a specification (SC-nnn) read as an objective with a metric named as OpenTelemetry names one (0006-signals FR-013), a target, a unit, an error budget and the window it is spent in; its measure is computed from the evidence and never typed in; WHEN the budget is spent within the window the system opens a nonconformance, and WHILE budget remains the remainder is shown with the objective. The quality system's own objectives (0001-quality-evidence FR-039) are the suggested set here.

  • A measure is one of a few computations over the evidence (the share of requirements at a grade, the review debt, the count of not_run cases, the age of the oldest open nonconformance, the number of stale proofs, the number of figures shown with no grade).
  • An error budget is the share of the window's samples that may miss the target (0 to 1): the objective is spent when more of the window's samples missed than the budget allows, at-risk when some missed within the budget, and met when none did.
  • The objectives are emitted as OpenTelemetry metrics (FR-011): gauges through kernel/otel.ts and otlp.ts.
import { evaluate, SUGGESTED_OBJECTIVES } from "./objectives.ts";
// evaluate(SUGGESTED_OBJECTIVES[0], [{ day: "2026-11-16", value: 0.9 }], "2026-11-17").state === "met"

Source: commons/quality/src/pure/objectives.ts

8 of 19 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Measuretypeno test imports it
type Measure =
  | { readonly kind: "share-at-grade"; readonly grade: Grade }
  | { readonly kind: "review-debt" }
  | { readonly kind: "not-run" }
  | { readonly kind: "oldest-open-nonconformance" }
  | { readonly kind: "stale-proofs" }
  | { readonly kind: "ungraded-figures" };

What an objective measures: each is computed from the evidence (FR-037).

Comparatortypeno test imports it
type Comparator = "at-least" | "at-most";

Whether a measure should be at least, or at most, its target.

Objectivetype
type Objective = { /** Its identifier, stable. */ readonly id: string; /** The OpenTelemetry metric that carries i… (732 characters)
type Objective = {
  /** Its identifier, stable. */
  readonly id: string;
  /** The OpenTelemetry metric that carries it (lower case, dotted, as 0006-signals FR-013 names metrics). */
  readonly metric: string;
  readonly title: string;
  readonly measure: Measure;
  readonly comparator: Comparator;
  readonly target: number;
  /** The unit of the metric, in UCUM as OpenTelemetry takes it. */
  readonly unit: string;
  /** The share of the window's samples allowed to miss the target, from 0 to 1. */
  readonly budget: number;
  /** The window, in days, the budget is spent in. */
  readonly windowDays: number;
  /** The success criterion it reads, `NNNN-slug SC-nnn`, where it reads one. */
  readonly criterion?: string;
};

A quality objective (ifqs:QualityObjective).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

MeasureFactstypeno test imports it
type MeasureFacts = {
  readonly summary: Summary;
  /** Cases that did not run in the newest run of each requirement. */
  readonly notRun: number;
  readonly oldestOpenDays: number;
  /** Requirements the index lists with no grade (none, by construction: the check that holds it). */
  readonly ungraded: number;
};

What a measure is computed from.

measureOffunctionno test imports it
function measureOf(m: Measure, f: MeasureFacts): number

A measure's value from the facts (FR-037).

isMetricNamefunction
function isMetricName(name: string): boolean

The metric names of OpenTelemetry's convention: lower case words and digits with _, in dotted namespaces of at least two names.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

objectiveProblemfunction
function objectiveProblem(o: Objective): string | undefined

What is wrong with an objective, or nothing (FR-037: a metric named as OpenTelemetry names it, a target, a unit, a budget and a window).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

SUGGESTED_OBJECTIVESconst
const SUGGESTED_OBJECTIVES: readonly Objective[]

The quality system's own objectives, suggested to a harness (0001-quality-evidence FR-039): the share at E3 or above, the review debt, not_run, the age of the oldest open nonconformance and the stale proofs.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Sampletypeno test imports it
type Sample = { readonly day: string; readonly value: number };

A measure on a day.

ObjectiveStatetypeno test imports it
type ObjectiveState = "met" | "at-risk" | "spent";

How an objective stands: met (no sample of its window missed), at-risk (some missed, within the budget) or spent (more missed than the budget allows).

Evaluationtypeno test imports it
type Evaluation = { readonly objective: Objective; /** The newest measure. */ readonly value: number; readonly s… (430 characters)
type Evaluation = {
  readonly objective: Objective;
  /** The newest measure. */
  readonly value: number;
  readonly state: ObjectiveState;
  /** Samples in the window, and how many of them missed the target. */
  readonly samples: number;
  readonly missed: number;
  /** The budget that remains, as a share of the window's samples (negative where it is overspent); shown with the objective. */
  readonly remaining: number;
};

An objective evaluated (FR-037, FR-038).

evaluatefunction
function evaluate(o: Objective, samples: readonly Sample[], today: string): Evaluation

An objective evaluated against its samples at today: those of the window ending that day, the newest being the value (FR-037, FR-038).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

showEvaluationfunction
function showEvaluation(e: Evaluation): string

The objective an evaluation shows: its value against its target and the budget that remains (FR-038).

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

objectiveSubjectfunctionno test imports it
function objectiveSubject(o: Objective): string

The requirement the nonconformance of a spent budget names.

Criteriontypeno test imports it
type Criterion = { readonly spec: string; readonly id: string; readonly text: string; readonly objective?: Objective };

A success criterion of a specification, and the objective that reads it where one is declared.

criteriaOffunctionno test imports it
function criteriaOf(spec: string, text: string): readonly { readonly spec: string; readonly id: string; readonly text: string; }[]

The success criteria of a specification's text (- **SC-001**: ...), in order.

criteriaWithObjectivesfunction
function criteriaWithObjectives(specs: readonly { readonly slug: string; readonly text: string; }[], declared: readonly Objective[]): readonly Criterion[]

The success criteria of the specifications read as quality objectives (FR-037): each criterion with the objective declared for it (an objective whose criterion is NNNN-slug SC-nnn); a criterion with none is listed with no objective, so that it is seen.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

objectiveMetricsfunctionno test imports it
function objectiveMetrics(evals: readonly Evaluation[], resource: Resource, time: bigint): readonly MetricBatch[]

The metric batches of evaluations (FR-011): each objective's value as a gauge named by its metric, and its target and remaining budget, at time.

objectiveMetricsJsonfunction
function objectiveMetricsJson(evals: readonly Evaluation[], resource: Resource, time: bigint): Result<string, string>

The metrics as an OTLP/JSON ExportMetricsServiceRequest (FR-011), or why an objective cannot be emitted.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.