@variance-authority/core 0.1.0

package/dist/judge/sensitivity.d.ts

@@ -0,0 +1,202 @@
+import { type Band } from '../compare/band.js';
+import type { SemanticDiff } from '../compare/diff/index.js';
+import { type IgnoreOptions, type IgnoreRule } from './ignore.js';
+/**
+ * How much of a subject is being asserted on, declared where it applies.
+ *
+ * A route-level test and a component-level test want opposite things from the
+ * same machinery. A component's test asserts on everything: a colour token moved
+ * and that is the change. A route's test asserts that the *page still assembles*
+ * — the nav is where it was, the sidebar did not collapse, nothing overlaps — and
+ * a design-system token landing in forty routes is noise it should never have
+ * been shown. Run one policy over both and one of them is unusable: either the
+ * routes are permanently red, or the components stop reporting the thing they
+ * exist to catch.
+ *
+ * The usual answer is a second product, or a threshold, and both are worse than
+ * the problem. What this offers instead is the same shape an
+ * {@link IgnoreRule} has, because it is the same act: **naming what is not being
+ * asserted on, where, by whom, and with the count in the report.**
+ *
+ * ## The unit is a band, and that is the whole design
+ *
+ * The frequency bands already say what *kind* of thing moved — `a11y`,
+ * `geometry`, `token`, `content`, `texture` — and they are ordered by how rarely
+ * they move and how much it matters when they do. "Assert on layout and ignore
+ * small token updates" is not a tolerance, a percentage or a pixel count. It is
+ * two band names.
+ *
+ * That is why this is not a threshold: a threshold absorbs *anything* small
+ * enough, and a band absorbs exactly one kind of thing however large it is. A
+ * route declared `layout` still reports a nav that moved by one pixel, and never
+ * reports a rebrand that repainted every surface on the page.
+ *
+ * ## Why it is a declaration and not a mode
+ *
+ * The same reason an ignore is. A run-wide switch is a decision nobody attributes
+ * and nobody revisits; a rule with an id, a required reason and a place is one a
+ * reviewer can read six months later and disagree with. Everything an ignore owes
+ * it owes: a reason, a scope, and a count of what it absorbed — including the
+ * count of zero, which is how a declaration that has stopped being true is found.
+ */
+/**
+ * A named set of bands worth asserting on.
+ *
+ * A closed set. Three names cover the cases that have argued for themselves and
+ * a fourth would need one; an open set of user-defined levels would put the
+ * vocabulary in a config file, where the report cannot explain what a word meant
+ * to whoever wrote it.
+ */
+export type Level = 
+/**
+ * Everything. What a component's own test wants, and the default everywhere.
+ *
+ * Named rather than left implicit so a subject can be declared strict *back*
+ * inside a route that is not — the exception a broad declaration always grows.
+ */
+'strict'
+/**
+ * The page still assembles: `a11y` and `geometry`.
+ *
+ * `geometry` is the obvious half — boxes appeared, vanished, moved or resized.
+ * `a11y` is the half that gets left out and should not be: a control that lost
+ * its accessible name is a structural regression that happens to repaint
+ * nothing, and a route test that ignored it would be asserting on the shape of
+ * the page while blind to the shape a screen reader sees.
+ *
+ * What it absorbs is `token`, `content` and `texture` — a restyle, a copy edit,
+ * anti-aliasing. Each is a real change, each is reported as absorbed, and none
+ * of them is what a route-level test is for.
+ */
+ | 'layout'
+/**
+ * What the page *says*: `a11y` and `content`.
+ *
+ * For a subject whose styling is somebody else's to change — a themed embed, a
+ * page inside a design system being actively rebranded — where the assertion
+ * worth keeping is that the words and the semantics survived.
+ */
+ | 'content';
+/** The bands a level asserts on. Everything else is absorbed and counted. */
+export declare function bandsOf(level: Level): readonly Band[];
+export interface SensitivityRule {
+    /** Stable name. Appears in the report and in every count this rule produces. */
+    readonly id: string;
+    /**
+     * Why this subject is not asserted on in full. Required, as an ignore's is.
+     *
+     * The difference between a policy somebody chose and one that accreted. A
+     * route declared `layout` two years ago by somebody who has left is a blind
+     * spot with a plausible-looking config entry in front of it.
+     */
+    readonly reason: string;
+    readonly level: Level;
+    /** Subjects this applies to. `*` matches any run of characters. */
+    readonly subjects?: readonly string[];
+    /**
+     * Tags the subject must carry, as its own artifact declared them.
+     *
+     * FIXME: read by nothing. `asIgnore` copies `subjects` and drops this, so a
+     * rule scoped only by tags translates to an unscoped ignore and absorbs across
+     * every subject in the run — the widest possible reading of the narrowest
+     * scope an operator can write.
+     */
+    readonly tags?: readonly string[];
+}
+/** What one rule absorbed, per band, across a run. */
+export interface Relaxation {
+    readonly rule: string;
+    readonly reason: string;
+    readonly level: Level;
+    /** Deltas absorbed because their band is not asserted on here. */
+    readonly absorbed: number;
+    readonly subjects: readonly string[];
+    /** Which bands were absorbed, so a level can be tightened with evidence. */
+    readonly bands: readonly Band[];
+}
+export interface SensitivityRegister {
+    readonly relaxations: readonly Relaxation[];
+    /**
+     * Rules that absorbed nothing in any subject they applied to.
+     *
+     * The same accounting an ignore's register keeps, and for the same reason: a
+     * route declared `layout` that has reported no token change in six months is
+     * either a route nothing styles, or a declaration nobody needed. Both are worth
+     * a line, and neither is visible without the count.
+     */
+    readonly dead: readonly string[];
+    readonly totalAbsorbed: number;
+}
+export interface SensitivityOutcome {
+    readonly diffs: readonly SemanticDiff[];
+    readonly register: SensitivityRegister;
+}
+/**
+ * Turn a sensitivity rule into the ignore it is.
+ *
+ * Not a shortcut — a statement about what these are. A sensitivity names a place
+ * and narrows by band, which is exactly the shape `IgnoreRule` already refuses to
+ * accept *without* a place, and exactly the shape it accepts with one. Sharing
+ * the mechanism means sharing the safety property: the deltas are absorbed by
+ * `applyIgnores`, counted per rule, and reported when a rule absorbs nothing.
+ *
+ * The bands are inverted on the way through, and that inversion is the whole
+ * translation. A sensitivity says what it *asserts on*; an ignore says what it
+ * *absorbs*. Stating the level positively is what makes a config readable — "this
+ * route asserts on layout" rather than "this route ignores token, content and
+ * texture" — and the negative form is what the machinery needs.
+ */
+export declare function asIgnore(rule: SensitivityRule): IgnoreRule | null;
+/**
+ * The register as the lines a run prints.
+ *
+ * Absorption is stated in the *positive* form the operator wrote, because that is
+ * the sentence they can check: "asserts on layout" is a claim about intent, and
+ * "absorbed 412 token deltas" is the evidence for or against it.
+ */
+export declare function summarizeSensitivity(register: SensitivityRegister): readonly string[];
+/**
+ * Apply declared sensitivities to a run's diffs.
+ *
+ * A thin fold over {@link applyIgnores}, and thin on purpose: the absorption, the
+ * per-rule counting and the dead-rule reporting are one mechanism, and a second
+ * implementation of them would be a second set of bugs in the half of the system
+ * whose whole job is not to silently hide things.
+ *
+ * Rules that resolve to `strict` are dropped before the fold rather than passed
+ * through, so a project that declares its default explicitly does not collect a
+ * permanently-dead register line for saying so.
+ */
+export declare function applySensitivity(diffs: readonly SemanticDiff[], rules: readonly SensitivityRule[], options?: IgnoreOptions): SensitivityOutcome;
+/**
+ * What a level does with a set of bands that moved.
+ *
+ * The arm for the path that holds no second document. `applySensitivity` folds
+ * over deltas, which needs both revisions normalized; a `variance run` compares
+ * an image against a stored baseline and has only what that baseline carried —
+ * per-component hashes, one digest per band (ADR-0027, ADR-0029's split).
+ * `bandsBetween` turns those into the same vocabulary, and this decides against
+ * it, so the two paths agree by sharing {@link bandsOf} rather than by
+ * inspection.
+ *
+ * **Empty in means nothing absorbed**, not everything. A run whose pixels moved
+ * while every component hash held is raster residue — `texture`, which a
+ * document cannot carry and which this must therefore never claim to have
+ * decided. Absorbing on an empty set would turn the one band a hash comparison
+ * is blind to into the one it silences.
+ */
+export declare function relaxes(level: Level, moved: readonly Band[]): {
+    readonly asserted: readonly Band[];
+    readonly absorbed: readonly Band[];
+};
+/**
+ * Whether a subject's every moved band falls outside what it is asserted on.
+ *
+ * The whole subject, because that is the unit a stored baseline can answer for:
+ * one image, one verdict. A subject where *some* moved band is asserted on is
+ * reported in full — including the bands that would have been absorbed — since
+ * a reviewer looking at a nav that moved wants the restyle that came with it,
+ * and hiding half a diff is worse than hiding none of it.
+ */
+export declare function absorbsEntirely(level: Level, moved: readonly Band[]): boolean;
+//# sourceMappingURL=sensitivity.d.ts.map

