@variance-authority/report 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@variance-authority/report` — what a run leaves behind.
+ *
+ * The **record** tool kind, in a box of its own. A run produces values in memory
+ * and then the process ends; this is the shape the answers take so they can be
+ * read afterwards, from a different process, on a different machine, by whoever
+ * or whatever is asking.
+ *
+ * It lives here rather than with any of its readers because it has several, and
+ * a format owned by one of them bends towards that one. The CLI writes it, the
+ * MCP tools read it, a PR comment renders it, and none of those is the format's
+ * home. That was not a hypothetical: the shapes used to live in the MCP package,
+ * so the CLI depended on an agent protocol to describe its own output.
+ *
+ * It also holds the three derivations that belong to the format rather than to any
+ * reader. The first groups a run's changes into the *distinct things that
+ * happened*, so a token edit across forty stories is one decision rather than
+ * forty. The second reads those changes back against what the author said they
+ * were doing, which is the only way an artifact can report the edit that never
+ * landed. The third folds what a reviewer accepted into the record of *why a
+ * baseline is what it is*, which outlives this file — into a commit message where
+ * baselines are commits, into a row where they are rows. The CLI prints them, the
+ * MCP tools answer from them, and none of those owns them.
+ *
+ * The default entrypoint is the format and needs nothing.
+ * `@variance-authority/report/file` reads and writes it on a disk.
+ */
+export type { RunReport, ObservationRecord, RegionRecord, FindingRecord, PresentationEffectEvidence, PresentationEffectRecord, PresentationEffectTransition, PresentationInformationRecord, PresentationSignalRecord, NotObserved, NotObservedKind, FlakinessRecord, ChurnRecord, DriftRecord, VariationRecord, } from './format.js';
+export type { CompositionReport, ComponentRecord, EchoRecord, DivergenceRecord, PartingRecord, MovementRecord, } from './composition.js';
+export type { ReachReport, ReachedComponent, ReachHole, SubjectReach, } from './reach.js';
+export { absorbedBands, greenBecause, ignoreSays, ignoreState, ignoreShare, ignoreTotals, isActionable, sensitivitySays, sensitivityState, sensitivityShare, sensitivityTotals, } from './declarations.js';
+export type { Green, GreenSubject, IgnoreLedger, IgnoreState, IgnoreUsage, SensitivityLedger, SensitivityState, SensitivityUsage, } from './declarations.js';
+export { AGE_WHY, AGE_WORDS, ageOf, arrivalLine, bandTitle, byArrival, byBand, carriedLine, findingTotals, methodLine, mixedAges, } from './findings.js';
+export type { Age, Arrival, Grouped } from './findings.js';
+export { clusterChanges, describeClustering } from './cluster.js';
+export type { Change, Clustering } from './cluster.js';
+export { changelogOf, isRecorded } from './changelog.js';
+export type { ChangelogDrift, ChangelogEntry, ChangelogOptions, ChangelogRecord, ChangelogSelection, Unrecordable, } from './changelog.js';
+export { changelogBody, parseCommitMessage, renderCommitMessage, } from './changelog-message.js';
+export type { CommitMessageOptions } from './changelog-message.js';
+export { promotionOf, selectByShape, whyNotWhole } from './promotion.js';
+export type { Promotion } from './promotion.js';
+export { adjudicateRun, describeAdjudication, parseRoot } from './intent.js';
+export type { AdjudicateOptions, Claim, ClaimOutcome, ClaimRootKind, ClaimVerdict, RunAdjudication, UnclaimedChange, } from './intent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * `@variance-authority/report` — what a run leaves behind.
+ *
+ * The **record** tool kind, in a box of its own. A run produces values in memory
+ * and then the process ends; this is the shape the answers take so they can be
+ * read afterwards, from a different process, on a different machine, by whoever
+ * or whatever is asking.
+ *
+ * It lives here rather than with any of its readers because it has several, and
+ * a format owned by one of them bends towards that one. The CLI writes it, the
+ * MCP tools read it, a PR comment renders it, and none of those is the format's
+ * home. That was not a hypothetical: the shapes used to live in the MCP package,
+ * so the CLI depended on an agent protocol to describe its own output.
+ *
+ * It also holds the three derivations that belong to the format rather than to any
+ * reader. The first groups a run's changes into the *distinct things that
+ * happened*, so a token edit across forty stories is one decision rather than
+ * forty. The second reads those changes back against what the author said they
+ * were doing, which is the only way an artifact can report the edit that never
+ * landed. The third folds what a reviewer accepted into the record of *why a
+ * baseline is what it is*, which outlives this file — into a commit message where
+ * baselines are commits, into a row where they are rows. The CLI prints them, the
+ * MCP tools answer from them, and none of those owns them.
+ *
+ * The default entrypoint is the format and needs nothing.
+ * `@variance-authority/report/file` reads and writes it on a disk.
+ */
+export { absorbedBands, greenBecause, ignoreSays, ignoreState, ignoreShare, ignoreTotals, isActionable, sensitivitySays, sensitivityState, sensitivityShare, sensitivityTotals, } from './declarations.js';
+export { AGE_WHY, AGE_WORDS, ageOf, arrivalLine, bandTitle, byArrival, byBand, carriedLine, findingTotals, methodLine, mixedAges, } from './findings.js';
+export { clusterChanges, describeClustering } from './cluster.js';
+export { changelogOf, isRecorded } from './changelog.js';
+export { changelogBody, parseCommitMessage, renderCommitMessage, } from './changelog-message.js';
+export { promotionOf, selectByShape, whyNotWhole } from './promotion.js';
+export { adjudicateRun, describeAdjudication, parseRoot } from './intent.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoCH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EACL,OAAO,EACP,SAAS,EACT,KAAK,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,MAAM,EACN,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAUzD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/**\n * `@variance-authority/report` — what a run leaves behind.\n *\n * The **record** tool kind, in a box of its own. A run produces values in memory\n * and then the process ends; this is the shape the answers take so they can be\n * read afterwards, from a different process, on a different machine, by whoever\n * or whatever is asking.\n *\n * It lives here rather than with any of its readers because it has several, and\n * a format owned by one of them bends towards that one. The CLI writes it, the\n * MCP tools read it, a PR comment renders it, and none of those is the format's\n * home. That was not a hypothetical: the shapes used to live in the MCP package,\n * so the CLI depended on an agent protocol to describe its own output.\n *\n * It also holds the three derivations that belong to the format rather than to any\n * reader. The first groups a run's changes into the *distinct things that\n * happened*, so a token edit across forty stories is one decision rather than\n * forty. The second reads those changes back against what the author said they\n * were doing, which is the only way an artifact can report the edit that never\n * landed. The third folds what a reviewer accepted into the record of *why a\n * baseline is what it is*, which outlives this file — into a commit message where\n * baselines are commits, into a row where they are rows. The CLI prints them, the\n * MCP tools answer from them, and none of those owns them.\n *\n * The default entrypoint is the format and needs nothing.\n * `@variance-authority/report/file` reads and writes it on a disk.\n */\n\nexport type {\n  RunReport,\n  ObservationRecord,\n  RegionRecord,\n  FindingRecord,\n  PresentationEffectEvidence,\n  PresentationEffectRecord,\n  PresentationEffectTransition,\n  PresentationInformationRecord,\n  PresentationSignalRecord,\n  NotObserved,\n  NotObservedKind,\n  FlakinessRecord,\n  ChurnRecord,\n  DriftRecord,\n  VariationRecord,\n} from './format.js';\n\nexport type {\n  CompositionReport,\n  ComponentRecord,\n  EchoRecord,\n  DivergenceRecord,\n  PartingRecord,\n  MovementRecord,\n} from './composition.js';\n\nexport type {\n  ReachReport,\n  ReachedComponent,\n  ReachHole,\n  SubjectReach,\n} from './reach.js';\n\nexport {\n  absorbedBands,\n  greenBecause,\n  ignoreSays,\n  ignoreState,\n  ignoreShare,\n  ignoreTotals,\n  isActionable,\n  sensitivitySays,\n  sensitivityState,\n  sensitivityShare,\n  sensitivityTotals,\n} from './declarations.js';\nexport type {\n  Green,\n  GreenSubject,\n  IgnoreLedger,\n  IgnoreState,\n  IgnoreUsage,\n  SensitivityLedger,\n  SensitivityState,\n  SensitivityUsage,\n} from './declarations.js';\n\nexport {\n  AGE_WHY,\n  AGE_WORDS,\n  ageOf,\n  arrivalLine,\n  bandTitle,\n  byArrival,\n  byBand,\n  carriedLine,\n  findingTotals,\n  methodLine,\n  mixedAges,\n} from './findings.js';\nexport type { Age, Arrival, Grouped } from './findings.js';\n\nexport { clusterChanges, describeClustering } from './cluster.js';\nexport type { Change, Clustering } from './cluster.js';\n\nexport { changelogOf, isRecorded } from './changelog.js';\nexport type {\n  ChangelogDrift,\n  ChangelogEntry,\n  ChangelogOptions,\n  ChangelogRecord,\n  ChangelogSelection,\n  Unrecordable,\n} from './changelog.js';\n\nexport {\n  changelogBody,\n  parseCommitMessage,\n  renderCommitMessage,\n} from './changelog-message.js';\nexport type { CommitMessageOptions } from './changelog-message.js';\n\nexport { promotionOf, selectByShape, whyNotWhole } from './promotion.js';\nexport type { Promotion } from './promotion.js';\n\nexport { adjudicateRun, describeAdjudication, parseRoot } from './intent.js';\nexport type {\n  AdjudicateOptions,\n  Claim,\n  ClaimOutcome,\n  ClaimRootKind,\n  ClaimVerdict,\n  RunAdjudication,\n  UnclaimedChange,\n} from './intent.js';\n"]}

package/dist/intent.d.ts

@@ -0,0 +1,168 @@
+import type { Change } from './cluster.js';
+import type { NotObserved, RunReport } from './format.js';
+/**
+ * A claim, and what the run did with it.
+ *
+ * ## The half nobody asks for
+ *
+ * Everything else in this package answers *what changed*. That is not the
+ * question an agent that just edited a component is asking. It already knows what
+ * it meant to do; what it cannot know is whether the edit landed, whether it
+ * landed only where it was supposed to, and whether the thing it did not mean to
+ * touch moved anyway.
+ *
+ * So the agent declares first — *I am changing `Button`, paint only, at most 12
+ * subjects* — and the run is read back against the declaration. Three arms come
+ * out, and they are three different products:
+ *
+ * - **Delivered.** The change happened where it was declared. Confirmation, and
+ *   the cheapest of the three.
+ * - **Unclaimed.** Something moved that no claim covers. The collateral to fix,
+ *   or to name in the proposal before a human finds it.
+ * - **Undelivered.** A claim that matched nothing. *The edit did not take* —
+ *   wrong file, dead branch, a rule something else overrides, a stale build.
+ *
+ * The third arm is the one aimed at the failure mode an agent actually has:
+ * acting, observing nothing, and proceeding on the belief that the action landed.
+ * A picture cannot produce it. A build with no diff and a build where the edit
+ * never ran are the same image, and every tool whose output is a score over two
+ * PNGs reports them identically.
+ *
+ * It also disciplines the other two. An agent that claims everything so nothing
+ * can ever be unclaimed walks straight into arm three, because a claim with no
+ * matching change is reported rather than absorbed. Over-claiming is visible by
+ * construction, not by policy.
+ *
+ * ## Declared before, not after
+ *
+ * A claim read out of the diff is not a claim. This function takes the
+ * declaration as an input and never derives one, which is what keeps the
+ * adjudication from scoring the run against itself.
+ *
+ * ## Why an undelivered claim has two different answers
+ *
+ * `Button` was claimed and nothing about `Button` changed. That is either
+ *
+ * - the run rendered `Button` — in this many subjects — and it did not move, so
+ *   the edit did not take; or
+ * - the run never rendered `Button` at all, so the claim was not checked and
+ *   nothing here may be read as evidence about it.
+ *
+ * Those are opposite instructions. The first sends an agent back to its own edit;
+ * the second sends it to the subject list, or to the provenance that would have
+ * named the component. The census in
+ * [`CompositionReport`](./composition.ts) is what separates them, and where a run
+ * kept no census this says *that*, rather than collapsing the pair into the
+ * reading that happens to be more flattering.
+ *
+ * ## The relationship to core's `adjudicate`
+ *
+ * `@variance-authority/core` adjudicates a **docket** — roots with bands,
+ * impacts, and a project policy — which exists while a run is in memory. A run
+ * report keeps no roots (see [`format.ts`](./format.ts): what is kept is what a
+ * sentence needs), so this adjudicates at the resolution the artifact actually
+ * recorded: the component and the shape. It is the same three arms against less
+ * evidence, and the fields it cannot check it names instead of ignoring.
+ */
+/** What a claim may be made about, at the resolution a run report keeps. */
+export type ClaimRootKind = 'component' | 'shape';
+export interface Claim {
+    /**
+     * What the change is about: `component:Button`, `shape:<fingerprint>`, or a
+     * bare name read as a component.
+     *
+     * Matched exactly. A prefix match would let a claim about `Button` silently
+     * authorize a change to `ButtonGroup`, which is the one thing a declaration
+     * must never do.
+     */
+    readonly root: string;
+    /** Why. Never matched on; carried into the answer so a reader has the context. */
+    readonly reason: string;
+    /**
+     * Cap on how many subjects the change may reach.
+     *
+     * The most useful field in practice, and the one nobody checks unaided. "I
+     * meant to restyle `Button`" is almost always true; "I meant to restyle
+     * `Button` in 3 subjects" is the part that turns out to be 40.
+     */
+    readonly maxSubjects?: number;
+}
+export type ClaimVerdict = 
+/** Matched, within its declared bound. */
+'delivered'
+/** Matched, and reached further than declared. Still the intended change. */
+ | 'overreached'
+/** Matched nothing, and the run watched it. The edit did not take. */
+ | 'undelivered'
+/** Matched nothing, and the run could not have seen it either way. */
+ | 'unobservable';
+export interface ClaimOutcome {
+    readonly claim: Claim;
+    readonly verdict: ClaimVerdict;
+    /** Changes this claim accounts for, most widespread first. */
+    readonly changes: readonly Change[];
+    /** Subjects reached, deduplicated across the matched changes. */
+    readonly subjects: readonly string[];
+    /** One sentence, ready to print, naming the next move rather than the state. */
+    readonly because: string;
+}
+export interface UnclaimedChange {
+    readonly change: Change;
+    readonly because: string;
+}
+export interface RunAdjudication {
+    readonly claims: readonly ClaimOutcome[];
+    /** Changes no claim covers. Arm two, in report order. */
+    readonly unclaimed: readonly UnclaimedChange[];
+    /**
+     * Changed subjects that produced no shape at all.
+     *
+     * Never folded into either arm. A run with no document behind its comparison
+     * cannot say what moved, so it cannot say whether a claim covers it — and
+     * counting these as unclaimed would invent collateral out of missing evidence.
+     */
+    readonly ungrouped: readonly string[];
+    /**
+     * Subjects the run meant to observe and did not.
+     *
+     * Carried because it bounds every other line here. A claim checked against a
+     * run that failed on 50 of 300 subjects is a claim checked against 250, and an
+     * agent told `delivered` without being told that has been told something the
+     * run never established.
+     */
+    readonly blind: readonly NotObserved[];
+    /**
+     * The worst thing present, in the order an agent should act on it.
+     *
+     * `unmet` outranks `review`: a claim that did not land means the agent's own
+     * last action failed, and there is no point triaging collateral from an edit
+     * that never happened.
+     */
+    readonly verdict: 'clean' | 'review' | 'unmet';
+}
+export interface AdjudicateOptions {
+    /**
+     * Claim fields the caller supplied that this resolution cannot check.
+     *
+     * The boundary that parses agent input passes them through so the answer can
+     * say so. Silently dropping a declared band would tell an agent its band claim
+     * held when nothing looked at it.
+     */
+    readonly unchecked?: readonly string[];
+}
+/** Adjudicate a run against what its author said they were doing. */
+export declare function adjudicateRun(report: RunReport, claims: readonly Claim[], options?: AdjudicateOptions): RunAdjudication;
+/** `component:Button`, `shape:ab12…`, or a bare name read as a component. */
+export declare function parseRoot(root: string): {
+    kind: ClaimRootKind;
+    name: string;
+};
+/**
+ * The adjudication as the thing an agent reads before deciding what to do next.
+ *
+ * Ordered by what it should act on, not by what the run computed first:
+ * undelivered claims lead, because an agent triaging collateral from an edit that
+ * never happened is an agent about to make its second mistake.
+ */
+export declare function describeAdjudication(result: RunAdjudication): string;
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.js

@@ -0,0 +1,214 @@
+import { clusterChanges } from './cluster.js';
+/** Adjudicate a run against what its author said they were doing. */
+export function adjudicateRun(report, claims, options = {}) {
+    const clustering = clusterChanges(report.observations);
+    const census = componentCensus(report);
+    const taken = new Set();
+    const outcomes = claims.map((claim) => {
+        const matched = clustering.changes.filter((change) => covers(claim, change));
+        for (const change of matched)
+            taken.add(change);
+        return outcomeOf(claim, matched, census, options);
+    });
+    const unclaimed = clustering.changes
+        .filter((change) => !taken.has(change))
+        .map((change) => ({ change, because: unclaimedBecause(change) }));
+    return {
+        claims: outcomes,
+        unclaimed,
+        ungrouped: clustering.ungrouped,
+        blind: report.notObserved ?? [],
+        verdict: worst(outcomes, unclaimed, clustering),
+    };
+}
+/**
+ * Subjects each component was rendered in, or `undefined` when the run kept no
+ * census.
+ *
+ * `undefined` and an empty map are different claims and both occur: a run with no
+ * semantic snapshots to fold has no composition section at all, and reading that
+ * as "no component rendered anywhere" would turn every claim into evidence of a
+ * failed edit.
+ */
+function componentCensus(report) {
+    const components = report.composition?.components;
+    if (components === undefined)
+        return undefined;
+    return new Map(components.map((record) => [record.component, record.subjects]));
+}
+function covers(claim, change) {
+    const { kind, name } = parseRoot(claim.root);
+    return kind === 'shape' ? change.fingerprint === name : change.component === name;
+}
+/** `component:Button`, `shape:ab12…`, or a bare name read as a component. */
+export function parseRoot(root) {
+    const separator = root.indexOf(':');
+    if (separator === -1)
+        return { kind: 'component', name: root };
+    const prefix = root.slice(0, separator);
+    const name = root.slice(separator + 1);
+    return prefix === 'shape'
+        ? { kind: 'shape', name }
+        : { kind: 'component', name: prefix === 'component' ? name : root };
+}
+function outcomeOf(claim, matched, census, options) {
+    const subjects = [...new Set(matched.flatMap((change) => change.subjects))];
+    const caveat = options.unchecked?.length ? ` Not checked here: ${options.unchecked.join(', ')}.` : '';
+    if (matched.length === 0)
+        return undeliveredOutcome(claim, census, caveat);
+    const exceeded = claim.maxSubjects !== undefined && subjects.length > claim.maxSubjects;
+    const where = `${claim.root} changed in ${subjects.length} subject(s): ${preview(subjects)}`;
+    return exceeded
+        ? {
+            claim,
+            verdict: 'overreached',
+            changes: matched,
+            subjects,
+            // Not a failure: the change is the declared one. What missed is the
+            // author's estimate of its blast radius, which is the half worth showing
+            // them rather than blocking on.
+            because: `declared (${claim.reason}) and delivered, but reached ${subjects.length} ` +
+                `subject(s) against the ${claim.maxSubjects} declared — the change is the ` +
+                `intended one, its reach is not.${caveat}`,
+        }
+        : {
+            claim,
+            verdict: 'delivered',
+            changes: matched,
+            subjects,
+            because: `declared (${claim.reason}) and delivered: ${where}.${caveat}`,
+        };
+}
+/** Arm three, split by whether the run was in a position to see the claim fail. */
+function undeliveredOutcome(claim, census, caveat) {
+    const { kind, name } = parseRoot(claim.root);
+    const blank = { claim, changes: [], subjects: [] };
+    if (kind === 'shape') {
+        return {
+            ...blank,
+            verdict: 'undelivered',
+            // A shape is a digest of a difference. Claiming one that did not occur is
+            // always the strong reading: nothing else could have produced it.
+            because: `declared (${claim.reason}) and no change in this run carries shape ` +
+                `\`${name}\` — nothing produced that difference.${caveat}`,
+        };
+    }
+    if (census === undefined) {
+        return {
+            ...blank,
+            verdict: 'unobservable',
+            because: `declared (${claim.reason}) and nothing changed under \`${name}\`, but this run ` +
+                'kept no component census, so it cannot say whether `' +
+                name +
+                '` was rendered at all. The claim was not checked.' +
+                caveat,
+        };
+    }
+    const rendered = census.get(name);
+    if (rendered === undefined) {
+        return {
+            ...blank,
+            verdict: 'unobservable',
+            because: `declared (${claim.reason}) and this run never rendered \`${name}\` in any subject, ` +
+                'so nothing here is evidence about it either way. Check the subject selection, or ' +
+                'whether provenance names this component.' +
+                caveat,
+        };
+    }
+    return {
+        ...blank,
+        verdict: 'undelivered',
+        because: `declared (${claim.reason}) and \`${name}\` rendered in ${rendered.length} subject(s) ` +
+            `— ${preview(rendered)} — and did not change. The edit did not take: wrong file, a ` +
+            'dead branch, a rule something else overrides, or a stale build.' +
+            caveat,
+    };
+}
+function unclaimedBecause(change) {
+    const named = change.component ?? '(no component resolved; grouped by shape alone)';
+    const settle = change.settles.length === 0
+        ? 'nothing it can settle on its own'
+        : `settles ${change.settles.length} of them`;
+    return (`${named} moved and no claim covers it — ${change.subjects.length} subject(s), ` +
+        `${change.pixels} pixel(s), ${settle}` +
+        (change.cause ? '' : '; it was displaced rather than edited'));
+}
+function worst(outcomes, unclaimed, clustering) {
+    if (outcomes.some((outcome) => outcome.verdict === 'undelivered'))
+        return 'unmet';
+    if (unclaimed.length > 0 || clustering.ungrouped.length > 0)
+        return 'review';
+    if (outcomes.some((outcome) => outcome.verdict !== 'delivered'))
+        return 'review';
+    return 'clean';
+}
+/**
+ * The adjudication as the thing an agent reads before deciding what to do next.
+ *
+ * Ordered by what it should act on, not by what the run computed first:
+ * undelivered claims lead, because an agent triaging collateral from an edit that
+ * never happened is an agent about to make its second mistake.
+ */
+export function describeAdjudication(result) {
+    const counts = tally(result);
+    const lines = [headline(result, counts)];
+    const order = ['undelivered', 'unobservable', 'overreached', 'delivered'];
+    for (const verdict of order) {
+        for (const outcome of result.claims.filter((claim) => claim.verdict === verdict)) {
+            lines.push('', `  [${outcome.verdict}] ${outcome.claim.root}`, `      ${outcome.because}`);
+            for (const change of outcome.changes) {
+                if (change.file !== undefined)
+                    lines.push(`      ${change.file}`);
+            }
+        }
+    }
+    for (const entry of result.unclaimed) {
+        lines.push('', `  [unclaimed] ${entry.change.component ?? entry.change.fingerprint}`);
+        lines.push(`      ${entry.because}`);
+        if (entry.change.file !== undefined)
+            lines.push(`      ${entry.change.file}`);
+        if (entry.change.settles.length > 0) {
+            lines.push(`      variance accept --shape ${entry.change.fingerprint}`);
+        }
+    }
+    if (result.ungrouped.length > 0) {
+        lines.push('', `  [ungrouped] ${result.ungrouped.length} changed subject(s) carry no shape, so no claim ` +
+            'could be checked against them: ' +
+            preview(result.ungrouped));
+    }
+    if (result.blind.length > 0) {
+        lines.push('', `  [not observed] ${result.blind.length} subject(s) were not looked at, so every line ` +
+            'above is bounded by what this run saw: ' +
+            preview(result.blind.map((entry) => entry.subject)));
+    }
+    return lines.join('\n');
+}
+function headline(result, counts) {
+    const claims = `${result.claims.length} claim(s): ${counts.delivered} delivered, ` +
+        `${counts.undelivered} undelivered, ${counts.overreached} over-reaching, ` +
+        `${counts.unobservable} unchecked.`;
+    const lead = result.verdict === 'unmet'
+        ? 'An edit you declared did not take. Fix that before reading anything else.'
+        : result.verdict === 'review'
+            ? 'Every declared edit landed; something you did not declare also moved.'
+            : 'Every declared edit landed, and nothing else moved.';
+    return `${lead}\n${claims} ${result.unclaimed.length} unclaimed change(s).`;
+}
+function tally(result) {
+    const counts = {
+        delivered: 0,
+        overreached: 0,
+        undelivered: 0,
+        unobservable: 0,
+    };
+    for (const outcome of result.claims)
+        counts[outcome.verdict] += 1;
+    return counts;
+}
+/** The first few, because a reader wants examples and not a manifest. */
+function preview(items) {
+    return items.length <= 4
+        ? items.join(', ')
+        : `${items.slice(0, 4).join(', ')}, and ${items.length - 4} more`;
+}
+//# sourceMappingURL=intent.js.map