package/dist/judge/sensitivity.js

@@ -0,0 +1,152 @@
+import { BANDS } from '../compare/band.js';
+import { applyIgnores } from './ignore.js';
+const LEVELS = {
+    strict: BANDS,
+    layout: ['a11y', 'geometry'],
+    content: ['a11y', 'content'],
+};
+/** The bands a level asserts on. Everything else is absorbed and counted. */
+export function bandsOf(level) {
+    return LEVELS[level];
+}
+/**
+ * Turn a sensitivity rule into the ignore it is.
+ *
+ * Not a shortcut — a statement about what these are. A sensitivity names a place
+ * and narrows by band, which is exactly the shape `IgnoreRule` already refuses to
+ * accept *without* a place, and exactly the shape it accepts with one. Sharing
+ * the mechanism means sharing the safety property: the deltas are absorbed by
+ * `applyIgnores`, counted per rule, and reported when a rule absorbs nothing.
+ *
+ * The bands are inverted on the way through, and that inversion is the whole
+ * translation. A sensitivity says what it *asserts on*; an ignore says what it
+ * *absorbs*. Stating the level positively is what makes a config readable — "this
+ * route asserts on layout" rather than "this route ignores token, content and
+ * texture" — and the negative form is what the machinery needs.
+ */
+export function asIgnore(rule) {
+    const asserted = new Set(bandsOf(rule.level));
+    const absorbed = BANDS.filter((band) => !asserted.has(band));
+    // `strict` asserts on everything, so it absorbs nothing and produces no rule.
+    // Returning an ignore with an empty band list would produce a register entry
+    // that is permanently dead, which is a line telling an operator to delete the
+    // one declaration that is doing nothing wrong.
+    if (absorbed.length === 0)
+        return null;
+    return {
+        id: rule.id,
+        reason: rule.reason,
+        bands: absorbed,
+        // The place is the subject, said rather than left to be inferred from a
+        // missing selector — see `IgnoreRule.whole`.
+        whole: true,
+        ...(rule.subjects !== undefined ? { subjects: rule.subjects } : {}),
+    };
+}
+/**
+ * The register as the lines a run prints.
+ *
+ * Absorption is stated in the *positive* form the operator wrote, because that is
+ * the sentence they can check: "asserts on layout" is a claim about intent, and
+ * "absorbed 412 token deltas" is the evidence for or against it.
+ */
+export function summarizeSensitivity(register) {
+    if (register.relaxations.length === 0)
+        return [];
+    const lines = [
+        `SENSITIVITY — ${register.totalAbsorbed} difference(s) not asserted on, ` +
+            `by ${register.relaxations.length} rule(s)`,
+    ];
+    for (const entry of register.relaxations) {
+        if (entry.absorbed === 0) {
+            lines.push(`  [dead] ${entry.rule} — asserts on ${entry.level} across ` +
+                `${entry.subjects.length} subject(s) and absorbed nothing (${entry.reason}); ` +
+                'nothing here needed relaxing');
+            continue;
+        }
+        lines.push(`  ${entry.rule} — asserts on ${entry.level}; absorbed ${entry.absorbed} ` +
+            `${entry.bands.join('/')} difference(s) in ${entry.subjects.length} subject(s): ` +
+            entry.reason);
+    }
+    return lines;
+}
+/**
+ * Apply declared sensitivities to a run's diffs.
+ *
+ * A thin fold over {@link applyIgnores}, and thin on purpose: the absorption, the
+ * per-rule counting and the dead-rule reporting are one mechanism, and a second
+ * implementation of them would be a second set of bugs in the half of the system
+ * whose whole job is not to silently hide things.
+ *
+ * Rules that resolve to `strict` are dropped before the fold rather than passed
+ * through, so a project that declares its default explicitly does not collect a
+ * permanently-dead register line for saying so.
+ */
+export function applySensitivity(diffs, rules, options = {}) {
+    const translated = new Map();
+    const ignores = [];
+    for (const rule of rules) {
+        const ignore = asIgnore(rule);
+        if (ignore === null)
+            continue;
+        translated.set(rule.id, rule);
+        ignores.push(ignore);
+    }
+    const outcome = applyIgnores(diffs, ignores, options);
+    const relaxations = [...translated.values()].map((rule) => {
+        const absorbed = outcome.register.absorbed.find((entry) => entry.rule === rule.id);
+        return {
+            rule: rule.id,
+            reason: rule.reason,
+            level: rule.level,
+            absorbed: absorbed?.deltas ?? 0,
+            subjects: absorbed?.subjects ?? [],
+            bands: absorbed?.bands ?? [],
+        };
+    });
+    return {
+        diffs: outcome.diffs,
+        register: {
+            relaxations,
+            dead: relaxations.filter((entry) => entry.absorbed === 0).map((entry) => entry.rule),
+            totalAbsorbed: relaxations.reduce((sum, entry) => sum + entry.absorbed, 0),
+        },
+    };
+}
+/**
+ * What a level does with a set of bands that moved.
+ *
+ * The arm for the path that holds no second document. `applySensitivity` folds
+ * over deltas, which needs both revisions normalized; a `variance run` compares
+ * an image against a stored baseline and has only what that baseline carried —
+ * per-component hashes, one digest per band (ADR-0027, ADR-0029's split).
+ * `bandsBetween` turns those into the same vocabulary, and this decides against
+ * it, so the two paths agree by sharing {@link bandsOf} rather than by
+ * inspection.
+ *
+ * **Empty in means nothing absorbed**, not everything. A run whose pixels moved
+ * while every component hash held is raster residue — `texture`, which a
+ * document cannot carry and which this must therefore never claim to have
+ * decided. Absorbing on an empty set would turn the one band a hash comparison
+ * is blind to into the one it silences.
+ */
+export function relaxes(level, moved) {
+    const asserting = new Set(bandsOf(level));
+    return {
+        asserted: moved.filter((band) => asserting.has(band)),
+        absorbed: moved.filter((band) => !asserting.has(band)),
+    };
+}
+/**
+ * Whether a subject's every moved band falls outside what it is asserted on.
+ *
+ * The whole subject, because that is the unit a stored baseline can answer for:
+ * one image, one verdict. A subject where *some* moved band is asserted on is
+ * reported in full — including the bands that would have been absorbed — since
+ * a reviewer looking at a nav that moved wants the restyle that came with it,
+ * and hiding half a diff is worse than hiding none of it.
+ */
+export function absorbsEntirely(level, moved) {
+    return moved.length > 0 && relaxes(level, moved).asserted.length === 0;
+}
+//# sourceMappingURL=sensitivity.js.map

package/dist/judge/sensitivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitivity.js","sourceRoot":"","sources":["../../src/judge/sensitivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAuC,MAAM,aAAa,CAAC;AAgFhF,MAAM,MAAM,GAA6C;IACvD,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;CAC7B,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,KAAY;IAClC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAkED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAqB;IAC5C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7D,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,+CAA+C;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,QAAQ;QACf,wEAAwE;QACxE,6CAA6C;QAC7C,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA6B;IAChE,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjD,MAAM,KAAK,GAAG;QACZ,iBAAiB,QAAQ,CAAC,aAAa,kCAAkC;YACvE,MAAM,QAAQ,CAAC,WAAW,CAAC,MAAM,UAAU;KAC9C,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CACR,YAAY,KAAK,CAAC,IAAI,iBAAiB,KAAK,CAAC,KAAK,UAAU;gBAC1D,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,qCAAqC,KAAK,CAAC,MAAM,KAAK;gBAC9E,8BAA8B,CACjC,CAAC;YACF,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,IAAI,iBAAiB,KAAK,CAAC,KAAK,cAAc,KAAK,CAAC,QAAQ,GAAG;YACxE,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,qBAAqB,KAAK,CAAC,QAAQ,CAAC,MAAM,eAAe;YACjF,KAAK,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA8B,EAC9B,KAAiC,EACjC,OAAO,GAAkB,EAAE;IAE3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IACtD,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC9B,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEtD,MAAM,WAAW,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QACnF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;YAC/B,QAAQ,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE;YAClC,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE;SAC7B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,QAAQ,EAAE;YACR,WAAW;YACX,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;YACpF,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;SAC3E;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,OAAO,CACrB,KAAY,EACZ,KAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAE1C,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrD,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,KAAsB;IAClE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;AACzE,CAAC","sourcesContent":["import { BANDS, type Band } from '../compare/band.js';\nimport type { SemanticDiff } from '../compare/diff/index.js';\nimport { applyIgnores, type IgnoreOptions, type IgnoreRule } from './ignore.js';\n\n/**\n * How much of a subject is being asserted on, declared where it applies.\n *\n * A route-level test and a component-level test want opposite things from the\n * same machinery. A component's test asserts on everything: a colour token moved\n * and that is the change. A route's test asserts that the *page still assembles*\n * — the nav is where it was, the sidebar did not collapse, nothing overlaps — and\n * a design-system token landing in forty routes is noise it should never have\n * been shown. Run one policy over both and one of them is unusable: either the\n * routes are permanently red, or the components stop reporting the thing they\n * exist to catch.\n *\n * The usual answer is a second product, or a threshold, and both are worse than\n * the problem. What this offers instead is the same shape an\n * {@link IgnoreRule} has, because it is the same act: **naming what is not being\n * asserted on, where, by whom, and with the count in the report.**\n *\n * ## The unit is a band, and that is the whole design\n *\n * The frequency bands already say what *kind* of thing moved — `a11y`,\n * `geometry`, `token`, `content`, `texture` — and they are ordered by how rarely\n * they move and how much it matters when they do. \"Assert on layout and ignore\n * small token updates\" is not a tolerance, a percentage or a pixel count. It is\n * two band names.\n *\n * That is why this is not a threshold: a threshold absorbs *anything* small\n * enough, and a band absorbs exactly one kind of thing however large it is. A\n * route declared `layout` still reports a nav that moved by one pixel, and never\n * reports a rebrand that repainted every surface on the page.\n *\n * ## Why it is a declaration and not a mode\n *\n * The same reason an ignore is. A run-wide switch is a decision nobody attributes\n * and nobody revisits; a rule with an id, a required reason and a place is one a\n * reviewer can read six months later and disagree with. Everything an ignore owes\n * it owes: a reason, a scope, and a count of what it absorbed — including the\n * count of zero, which is how a declaration that has stopped being true is found.\n */\n\n/**\n * A named set of bands worth asserting on.\n *\n * A closed set. Three names cover the cases that have argued for themselves and\n * a fourth would need one; an open set of user-defined levels would put the\n * vocabulary in a config file, where the report cannot explain what a word meant\n * to whoever wrote it.\n */\nexport type Level =\n  /**\n   * Everything. What a component's own test wants, and the default everywhere.\n   *\n   * Named rather than left implicit so a subject can be declared strict *back*\n   * inside a route that is not — the exception a broad declaration always grows.\n   */\n  | 'strict'\n  /**\n   * The page still assembles: `a11y` and `geometry`.\n   *\n   * `geometry` is the obvious half — boxes appeared, vanished, moved or resized.\n   * `a11y` is the half that gets left out and should not be: a control that lost\n   * its accessible name is a structural regression that happens to repaint\n   * nothing, and a route test that ignored it would be asserting on the shape of\n   * the page while blind to the shape a screen reader sees.\n   *\n   * What it absorbs is `token`, `content` and `texture` — a restyle, a copy edit,\n   * anti-aliasing. Each is a real change, each is reported as absorbed, and none\n   * of them is what a route-level test is for.\n   */\n  | 'layout'\n  /**\n   * What the page *says*: `a11y` and `content`.\n   *\n   * For a subject whose styling is somebody else's to change — a themed embed, a\n   * page inside a design system being actively rebranded — where the assertion\n   * worth keeping is that the words and the semantics survived.\n   */\n  | 'content';\n\nconst LEVELS: Readonly<Record<Level, readonly Band[]>> = {\n  strict: BANDS,\n  layout: ['a11y', 'geometry'],\n  content: ['a11y', 'content'],\n};\n\n/** The bands a level asserts on. Everything else is absorbed and counted. */\nexport function bandsOf(level: Level): readonly Band[] {\n  return LEVELS[level];\n}\n\nexport interface SensitivityRule {\n  /** Stable name. Appears in the report and in every count this rule produces. */\n  readonly id: string;\n\n  /**\n   * Why this subject is not asserted on in full. Required, as an ignore's is.\n   *\n   * The difference between a policy somebody chose and one that accreted. A\n   * route declared `layout` two years ago by somebody who has left is a blind\n   * spot with a plausible-looking config entry in front of it.\n   */\n  readonly reason: string;\n\n  readonly level: Level;\n\n  /** Subjects this applies to. `*` matches any run of characters. */\n  readonly subjects?: readonly string[];\n\n  /**\n   * Tags the subject must carry, as its own artifact declared them.\n   *\n   * FIXME: read by nothing. `asIgnore` copies `subjects` and drops this, so a\n   * rule scoped only by tags translates to an unscoped ignore and absorbs across\n   * every subject in the run — the widest possible reading of the narrowest\n   * scope an operator can write.\n   */\n  readonly tags?: readonly string[];\n}\n\n/** What one rule absorbed, per band, across a run. */\nexport interface Relaxation {\n  readonly rule: string;\n  readonly reason: string;\n  readonly level: Level;\n\n  /** Deltas absorbed because their band is not asserted on here. */\n  readonly absorbed: number;\n  readonly subjects: readonly string[];\n\n  /** Which bands were absorbed, so a level can be tightened with evidence. */\n  readonly bands: readonly Band[];\n}\n\nexport interface SensitivityRegister {\n  readonly relaxations: readonly Relaxation[];\n\n  /**\n   * Rules that absorbed nothing in any subject they applied to.\n   *\n   * The same accounting an ignore's register keeps, and for the same reason: a\n   * route declared `layout` that has reported no token change in six months is\n   * either a route nothing styles, or a declaration nobody needed. Both are worth\n   * a line, and neither is visible without the count.\n   */\n  readonly dead: readonly string[];\n\n  readonly totalAbsorbed: number;\n}\n\nexport interface SensitivityOutcome {\n  readonly diffs: readonly SemanticDiff[];\n  readonly register: SensitivityRegister;\n}\n\n/**\n * Turn a sensitivity rule into the ignore it is.\n *\n * Not a shortcut — a statement about what these are. A sensitivity names a place\n * and narrows by band, which is exactly the shape `IgnoreRule` already refuses to\n * accept *without* a place, and exactly the shape it accepts with one. Sharing\n * the mechanism means sharing the safety property: the deltas are absorbed by\n * `applyIgnores`, counted per rule, and reported when a rule absorbs nothing.\n *\n * The bands are inverted on the way through, and that inversion is the whole\n * translation. A sensitivity says what it *asserts on*; an ignore says what it\n * *absorbs*. Stating the level positively is what makes a config readable — \"this\n * route asserts on layout\" rather than \"this route ignores token, content and\n * texture\" — and the negative form is what the machinery needs.\n */\nexport function asIgnore(rule: SensitivityRule): IgnoreRule | null {\n  const asserted = new Set(bandsOf(rule.level));\n  const absorbed = BANDS.filter((band) => !asserted.has(band));\n\n  // `strict` asserts on everything, so it absorbs nothing and produces no rule.\n  // Returning an ignore with an empty band list would produce a register entry\n  // that is permanently dead, which is a line telling an operator to delete the\n  // one declaration that is doing nothing wrong.\n  if (absorbed.length === 0) return null;\n\n  return {\n    id: rule.id,\n    reason: rule.reason,\n    bands: absorbed,\n    // The place is the subject, said rather than left to be inferred from a\n    // missing selector — see `IgnoreRule.whole`.\n    whole: true,\n    ...(rule.subjects !== undefined ? { subjects: rule.subjects } : {}),\n  };\n}\n\n/**\n * The register as the lines a run prints.\n *\n * Absorption is stated in the *positive* form the operator wrote, because that is\n * the sentence they can check: \"asserts on layout\" is a claim about intent, and\n * \"absorbed 412 token deltas\" is the evidence for or against it.\n */\nexport function summarizeSensitivity(register: SensitivityRegister): readonly string[] {\n  if (register.relaxations.length === 0) return [];\n\n  const lines = [\n    `SENSITIVITY — ${register.totalAbsorbed} difference(s) not asserted on, ` +\n      `by ${register.relaxations.length} rule(s)`,\n  ];\n\n  for (const entry of register.relaxations) {\n    if (entry.absorbed === 0) {\n      lines.push(\n        `  [dead] ${entry.rule} — asserts on ${entry.level} across ` +\n          `${entry.subjects.length} subject(s) and absorbed nothing (${entry.reason}); ` +\n          'nothing here needed relaxing',\n      );\n      continue;\n    }\n    lines.push(\n      `  ${entry.rule} — asserts on ${entry.level}; absorbed ${entry.absorbed} ` +\n        `${entry.bands.join('/')} difference(s) in ${entry.subjects.length} subject(s): ` +\n        entry.reason,\n    );\n  }\n\n  return lines;\n}\n\n/**\n * Apply declared sensitivities to a run's diffs.\n *\n * A thin fold over {@link applyIgnores}, and thin on purpose: the absorption, the\n * per-rule counting and the dead-rule reporting are one mechanism, and a second\n * implementation of them would be a second set of bugs in the half of the system\n * whose whole job is not to silently hide things.\n *\n * Rules that resolve to `strict` are dropped before the fold rather than passed\n * through, so a project that declares its default explicitly does not collect a\n * permanently-dead register line for saying so.\n */\nexport function applySensitivity(\n  diffs: readonly SemanticDiff[],\n  rules: readonly SensitivityRule[],\n  options: IgnoreOptions = {},\n): SensitivityOutcome {\n  const translated = new Map<string, SensitivityRule>();\n  const ignores: IgnoreRule[] = [];\n\n  for (const rule of rules) {\n    const ignore = asIgnore(rule);\n    if (ignore === null) continue;\n    translated.set(rule.id, rule);\n    ignores.push(ignore);\n  }\n\n  const outcome = applyIgnores(diffs, ignores, options);\n\n  const relaxations = [...translated.values()].map((rule) => {\n    const absorbed = outcome.register.absorbed.find((entry) => entry.rule === rule.id);\n    return {\n      rule: rule.id,\n      reason: rule.reason,\n      level: rule.level,\n      absorbed: absorbed?.deltas ?? 0,\n      subjects: absorbed?.subjects ?? [],\n      bands: absorbed?.bands ?? [],\n    };\n  });\n\n  return {\n    diffs: outcome.diffs,\n    register: {\n      relaxations,\n      dead: relaxations.filter((entry) => entry.absorbed === 0).map((entry) => entry.rule),\n      totalAbsorbed: relaxations.reduce((sum, entry) => sum + entry.absorbed, 0),\n    },\n  };\n}\n\n/**\n * What a level does with a set of bands that moved.\n *\n * The arm for the path that holds no second document. `applySensitivity` folds\n * over deltas, which needs both revisions normalized; a `variance run` compares\n * an image against a stored baseline and has only what that baseline carried —\n * per-component hashes, one digest per band (ADR-0027, ADR-0029's split).\n * `bandsBetween` turns those into the same vocabulary, and this decides against\n * it, so the two paths agree by sharing {@link bandsOf} rather than by\n * inspection.\n *\n * **Empty in means nothing absorbed**, not everything. A run whose pixels moved\n * while every component hash held is raster residue — `texture`, which a\n * document cannot carry and which this must therefore never claim to have\n * decided. Absorbing on an empty set would turn the one band a hash comparison\n * is blind to into the one it silences.\n */\nexport function relaxes(\n  level: Level,\n  moved: readonly Band[],\n): { readonly asserted: readonly Band[]; readonly absorbed: readonly Band[] } {\n  const asserting = new Set(bandsOf(level));\n\n  return {\n    asserted: moved.filter((band) => asserting.has(band)),\n    absorbed: moved.filter((band) => !asserting.has(band)),\n  };\n}\n\n/**\n * Whether a subject's every moved band falls outside what it is asserted on.\n *\n * The whole subject, because that is the unit a stored baseline can answer for:\n * one image, one verdict. A subject where *some* moved band is asserted on is\n * reported in full — including the bands that would have been absorbed — since\n * a reviewer looking at a nav that moved wants the restyle that came with it,\n * and hiding half a diff is worse than hiding none of it.\n */\nexport function absorbsEntirely(level: Level, moved: readonly Band[]): boolean {\n  return moved.length > 0 && relaxes(level, moved).asserted.length === 0;\n}\n"]}

package/dist/judge/trail.d.ts

@@ -0,0 +1,122 @@
+import { type ComponentHash } from '../attribute/component-hash.js';
+import type { Digest } from '../format/hash.js';
+import type { SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * What a working session accumulates, for the loop an agent actually runs.
+ *
+ * `observePair` compares two documents and keeps nothing, which is right for a
+ * one-shot ephemeral run and wrong for the setting the mode exists to serve. An
+ * agent editing components runs: observe, edit, observe, edit. Each observation
+ * on its own can answer *what moved since the previous one*, and the questions
+ * that decide what to do next are all about the trajectory:
+ *
+ * - **What have I changed since I started?** The difference between now and the
+ *   first step, which is the diff a reviewer will eventually read — never the
+ *   sum of the per-step differences, because an edit and its revert cancel.
+ * - **Did my last edit fix what I broke two edits ago?** Components that moved
+ *   away from the starting state and have since come back to it.
+ * - **Is this the same difference I already saw?** A render hash that has been
+ *   seen before means the subject has returned to a state this session already
+ *   observed — going in circles, which is the failure mode of an agent that
+ *   cannot see its own history.
+ *
+ * ## Why this is cheap
+ *
+ * A step is a *snapshot*, not an image. Collecting one is ~7.5 ms against ~65 ms
+ * to paint (journal 0007, ADR-0010), and the interesting questions above are all
+ * answerable from component hashes and a render hash — text. A paint happens when
+ * somebody asks a question about pixels, which in an author loop is rarely and
+ * never on every step.
+ *
+ * ## Why it is here and not in a store
+ *
+ * A trail is a value and this module is a function over it. Nothing accumulates
+ * on disk, nothing is keyed by anything, and the standing constraint that images
+ * are never kept in something that accumulates is satisfied by construction:
+ * there are no images in it. The holder is whoever runs the loop — an MCP server
+ * for a session, a test for its duration — and when they stop holding it, it is
+ * gone. That is the ephemeral contract (ADR-0011), not an exception to it.
+ *
+ * ## What it cannot see
+ *
+ * Anything the semantic tier cannot. A `RenderDocument`'s `assets` map is
+ * optional and no shipped collector fills it, so an image swapped behind an
+ * unchanged URL moves no hash here and no step will mention it. That is stated
+ * rather than pending: a trail is a cheap tier, and a cheap tier's blind spots
+ * are the price of it being cheap. Ask a raster question when the answer matters.
+ */
+export interface TrailStep {
+    /**
+     * Position in the trail, from `0`. Not a time.
+     *
+     * `core` has no clock, and an ordinal is the better key anyway: an agent asks
+     * "since I started" and "since my last edit", never "since 14:03".
+     */
+    readonly at: number;
+    /** What the author said they were doing. Carried, never matched on. */
+    readonly label?: string;
+    /** Identity of the subject's state. Equal hashes are the same render. */
+    readonly renderHash: Digest;
+    readonly components: readonly ComponentHash[];
+}
+export interface Trail {
+    readonly subject: string;
+    readonly steps: readonly TrailStep[];
+}
+/** An empty trail for a subject. The first `record` gives it a starting state. */
+export declare function startTrail(subject: string): Trail;
+/**
+ * Add this observation to the trail.
+ *
+ * @throws {Error} when the snapshot is of a different subject. A trail is one
+ * subject's history, and appending another's would make every question below
+ * answer about a mixture — silently, since the shapes are identical.
+ */
+export declare function record(trail: Trail, snapshot: SemanticSnapshot, label?: string): Trail;
+export interface Progress {
+    /** Components differing from where this session started. The reviewable diff. */
+    readonly changed: readonly string[];
+    /** Components that differ from the previous step. What the last edit did. */
+    readonly sinceLast: readonly string[];
+    /**
+     * Components that had moved away from the starting state and are back at it.
+     *
+     * The question an agent cannot otherwise ask. Reverting a component is
+     * invisible to a per-step comparison — the step *before* the revert saw it
+     * change, and the step after sees it change back, and neither says the net
+     * effect is nothing. Only the start does.
+     */
+    readonly repaired: readonly string[];
+    /**
+     * The earlier step this state is identical to, when there is one.
+     *
+     * A render hash that has been seen before means the subject is exactly where it
+     * already was, which for an agent means the loop is going in circles. Nothing
+     * else in the system can notice, because every other comparison has two
+     * elements and this needs the whole history.
+     */
+    readonly returnedTo?: number;
+    /** `true` when the subject is exactly as this session found it. */
+    readonly atStart: boolean;
+}
+/**
+ * Where the session has got to, in the terms the next decision needs.
+ *
+ * Deliberately four answers rather than a diff. A diff is what a reviewer reads
+ * at the end; what an author needs *during* the loop is whether they are closer
+ * than they were, which no single comparison can say.
+ *
+ * A trail of fewer than two steps has no progress to report — one observation is
+ * a starting state, and calling that "nothing changed" would be a claim about an
+ * edit nobody has made yet.
+ */
+export declare function progress(trail: Trail): Progress | null;
+/**
+ * The trail as the paragraph an agent reads before deciding what to do next.
+ *
+ * Written for a reader that acts on one sentence, so the ordering is by what
+ * changes the next move: whether the work is done, whether it is going in
+ * circles, what the last edit did, and only then the accumulated diff.
+ */
+export declare function summarizeTrail(trail: Trail): string;
+//# sourceMappingURL=trail.d.ts.map

package/dist/judge/trail.js

@@ -0,0 +1,96 @@
+import { causesBetween, hashComponents, } from '../attribute/component-hash.js';
+/** An empty trail for a subject. The first `record` gives it a starting state. */
+export function startTrail(subject) {
+    return { subject, steps: [] };
+}
+/**
+ * Add this observation to the trail.
+ *
+ * @throws {Error} when the snapshot is of a different subject. A trail is one
+ * subject's history, and appending another's would make every question below
+ * answer about a mixture — silently, since the shapes are identical.
+ */
+export function record(trail, snapshot, label) {
+    if (snapshot.subject.id !== trail.subject) {
+        throw new Error(`refusing to record \`${snapshot.subject.id}\` on the trail for \`${trail.subject}\`: ` +
+            'a trail is one subject and mixing two would answer every question about neither');
+    }
+    const step = {
+        at: trail.steps.length,
+        ...(label !== undefined ? { label } : {}),
+        renderHash: snapshot.renderHash,
+        components: hashesOf(snapshot),
+    };
+    return { subject: trail.subject, steps: [...trail.steps, step] };
+}
+/**
+ * Where the session has got to, in the terms the next decision needs.
+ *
+ * Deliberately four answers rather than a diff. A diff is what a reviewer reads
+ * at the end; what an author needs *during* the loop is whether they are closer
+ * than they were, which no single comparison can say.
+ *
+ * A trail of fewer than two steps has no progress to report — one observation is
+ * a starting state, and calling that "nothing changed" would be a claim about an
+ * edit nobody has made yet.
+ */
+export function progress(trail) {
+    const first = trail.steps[0];
+    const last = trail.steps.at(-1);
+    if (first === undefined || last === undefined || trail.steps.length < 2)
+        return null;
+    const previous = trail.steps.at(-2);
+    const changed = causesBetween(first.components, last.components);
+    const everChanged = new Set(trail.steps.slice(1, -1).flatMap((step) => causesBetween(first.components, step.components)));
+    const stillChanged = new Set(changed);
+    const seen = trail.steps
+        .slice(0, -1)
+        .find((step) => step.renderHash === last.renderHash);
+    return {
+        changed,
+        sinceLast: causesBetween(previous.components, last.components),
+        repaired: [...everChanged].filter((component) => !stillChanged.has(component)).sort(),
+        ...(seen !== undefined ? { returnedTo: seen.at } : {}),
+        atStart: last.renderHash === first.renderHash,
+    };
+}
+/**
+ * The trail as the paragraph an agent reads before deciding what to do next.
+ *
+ * Written for a reader that acts on one sentence, so the ordering is by what
+ * changes the next move: whether the work is done, whether it is going in
+ * circles, what the last edit did, and only then the accumulated diff.
+ */
+export function summarizeTrail(trail) {
+    const state = progress(trail);
+    if (state === null) {
+        return `${trail.subject}: ${trail.steps.length} step(s) recorded, nothing to compare yet.`;
+    }
+    const lines = [`${trail.subject}: ${trail.steps.length} steps.`];
+    if (state.atStart) {
+        lines.push('  The subject is exactly as this session found it. Nothing has net changed.');
+    }
+    else {
+        lines.push(`  Changed since step 0: ${state.changed.length === 0 ? 'nothing nameable' : state.changed.join(', ')}`);
+    }
+    if (state.returnedTo !== undefined && !state.atStart) {
+        lines.push(`  This state is identical to step ${state.returnedTo}. The last edits have cancelled ` +
+            'out — a different approach is needed, not another attempt at this one.');
+    }
+    lines.push(`  The last edit moved: ${state.sinceLast.length === 0 ? 'nothing' : state.sinceLast.join(', ')}`);
+    if (state.repaired.length > 0) {
+        lines.push(`  Back to where it started: ${state.repaired.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Component hashes for a snapshot, computed here rather than accepted.
+ *
+ * A parameter would let a caller hand a trail the hashes of one document beside
+ * the render hash of another, which makes every answer above quietly wrong and
+ * nothing detects it. Computing costs one walk of a tree already in hand.
+ */
+function hashesOf(snapshot) {
+    return hashComponents(snapshot);
+}
+//# sourceMappingURL=trail.js.map

package/dist/judge/trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../../src/judge/trail.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  causesBetween,\n  hashComponents,\n  type ComponentHash,\n} from '../attribute/component-hash.js';\nimport type { Digest } from '../format/hash.js';\nimport type { SemanticSnapshot } from '../format/snapshot.js';\n\n/**\n * What a working session accumulates, for the loop an agent actually runs.\n *\n * `observePair` compares two documents and keeps nothing, which is right for a\n * one-shot ephemeral run and wrong for the setting the mode exists to serve. An\n * agent editing components runs: observe, edit, observe, edit. Each observation\n * on its own can answer *what moved since the previous one*, and the questions\n * that decide what to do next are all about the trajectory:\n *\n * - **What have I changed since I started?** The difference between now and the\n *   first step, which is the diff a reviewer will eventually read — never the\n *   sum of the per-step differences, because an edit and its revert cancel.\n * - **Did my last edit fix what I broke two edits ago?** Components that moved\n *   away from the starting state and have since come back to it.\n * - **Is this the same difference I already saw?** A render hash that has been\n *   seen before means the subject has returned to a state this session already\n *   observed — going in circles, which is the failure mode of an agent that\n *   cannot see its own history.\n *\n * ## Why this is cheap\n *\n * A step is a *snapshot*, not an image. Collecting one is ~7.5 ms against ~65 ms\n * to paint (journal 0007, ADR-0010), and the interesting questions above are all\n * answerable from component hashes and a render hash — text. A paint happens when\n * somebody asks a question about pixels, which in an author loop is rarely and\n * never on every step.\n *\n * ## Why it is here and not in a store\n *\n * A trail is a value and this module is a function over it. Nothing accumulates\n * on disk, nothing is keyed by anything, and the standing constraint that images\n * are never kept in something that accumulates is satisfied by construction:\n * there are no images in it. The holder is whoever runs the loop — an MCP server\n * for a session, a test for its duration — and when they stop holding it, it is\n * gone. That is the ephemeral contract (ADR-0011), not an exception to it.\n *\n * ## What it cannot see\n *\n * Anything the semantic tier cannot. A `RenderDocument`'s `assets` map is\n * optional and no shipped collector fills it, so an image swapped behind an\n * unchanged URL moves no hash here and no step will mention it. That is stated\n * rather than pending: a trail is a cheap tier, and a cheap tier's blind spots\n * are the price of it being cheap. Ask a raster question when the answer matters.\n */\n\nexport interface TrailStep {\n  /**\n   * Position in the trail, from `0`. Not a time.\n   *\n   * `core` has no clock, and an ordinal is the better key anyway: an agent asks\n   * \"since I started\" and \"since my last edit\", never \"since 14:03\".\n   */\n  readonly at: number;\n\n  /** What the author said they were doing. Carried, never matched on. */\n  readonly label?: string;\n\n  /** Identity of the subject's state. Equal hashes are the same render. */\n  readonly renderHash: Digest;\n\n  readonly components: readonly ComponentHash[];\n}\n\nexport interface Trail {\n  readonly subject: string;\n  readonly steps: readonly TrailStep[];\n}\n\n/** An empty trail for a subject. The first `record` gives it a starting state. */\nexport function startTrail(subject: string): Trail {\n  return { subject, steps: [] };\n}\n\n/**\n * Add this observation to the trail.\n *\n * @throws {Error} when the snapshot is of a different subject. A trail is one\n * subject's history, and appending another's would make every question below\n * answer about a mixture — silently, since the shapes are identical.\n */\nexport function record(trail: Trail, snapshot: SemanticSnapshot, label?: string): Trail {\n  if (snapshot.subject.id !== trail.subject) {\n    throw new Error(\n      `refusing to record \\`${snapshot.subject.id}\\` on the trail for \\`${trail.subject}\\`: ` +\n        'a trail is one subject and mixing two would answer every question about neither',\n    );\n  }\n\n  const step: TrailStep = {\n    at: trail.steps.length,\n    ...(label !== undefined ? { label } : {}),\n    renderHash: snapshot.renderHash,\n    components: hashesOf(snapshot),\n  };\n\n  return { subject: trail.subject, steps: [...trail.steps, step] };\n}\n\nexport interface Progress {\n  /** Components differing from where this session started. The reviewable diff. */\n  readonly changed: readonly string[];\n\n  /** Components that differ from the previous step. What the last edit did. */\n  readonly sinceLast: readonly string[];\n\n  /**\n   * Components that had moved away from the starting state and are back at it.\n   *\n   * The question an agent cannot otherwise ask. Reverting a component is\n   * invisible to a per-step comparison — the step *before* the revert saw it\n   * change, and the step after sees it change back, and neither says the net\n   * effect is nothing. Only the start does.\n   */\n  readonly repaired: readonly string[];\n\n  /**\n   * The earlier step this state is identical to, when there is one.\n   *\n   * A render hash that has been seen before means the subject is exactly where it\n   * already was, which for an agent means the loop is going in circles. Nothing\n   * else in the system can notice, because every other comparison has two\n   * elements and this needs the whole history.\n   */\n  readonly returnedTo?: number;\n\n  /** `true` when the subject is exactly as this session found it. */\n  readonly atStart: boolean;\n}\n\n/**\n * Where the session has got to, in the terms the next decision needs.\n *\n * Deliberately four answers rather than a diff. A diff is what a reviewer reads\n * at the end; what an author needs *during* the loop is whether they are closer\n * than they were, which no single comparison can say.\n *\n * A trail of fewer than two steps has no progress to report — one observation is\n * a starting state, and calling that \"nothing changed\" would be a claim about an\n * edit nobody has made yet.\n */\nexport function progress(trail: Trail): Progress | null {\n  const first = trail.steps[0];\n  const last = trail.steps.at(-1);\n  if (first === undefined || last === undefined || trail.steps.length < 2) return null;\n\n  const previous = trail.steps.at(-2)!;\n\n  const changed = causesBetween(first.components, last.components);\n  const everChanged = new Set(\n    trail.steps.slice(1, -1).flatMap((step) => causesBetween(first.components, step.components)),\n  );\n  const stillChanged = new Set(changed);\n\n  const seen = trail.steps\n    .slice(0, -1)\n    .find((step) => step.renderHash === last.renderHash);\n\n  return {\n    changed,\n    sinceLast: causesBetween(previous.components, last.components),\n    repaired: [...everChanged].filter((component) => !stillChanged.has(component)).sort(),\n    ...(seen !== undefined ? { returnedTo: seen.at } : {}),\n    atStart: last.renderHash === first.renderHash,\n  };\n}\n\n/**\n * The trail as the paragraph an agent reads before deciding what to do next.\n *\n * Written for a reader that acts on one sentence, so the ordering is by what\n * changes the next move: whether the work is done, whether it is going in\n * circles, what the last edit did, and only then the accumulated diff.\n */\nexport function summarizeTrail(trail: Trail): string {\n  const state = progress(trail);\n  if (state === null) {\n    return `${trail.subject}: ${trail.steps.length} step(s) recorded, nothing to compare yet.`;\n  }\n\n  const lines = [`${trail.subject}: ${trail.steps.length} steps.`];\n\n  if (state.atStart) {\n    lines.push('  The subject is exactly as this session found it. Nothing has net changed.');\n  } else {\n    lines.push(\n      `  Changed since step 0: ${state.changed.length === 0 ? 'nothing nameable' : state.changed.join(', ')}`,\n    );\n  }\n\n  if (state.returnedTo !== undefined && !state.atStart) {\n    lines.push(\n      `  This state is identical to step ${state.returnedTo}. The last edits have cancelled ` +\n        'out — a different approach is needed, not another attempt at this one.',\n    );\n  }\n\n  lines.push(\n    `  The last edit moved: ${state.sinceLast.length === 0 ? 'nothing' : state.sinceLast.join(', ')}`,\n  );\n\n  if (state.repaired.length > 0) {\n    lines.push(`  Back to where it started: ${state.repaired.join(', ')}`);\n  }\n\n  return lines.join('\\n');\n}\n\n/**\n * Component hashes for a snapshot, computed here rather than accepted.\n *\n * A parameter would let a caller hand a trail the hashes of one document beside\n * the render hash of another, which makes every answer above quietly wrong and\n * nothing detects it. Computing costs one walk of a tree already in hand.\n */\nfunction hashesOf(snapshot: SemanticSnapshot): readonly ComponentHash[] {\n  return hashComponents(snapshot);\n}\n"]}