package/dist/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Change, Clustering } from './cluster.js';\nimport { clusterChanges } from './cluster.js';\nimport type { NotObserved, RunReport } from './format.js';\n\n/**\n * A claim, and what the run did with it.\n *\n * ## The half nobody asks for\n *\n * Everything else in this package answers *what changed*. That is not the\n * question an agent that just edited a component is asking. It already knows what\n * it meant to do; what it cannot know is whether the edit landed, whether it\n * landed only where it was supposed to, and whether the thing it did not mean to\n * touch moved anyway.\n *\n * So the agent declares first — *I am changing `Button`, paint only, at most 12\n * subjects* — and the run is read back against the declaration. Three arms come\n * out, and they are three different products:\n *\n * - **Delivered.** The change happened where it was declared. Confirmation, and\n *   the cheapest of the three.\n * - **Unclaimed.** Something moved that no claim covers. The collateral to fix,\n *   or to name in the proposal before a human finds it.\n * - **Undelivered.** A claim that matched nothing. *The edit did not take* —\n *   wrong file, dead branch, a rule something else overrides, a stale build.\n *\n * The third arm is the one aimed at the failure mode an agent actually has:\n * acting, observing nothing, and proceeding on the belief that the action landed.\n * A picture cannot produce it. A build with no diff and a build where the edit\n * never ran are the same image, and every tool whose output is a score over two\n * PNGs reports them identically.\n *\n * It also disciplines the other two. An agent that claims everything so nothing\n * can ever be unclaimed walks straight into arm three, because a claim with no\n * matching change is reported rather than absorbed. Over-claiming is visible by\n * construction, not by policy.\n *\n * ## Declared before, not after\n *\n * A claim read out of the diff is not a claim. This function takes the\n * declaration as an input and never derives one, which is what keeps the\n * adjudication from scoring the run against itself.\n *\n * ## Why an undelivered claim has two different answers\n *\n * `Button` was claimed and nothing about `Button` changed. That is either\n *\n * - the run rendered `Button` — in this many subjects — and it did not move, so\n *   the edit did not take; or\n * - the run never rendered `Button` at all, so the claim was not checked and\n *   nothing here may be read as evidence about it.\n *\n * Those are opposite instructions. The first sends an agent back to its own edit;\n * the second sends it to the subject list, or to the provenance that would have\n * named the component. The census in\n * [`CompositionReport`](./composition.ts) is what separates them, and where a run\n * kept no census this says *that*, rather than collapsing the pair into the\n * reading that happens to be more flattering.\n *\n * ## The relationship to core's `adjudicate`\n *\n * `@variance-authority/core` adjudicates a **docket** — roots with bands,\n * impacts, and a project policy — which exists while a run is in memory. A run\n * report keeps no roots (see [`format.ts`](./format.ts): what is kept is what a\n * sentence needs), so this adjudicates at the resolution the artifact actually\n * recorded: the component and the shape. It is the same three arms against less\n * evidence, and the fields it cannot check it names instead of ignoring.\n */\n\n/** What a claim may be made about, at the resolution a run report keeps. */\nexport type ClaimRootKind = 'component' | 'shape';\n\nexport interface Claim {\n  /**\n   * What the change is about: `component:Button`, `shape:<fingerprint>`, or a\n   * bare name read as a component.\n   *\n   * Matched exactly. A prefix match would let a claim about `Button` silently\n   * authorize a change to `ButtonGroup`, which is the one thing a declaration\n   * must never do.\n   */\n  readonly root: string;\n\n  /** Why. Never matched on; carried into the answer so a reader has the context. */\n  readonly reason: string;\n\n  /**\n   * Cap on how many subjects the change may reach.\n   *\n   * The most useful field in practice, and the one nobody checks unaided. \"I\n   * meant to restyle `Button`\" is almost always true; \"I meant to restyle\n   * `Button` in 3 subjects\" is the part that turns out to be 40.\n   */\n  readonly maxSubjects?: number;\n}\n\nexport type ClaimVerdict =\n  /** Matched, within its declared bound. */\n  | 'delivered'\n  /** Matched, and reached further than declared. Still the intended change. */\n  | 'overreached'\n  /** Matched nothing, and the run watched it. The edit did not take. */\n  | 'undelivered'\n  /** Matched nothing, and the run could not have seen it either way. */\n  | 'unobservable';\n\nexport interface ClaimOutcome {\n  readonly claim: Claim;\n  readonly verdict: ClaimVerdict;\n  /** Changes this claim accounts for, most widespread first. */\n  readonly changes: readonly Change[];\n  /** Subjects reached, deduplicated across the matched changes. */\n  readonly subjects: readonly string[];\n  /** One sentence, ready to print, naming the next move rather than the state. */\n  readonly because: string;\n}\n\nexport interface UnclaimedChange {\n  readonly change: Change;\n  readonly because: string;\n}\n\nexport interface RunAdjudication {\n  readonly claims: readonly ClaimOutcome[];\n  /** Changes no claim covers. Arm two, in report order. */\n  readonly unclaimed: readonly UnclaimedChange[];\n\n  /**\n   * Changed subjects that produced no shape at all.\n   *\n   * Never folded into either arm. A run with no document behind its comparison\n   * cannot say what moved, so it cannot say whether a claim covers it — and\n   * counting these as unclaimed would invent collateral out of missing evidence.\n   */\n  readonly ungrouped: readonly string[];\n\n  /**\n   * Subjects the run meant to observe and did not.\n   *\n   * Carried because it bounds every other line here. A claim checked against a\n   * run that failed on 50 of 300 subjects is a claim checked against 250, and an\n   * agent told `delivered` without being told that has been told something the\n   * run never established.\n   */\n  readonly blind: readonly NotObserved[];\n\n  /**\n   * The worst thing present, in the order an agent should act on it.\n   *\n   * `unmet` outranks `review`: a claim that did not land means the agent's own\n   * last action failed, and there is no point triaging collateral from an edit\n   * that never happened.\n   */\n  readonly verdict: 'clean' | 'review' | 'unmet';\n}\n\nexport interface AdjudicateOptions {\n  /**\n   * Claim fields the caller supplied that this resolution cannot check.\n   *\n   * The boundary that parses agent input passes them through so the answer can\n   * say so. Silently dropping a declared band would tell an agent its band claim\n   * held when nothing looked at it.\n   */\n  readonly unchecked?: readonly string[];\n}\n\n/** Adjudicate a run against what its author said they were doing. */\nexport function adjudicateRun(\n  report: RunReport,\n  claims: readonly Claim[],\n  options: AdjudicateOptions = {},\n): RunAdjudication {\n  const clustering = clusterChanges(report.observations);\n  const census = componentCensus(report);\n\n  const taken = new Set<Change>();\n  const outcomes = claims.map((claim) => {\n    const matched = clustering.changes.filter((change) => covers(claim, change));\n    for (const change of matched) taken.add(change);\n    return outcomeOf(claim, matched, census, options);\n  });\n\n  const unclaimed = clustering.changes\n    .filter((change) => !taken.has(change))\n    .map((change) => ({ change, because: unclaimedBecause(change) }));\n\n  return {\n    claims: outcomes,\n    unclaimed,\n    ungrouped: clustering.ungrouped,\n    blind: report.notObserved ?? [],\n    verdict: worst(outcomes, unclaimed, clustering),\n  };\n}\n\n/**\n * Subjects each component was rendered in, or `undefined` when the run kept no\n * census.\n *\n * `undefined` and an empty map are different claims and both occur: a run with no\n * semantic snapshots to fold has no composition section at all, and reading that\n * as \"no component rendered anywhere\" would turn every claim into evidence of a\n * failed edit.\n */\nfunction componentCensus(report: RunReport): Map<string, readonly string[]> | undefined {\n  const components = report.composition?.components;\n  if (components === undefined) return undefined;\n\n  return new Map(components.map((record) => [record.component, record.subjects]));\n}\n\nfunction covers(claim: Claim, change: Change): boolean {\n  const { kind, name } = parseRoot(claim.root);\n\n  return kind === 'shape' ? change.fingerprint === name : change.component === name;\n}\n\n/** `component:Button`, `shape:ab12…`, or a bare name read as a component. */\nexport function parseRoot(root: string): { kind: ClaimRootKind; name: string } {\n  const separator = root.indexOf(':');\n  if (separator === -1) return { kind: 'component', name: root };\n\n  const prefix = root.slice(0, separator);\n  const name = root.slice(separator + 1);\n\n  return prefix === 'shape'\n    ? { kind: 'shape', name }\n    : { kind: 'component', name: prefix === 'component' ? name : root };\n}\n\nfunction outcomeOf(\n  claim: Claim,\n  matched: readonly Change[],\n  census: Map<string, readonly string[]> | undefined,\n  options: AdjudicateOptions,\n): ClaimOutcome {\n  const subjects = [...new Set(matched.flatMap((change) => change.subjects))];\n  const caveat = options.unchecked?.length ? ` Not checked here: ${options.unchecked.join(', ')}.` : '';\n\n  if (matched.length === 0) return undeliveredOutcome(claim, census, caveat);\n\n  const exceeded = claim.maxSubjects !== undefined && subjects.length > claim.maxSubjects;\n  const where = `${claim.root} changed in ${subjects.length} subject(s): ${preview(subjects)}`;\n\n  return exceeded\n    ? {\n        claim,\n        verdict: 'overreached',\n        changes: matched,\n        subjects,\n        // Not a failure: the change is the declared one. What missed is the\n        // author's estimate of its blast radius, which is the half worth showing\n        // them rather than blocking on.\n        because:\n          `declared (${claim.reason}) and delivered, but reached ${subjects.length} ` +\n          `subject(s) against the ${claim.maxSubjects} declared — the change is the ` +\n          `intended one, its reach is not.${caveat}`,\n      }\n    : {\n        claim,\n        verdict: 'delivered',\n        changes: matched,\n        subjects,\n        because: `declared (${claim.reason}) and delivered: ${where}.${caveat}`,\n      };\n}\n\n/** Arm three, split by whether the run was in a position to see the claim fail. */\nfunction undeliveredOutcome(\n  claim: Claim,\n  census: Map<string, readonly string[]> | undefined,\n  caveat: string,\n): ClaimOutcome {\n  const { kind, name } = parseRoot(claim.root);\n  const blank = { claim, changes: [], subjects: [] } as const;\n\n  if (kind === 'shape') {\n    return {\n      ...blank,\n      verdict: 'undelivered',\n      // A shape is a digest of a difference. Claiming one that did not occur is\n      // always the strong reading: nothing else could have produced it.\n      because:\n        `declared (${claim.reason}) and no change in this run carries shape ` +\n        `\\`${name}\\` — nothing produced that difference.${caveat}`,\n    };\n  }\n\n  if (census === undefined) {\n    return {\n      ...blank,\n      verdict: 'unobservable',\n      because:\n        `declared (${claim.reason}) and nothing changed under \\`${name}\\`, but this run ` +\n        'kept no component census, so it cannot say whether `' +\n        name +\n        '` was rendered at all. The claim was not checked.' +\n        caveat,\n    };\n  }\n\n  const rendered = census.get(name);\n\n  if (rendered === undefined) {\n    return {\n      ...blank,\n      verdict: 'unobservable',\n      because:\n        `declared (${claim.reason}) and this run never rendered \\`${name}\\` in any subject, ` +\n        'so nothing here is evidence about it either way. Check the subject selection, or ' +\n        'whether provenance names this component.' +\n        caveat,\n    };\n  }\n\n  return {\n    ...blank,\n    verdict: 'undelivered',\n    because:\n      `declared (${claim.reason}) and \\`${name}\\` rendered in ${rendered.length} subject(s) ` +\n      `— ${preview(rendered)} — and did not change. The edit did not take: wrong file, a ` +\n      'dead branch, a rule something else overrides, or a stale build.' +\n      caveat,\n  };\n}\n\nfunction unclaimedBecause(change: Change): string {\n  const named = change.component ?? '(no component resolved; grouped by shape alone)';\n  const settle =\n    change.settles.length === 0\n      ? 'nothing it can settle on its own'\n      : `settles ${change.settles.length} of them`;\n\n  return (\n    `${named} moved and no claim covers it — ${change.subjects.length} subject(s), ` +\n    `${change.pixels} pixel(s), ${settle}` +\n    (change.cause ? '' : '; it was displaced rather than edited')\n  );\n}\n\nfunction worst(\n  outcomes: readonly ClaimOutcome[],\n  unclaimed: readonly UnclaimedChange[],\n  clustering: Clustering,\n): RunAdjudication['verdict'] {\n  if (outcomes.some((outcome) => outcome.verdict === 'undelivered')) return 'unmet';\n  if (unclaimed.length > 0 || clustering.ungrouped.length > 0) return 'review';\n  if (outcomes.some((outcome) => outcome.verdict !== 'delivered')) return 'review';\n  return 'clean';\n}\n\n/**\n * The adjudication as the thing an agent reads before deciding what to do next.\n *\n * Ordered by what it should act on, not by what the run computed first:\n * undelivered claims lead, because an agent triaging collateral from an edit that\n * never happened is an agent about to make its second mistake.\n */\nexport function describeAdjudication(result: RunAdjudication): string {\n  const counts = tally(result);\n  const lines: string[] = [headline(result, counts)];\n\n  const order: readonly ClaimVerdict[] = ['undelivered', 'unobservable', 'overreached', 'delivered'];\n  for (const verdict of order) {\n    for (const outcome of result.claims.filter((claim) => claim.verdict === verdict)) {\n      lines.push('', `  [${outcome.verdict}] ${outcome.claim.root}`, `      ${outcome.because}`);\n      for (const change of outcome.changes) {\n        if (change.file !== undefined) lines.push(`      ${change.file}`);\n      }\n    }\n  }\n\n  for (const entry of result.unclaimed) {\n    lines.push('', `  [unclaimed] ${entry.change.component ?? entry.change.fingerprint}`);\n    lines.push(`      ${entry.because}`);\n    if (entry.change.file !== undefined) lines.push(`      ${entry.change.file}`);\n    if (entry.change.settles.length > 0) {\n      lines.push(`      variance accept --shape ${entry.change.fingerprint}`);\n    }\n  }\n\n  if (result.ungrouped.length > 0) {\n    lines.push(\n      '',\n      `  [ungrouped] ${result.ungrouped.length} changed subject(s) carry no shape, so no claim ` +\n        'could be checked against them: ' +\n        preview(result.ungrouped),\n    );\n  }\n\n  if (result.blind.length > 0) {\n    lines.push(\n      '',\n      `  [not observed] ${result.blind.length} subject(s) were not looked at, so every line ` +\n        'above is bounded by what this run saw: ' +\n        preview(result.blind.map((entry) => entry.subject)),\n    );\n  }\n\n  return lines.join('\\n');\n}\n\nfunction headline(result: RunAdjudication, counts: Record<ClaimVerdict, number>): string {\n  const claims =\n    `${result.claims.length} claim(s): ${counts.delivered} delivered, ` +\n    `${counts.undelivered} undelivered, ${counts.overreached} over-reaching, ` +\n    `${counts.unobservable} unchecked.`;\n\n  const lead =\n    result.verdict === 'unmet'\n      ? 'An edit you declared did not take. Fix that before reading anything else.'\n      : result.verdict === 'review'\n        ? 'Every declared edit landed; something you did not declare also moved.'\n        : 'Every declared edit landed, and nothing else moved.';\n\n  return `${lead}\\n${claims} ${result.unclaimed.length} unclaimed change(s).`;\n}\n\nfunction tally(result: RunAdjudication): Record<ClaimVerdict, number> {\n  const counts: Record<ClaimVerdict, number> = {\n    delivered: 0,\n    overreached: 0,\n    undelivered: 0,\n    unobservable: 0,\n  };\n  for (const outcome of result.claims) counts[outcome.verdict] += 1;\n  return counts;\n}\n\n/** The first few, because a reader wants examples and not a manifest. */\nfunction preview(items: readonly string[]): string {\n  return items.length <= 4\n    ? items.join(', ')\n    : `${items.slice(0, 4).join(', ')}, and ${items.length - 4} more`;\n}\n"]}

package/dist/presentation-record.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What a presentation reading contributes to a regression report.
+ *
+ * Beside `format.ts` rather than inside it for the reason `finding-record.ts` is:
+ * the record types a report carries are one shape each, and a file holding every
+ * shape at once is read by nobody looking for one of them.
+ */
+import type { Digest } from '@variance-authority/core';
+/** How one relationship condition changed between comparable presentation readings. */
+export type PresentationEffectTransition = 'introduced' | 'resolved' | 'persisted';
+/** The finding-local measurement retained on one side of a presentation effect. */
+export interface PresentationEffectEvidence {
+    /** Finding id in the corresponding presentation report or hierarchy reading. */
+    readonly finding: string;
+    readonly measurements: Readonly<Record<string, number | string>>;
+}
+/** One relationship consequence attributable to the difference between two readings. */
+export interface PresentationEffectRecord {
+    readonly rule: string;
+    readonly transition: PresentationEffectTransition;
+    readonly owner: string;
+    readonly nodes: readonly string[];
+    readonly pattern?: string;
+    readonly contract?: string;
+    readonly before?: PresentationEffectEvidence;
+    readonly after?: PresentationEffectEvidence;
+}
+/** Information-volume evidence kept beside relationship effects. */
+export interface PresentationInformationRecord {
+    readonly contentPreserved: boolean;
+    readonly characters: {
+        readonly before: number;
+        readonly after: number;
+        readonly delta: number;
+    };
+    readonly elements: {
+        readonly before: number;
+        readonly after: number;
+        readonly delta: number;
+    };
+    readonly repeatedObjects: {
+        readonly before: number;
+        readonly after: number;
+        readonly delta: number;
+    };
+}
+/**
+ * Presentation evidence carried by a general regression report.
+ *
+ * `incomparable` has no effects: inventing a transition from one reading would
+ * turn absence into evidence. Comparable readings always carry `effects`, where
+ * an empty array means the presentation consequence was measured and unchanged.
+ */
+export type PresentationSignalRecord = {
+    readonly verdict: 'incomparable';
+    readonly because: string;
+    readonly before?: Digest;
+    readonly after?: Digest;
+} | {
+    readonly verdict: 'unchanged' | 'changed';
+    readonly before: Digest;
+    readonly after: Digest;
+    readonly information: PresentationInformationRecord;
+    readonly effects: readonly PresentationEffectRecord[];
+};
+//# sourceMappingURL=presentation-record.d.ts.map

package/dist/presentation-record.js

@@ -0,0 +1,9 @@
+/**
+ * What a presentation reading contributes to a regression report.
+ *
+ * Beside `format.ts` rather than inside it for the reason `finding-record.ts` is:
+ * the record types a report carries are one shape each, and a file holding every
+ * shape at once is read by nobody looking for one of them.
+ */
+export {};
+//# sourceMappingURL=presentation-record.js.map

package/dist/presentation-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentation-record.js","sourceRoot":"","sources":["../src/presentation-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What a presentation reading contributes to a regression report.\n *\n * Beside `format.ts` rather than inside it for the reason `finding-record.ts` is:\n * the record types a report carries are one shape each, and a file holding every\n * shape at once is read by nobody looking for one of them.\n */\n\nimport type { Digest } from '@variance-authority/core';\n\n/** How one relationship condition changed between comparable presentation readings. */\nexport type PresentationEffectTransition = 'introduced' | 'resolved' | 'persisted';\n\n/** The finding-local measurement retained on one side of a presentation effect. */\nexport interface PresentationEffectEvidence {\n  /** Finding id in the corresponding presentation report or hierarchy reading. */\n  readonly finding: string;\n  readonly measurements: Readonly<Record<string, number | string>>;\n}\n\n/** One relationship consequence attributable to the difference between two readings. */\nexport interface PresentationEffectRecord {\n  readonly rule: string;\n  readonly transition: PresentationEffectTransition;\n  readonly owner: string;\n  readonly nodes: readonly string[];\n  readonly pattern?: string;\n  readonly contract?: string;\n  readonly before?: PresentationEffectEvidence;\n  readonly after?: PresentationEffectEvidence;\n}\n\n/** Information-volume evidence kept beside relationship effects. */\nexport interface PresentationInformationRecord {\n  readonly contentPreserved: boolean;\n  readonly characters: { readonly before: number; readonly after: number; readonly delta: number };\n  readonly elements: { readonly before: number; readonly after: number; readonly delta: number };\n  readonly repeatedObjects: { readonly before: number; readonly after: number; readonly delta: number };\n}\n\n/**\n * Presentation evidence carried by a general regression report.\n *\n * `incomparable` has no effects: inventing a transition from one reading would\n * turn absence into evidence. Comparable readings always carry `effects`, where\n * an empty array means the presentation consequence was measured and unchanged.\n */\nexport type PresentationSignalRecord =\n  | {\n      readonly verdict: 'incomparable';\n      readonly because: string;\n      readonly before?: Digest;\n      readonly after?: Digest;\n    }\n  | {\n      readonly verdict: 'unchanged' | 'changed';\n      readonly before: Digest;\n      readonly after: Digest;\n      readonly information: PresentationInformationRecord;\n      readonly effects: readonly PresentationEffectRecord[];\n    };\n\n"]}