@variance-authority/tribunal 0.1.0

package/dist/review-types.d.ts

@@ -0,0 +1,414 @@
+import type { AccessibilitySnapshot, RenderIdentity } from '@variance-authority/core';
+import type { FindingRecord, IgnoreLedger, NotObserved, ObservationRecord, ReachHole, ReachedComponent, RegionRecord, RunReport, SensitivityLedger, SubjectReach, VariationRecord } from '@variance-authority/report';
+import type { TribunalBindings } from './bindings.js';
+/**
+ * What a review store takes and what it answers with — and nothing that runs.
+ *
+ * The vocabulary rather than the implementation, apart from it because three
+ * other module graphs need the words without the machinery: `worker-input.ts`
+ * types the request bodies it validates against these, `ui/client.ts` types its
+ * responses against them, and the React surface renders them. None of those
+ * should have to name a D1 binding to say what a `BuildSummary` is.
+ *
+ * The arguments that produced these shapes are on the shapes, because that is
+ * where somebody about to change one will look. Why the store *behaves* as it
+ * does is in [`review.ts`](./review.ts).
+ */
+export interface ReviewOptions extends TribunalBindings {
+    readonly project: string;
+    /** Injected so tests can pin every `at`. Defaults to the wall clock. */
+    readonly now?: () => Date;
+}
+/** One image the run kept, as it arrives. */
+export interface CandidateImage {
+    /** Base64 PNG — the same encoding a `Raster` carries, for the same reason. */
+    readonly bytes: string;
+}
+/**
+ * What a run produced for one subject, over and above the report's record of it.
+ *
+ * `after` is the candidate and is the only one that can be promoted, which is why
+ * it alone carries the sidecar fields. `before` and `diff` exist to be looked at.
+ */
+export interface SubjectImages {
+    readonly after?: CandidateImage & {
+        readonly documentDigest: string;
+        readonly width: number;
+        readonly height: number;
+        readonly missingFonts: readonly string[];
+        readonly accessibility?: AccessibilitySnapshot;
+    };
+    /**
+     * The baseline this run compared against, with its own dimensions when they
+     * could be read.
+     *
+     * Optional, and absent means *not measured* — never *the same size as the
+     * candidate*. That assumption is the thing this field exists to stop: a
+     * baseline drawn to the candidate's box is a width change resampled out of
+     * existence, on the one screen where somebody decides whether it is allowed.
+     */
+    readonly before?: CandidateImage & {
+        readonly width?: number;
+        readonly height?: number;
+    };
+    readonly diff?: CandidateImage;
+}
+export interface BuildIngest {
+    /** The operator's own id for the run — a CI job number, a workflow run id. */
+    readonly build: string;
+    readonly commit: string;
+    readonly branch?: string;
+    readonly report: RunReport;
+    /** Keyed by subject. A subject with no entry is recorded with no images. */
+    readonly images?: Readonly<Record<string, SubjectImages>>;
+}
+import type { TribunalChangelog, TribunalChangelogQuery } from './changelog.js';
+export type Decision = 'approved' | 'rejected';
+export interface DecisionRecord {
+    readonly decision: Decision;
+    readonly by: string;
+    readonly note?: string;
+    readonly at: string;
+}
+export interface BuildSummary {
+    readonly project: string;
+    readonly build: string;
+    readonly commit: string;
+    readonly branch?: string;
+    readonly intent?: string;
+    readonly at: string;
+    readonly identity: RenderIdentity;
+    readonly retention: 'durable' | 'ephemeral';
+    /** One entry per verdict the report used, including the ones with no subjects. */
+    readonly verdicts: Readonly<Record<ObservationRecord['verdict'], number>>;
+    readonly decided: number;
+    /** Subjects whose verdict needs review and that nobody has decided yet. */
+    readonly pending: number;
+    readonly coverage: Coverage;
+}
+/**
+ * What the run said about the subjects it did not observe.
+ *
+ * `stated: false` is the whole reason this is a shape rather than two numbers. A
+ * summary that showed `failed: 0` for a report that never carried the list would
+ * be asserting coverage on the authority of a writer that declined to claim any.
+ */
+export interface Coverage {
+    readonly stated: boolean;
+    readonly failed: number;
+    readonly excluded: number;
+    /** Subjects the run proved this change cannot reach, so never rendered. */
+    readonly unreached: number;
+}
+export interface SubjectView {
+    readonly subject: string;
+    readonly verdict: ObservationRecord['verdict'];
+    readonly because: string;
+    readonly changedPixels: number;
+    readonly regions: readonly RegionRecord[];
+    readonly truncated?: {
+        readonly regions: number;
+        readonly pixels: number;
+    };
+    readonly missingFonts?: readonly string[];
+    readonly findings?: readonly FindingRecord[];
+    readonly signals?: ObservationRecord['signals'];
+    /**
+     * What the operator's ignores took out of this comparison, as the run wrote it.
+     *
+     * Carried per subject even though the build also carries a ledger, because the
+     * two answer different questions. The ledger says a rule absorbed 647 pixels
+     * somewhere; this says it absorbed them *here*. A settled list built from the
+     * ledger alone can only say a declaration decided this subject, which is the
+     * sentence a reviewer already read in the verdict.
+     */
+    readonly ignored?: ObservationRecord['ignored'];
+    /** The sensitivity that decided this subject, when one did. */
+    readonly relaxed?: ObservationRecord['relaxed'];
+    /**
+     * Which components moved here per their hashes, and in which bands.
+     *
+     * The half of the record {@link SubjectView.regions} cannot carry. A region is
+     * named from where its box landed, so an edit that reflowed its neighbours
+     * arrives as one blob attributed to the document root; these entries compared
+     * digests and never saw a pixel, so they still hold the component and the
+     * sense. Absent means the baseline carried no hashes — never that nothing
+     * moved.
+     */
+    readonly moved?: ObservationRecord['moved'];
+    /** Which images this build kept. Absent means the run did not save one. */
+    readonly has: {
+        readonly before: boolean;
+        readonly after: boolean;
+        readonly diff: boolean;
+    };
+    /**
+     * The candidate's dimensions, when it kept one.
+     *
+     * Carried so a viewer can place region rectangles over the image without
+     * measuring it in the browser first. Region coordinates are in the raster's own
+     * pixel space; a viewer that scaled them by a measured `naturalWidth` would draw
+     * the boxes in the right place only after the image had loaded, and in the wrong
+     * place for one frame before that.
+     */
+    readonly size?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * The baseline's own dimensions, when the run measured them.
+     *
+     * Separate from {@link SubjectView.size} rather than folded into it, because
+     * the two being different is a finding. A viewer that had only one pair would
+     * have to draw both layers to it, and a capture that grew by 40 pixels of
+     * width would read as identical everywhere except a hairline at the edge.
+     */
+    readonly baseline?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** `true` when the candidate carries the sidecar an approval would promote. */
+    readonly approvable: boolean;
+    readonly decision: DecisionRecord | null;
+}
+/**
+ * A build, and the docket a reviewer reads.
+ *
+ * `causes` is the ordering the incumbent comparison gets backwards. Ranked by
+ * area, a component that only *reflowed* outranks the component that was edited —
+ * measured at 6× on one edit — so the docket is grouped by the components the
+ * semantic tier named as causes, and collateral is counted rather than listed.
+ * One token change across 300 subjects is one review item with a count, never 300
+ * lines.
+ */
+export interface BuildDetail extends BuildSummary {
+    readonly subjects: readonly SubjectView[];
+    readonly notObserved: readonly NotObserved[];
+    readonly causes: readonly Cause[];
+    /**
+     * What the run read about its own subjects — the section with no baseline in it.
+     *
+     * Beside `causes` and not among them, because these are not changes and must
+     * never be counted as any: a variation is a difference somebody meant. It is
+     * here because it answers the question a docket cannot. A subject added behind
+     * a flag is `new`, its diff is empty, and what the flag *does* is visible only
+     * by opening two pictures side by side — which is the review nobody performs.
+     * The run already compared the pair, so the answer is carried rather than
+     * looked for.
+     *
+     * Empty when the report declared none. `VariationRecord` unchanged from the
+     * report's, because a store that reshaped it would be a second vocabulary for
+     * one fact.
+     */
+    readonly variations: readonly VariationRecord[];
+    /**
+     * What the commit reaches, and per subject whether it reaches that one.
+     *
+     * `null` when the run carried no diff — no ref to read against, or no file
+     * graph to walk — which is different from a diff that reached nothing and is
+     * shown as different.
+     *
+     * The four states a reviewer actually reads are not stored anywhere. They are
+     * this crossed against the verdicts already in `subjects`, and two of them are
+     * questions no comparison can pose on its own: a subject the commit reaches
+     * that did not move, and a subject that moved with nothing in the commit
+     * reaching it.
+     */
+    readonly reach: ReachView | null;
+    /**
+     * What the config declared, and what each declaration did in this run.
+     *
+     * The audit surface, carried across the boundary rather than left in a CI log.
+     * A mask that outlived its cause is only ever found by comparing runs — *this
+     * rule absorbed nothing again* — and a review service that dropped the ledger
+     * could show the question but never the answer.
+     */
+    readonly declarations: Declarations;
+    /**
+     * Who draws what, over the whole suite.
+     *
+     * `null` when the report carried no composition — a raster-only run has no
+     * boundaries to join. Empty is never written and would say something else
+     * entirely: that the run read its subjects and found no component in them.
+     */
+    readonly composition: readonly Placement[] | null;
+    /**
+     * What the run concluded about each thing that moved, in component order.
+     *
+     * The census above is the graph; this is the reading of it. A review page can
+     * derive neither: the run had the diff, the source index that maps a component
+     * to the file declaring it, the props digest each rendering was grouped under,
+     * and the subjects where the same component with the same props held still.
+     * None of those cross the wire, and a page that tried to re-derive the answer
+     * from `composition` and `reach` alone would be guessing at the one question a
+     * reviewer opens a change to ask.
+     *
+     * Empty when the store holds none, which includes a build ingested before this
+     * was carried. So it is read as *no attribution is on record*, and nothing
+     * downstream may turn it into *the run examined this and found no cause*.
+     */
+    readonly movements: readonly MovementView[];
+}
+/**
+ * Why one component moved in one subject, as the run decided it.
+ *
+ * `MovementRecord` from the report, minus `alsoIn` — which is the subjects of
+ * every sibling row for the same component, and a stored copy of it is a second
+ * answer able to disagree with the first.
+ *
+ * The pair is the key. A component moves for its own reason in each subject it
+ * moved in: the same `Button` is `edited` on the page whose file the diff names
+ * and `upstream` on the one where a changed parent hands it different props.
+ */
+export interface MovementView {
+    readonly subject: string;
+    readonly component: string;
+    readonly cause: 'edited' | 'token' | 'upstream' | 'contradicted' | 'unexplained';
+    /** One sentence, naming the evidence rather than the category. */
+    readonly because: string;
+    /** Empty means *not known* — a name-only comparison — never *no band*. */
+    readonly bands: readonly string[];
+    /** Subjects where the same component, with the same props, held still. */
+    readonly held: readonly string[];
+    /**
+     * Renders of this component with the same props, other than this one, that the
+     * run read — the pool `held` was drawn from.
+     *
+     * Absent is *the run never said*, from a build ingested before this was
+     * carried, and it is the reason `held: []` cannot be drawn as a finding on its
+     * own: without the denominator, *nothing to compare against* and *compared in
+     * four renders and moved in all four* are the same empty list.
+     */
+    readonly compared?: number;
+    /** The file the diff named, on the `edited` rung. */
+    readonly file?: string;
+    /** The custom properties that took a new value, on the `token` rung. */
+    readonly tokens?: readonly string[];
+    /** The edited component that reaches this one, on the `upstream` rung. */
+    readonly upstream?: string;
+    /** Components between `upstream` and this one, outermost first. */
+    readonly through?: readonly string[];
+    /** On an unexplained movement: whether the subject was already proven unstable. */
+    readonly standing?: 'flake' | 'suspect';
+}
+/**
+ * The two ledgers as this store holds them.
+ *
+ * `null` is *the report carried none*, and it is deliberately one state rather
+ * than two. On this format a config with no ignores and a writer that never kept
+ * a ledger produce the same absence, so a store that offered two answers would
+ * be inventing the difference. What it must not do is answer with an empty
+ * ledger, which would report an unaudited build as one that was audited and
+ * found clean.
+ */
+export interface Declarations {
+    readonly ignores: IgnoreLedger | null;
+    readonly sensitivities: SensitivityLedger | null;
+}
+/**
+ * Where one component sits in the suite, as the run's census recorded it.
+ *
+ * The other direction from {@link ReachView}, and the page needs both. Reach
+ * climbs: from a file the diff named, through its importers, to the components
+ * an edit could have arrived at. It can therefore never name anything a changed
+ * file *draws* — `ProductCard` renders `Card`, `Card` renders `CardFooter`, and
+ * an upward walk arrives at none of them. That is why a build page could count
+ * the components no rung held and could not say why any of them moved.
+ *
+ * Nothing here is measured for the tribunal. It is `composition.components` from
+ * the report, narrowed to the three edges a sentence needs.
+ */
+export interface Placement {
+    readonly component: string;
+    /** Subjects holding at least one boundary of it, in plan order. */
+    readonly subjects: readonly string[];
+    /** Components that enclose it somewhere in the suite, sorted. */
+    readonly within: readonly string[];
+    /**
+     * Components that mounted it somewhere, sorted.
+     *
+     * Empty on a production build, where React keeps no `_debugOwner` — and empty
+     * is **not** *nothing mounted it*. The report's own field carries the same
+     * ambiguity and the store does not resolve it, because resolving it here would
+     * be a claim about a build this service never saw.
+     */
+    readonly createdBy: readonly string[];
+    /** Components it encloses somewhere, sorted. */
+    readonly renders: readonly string[];
+}
+/**
+ * The reach section as the page reads it.
+ *
+ * `subjects` absent is the run saying it had a diff and could not attribute it,
+ * with `whole` carrying the reason. Empty would say the commit was understood and
+ * reaches none of them, and a page that drew the second when it held the first
+ * would let somebody merge on a refusal.
+ */
+export interface ReachView {
+    readonly against: string;
+    readonly changed: readonly string[];
+    readonly components: readonly ReachedComponent[];
+    readonly subjects?: Readonly<Record<string, SubjectReach>>;
+    readonly whole?: string;
+    readonly unscanned?: readonly string[];
+    readonly opaque?: readonly ReachHole[];
+}
+export interface Cause {
+    readonly component: string;
+    readonly file?: string;
+    readonly subjects: readonly string[];
+    readonly pixels: number;
+    /** Regions in the same builds that no component claimed as a cause. */
+    readonly collateralPixels: number;
+}
+export interface SweepReport {
+    /** Builds removed. */
+    readonly builds: number;
+    /** Subject rows removed with them. */
+    readonly subjects: number;
+    /** Stored images removed with them. */
+    readonly objects: number;
+    /**
+     * Decisions those builds carried, which are **kept**, not removed.
+     *
+     * Named for what happened to them, because every other number here is a
+     * removal and an operator reading `decisions: 4` beside them concludes four
+     * approvals were deleted — the one thing this store promises never happens
+     * ([ADR-0021](../../../docs/context/adr/0021-approval-promotes-an-image-that-already-exists.md)).
+     * The count is worth reporting: it is how much attribution outlived the build
+     * that proposed it, and a sweep that returned zero here forever would be a
+     * retention policy quietly disagreeing with the trigger on the table.
+     */
+    readonly decisionsKept: number;
+}
+export interface ReviewStore {
+    ingest(build: BuildIngest): Promise<void>;
+    builds(limit?: number): Promise<readonly BuildSummary[]>;
+    build(id: string): Promise<BuildDetail | null>;
+    image(build: string, subject: string, kind: 'before' | 'after' | 'diff'): Promise<ArrayBuffer | null>;
+    decide(input: {
+        readonly build: string;
+        readonly subject: string;
+        readonly decision: Decision;
+        readonly by: string;
+        readonly note?: string;
+    }): Promise<DecisionRecord>;
+    /**
+     * Why the baselines are what they are — every approval, grouped by what changed.
+     *
+     * Deliberately not derived from `builds`: those expire, and a baseline's
+     * explanation has to outlive the build that proposed it by as long as the
+     * baseline lasts. See [`changelog.ts`](./changelog.ts).
+     */
+    changelog(query?: TribunalChangelogQuery): Promise<TribunalChangelog>;
+    /**
+     * Remove builds older than `keepDays`, and everything that hangs off them.
+     *
+     * `decisions` and `changelog` are not among them, and both carry a permanence
+     * trigger saying so: a promoted baseline whose approval was swept is a change
+     * nobody can attribute to anyone, and one whose changelog entry was swept is a
+     * baseline nobody can account for.
+     */
+    sweep(keepDays: number): Promise<SweepReport>;
+}
+//# sourceMappingURL=review-types.d.ts.map

package/dist/review-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=review-types.js.map

package/dist/review-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-types.js","sourceRoot":"","sources":["../src/review-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { AccessibilitySnapshot, RenderIdentity } from '@variance-authority/core';\nimport type {\n  FindingRecord,\n  IgnoreLedger,\n  NotObserved,\n  ObservationRecord,\n  ReachHole,\n  ReachedComponent,\n  RegionRecord,\n  RunReport,\n  SensitivityLedger,\n  SubjectReach,\n  VariationRecord,\n} from '@variance-authority/report';\nimport type { TribunalBindings } from './bindings.js';\n\n/**\n * What a review store takes and what it answers with — and nothing that runs.\n *\n * The vocabulary rather than the implementation, apart from it because three\n * other module graphs need the words without the machinery: `worker-input.ts`\n * types the request bodies it validates against these, `ui/client.ts` types its\n * responses against them, and the React surface renders them. None of those\n * should have to name a D1 binding to say what a `BuildSummary` is.\n *\n * The arguments that produced these shapes are on the shapes, because that is\n * where somebody about to change one will look. Why the store *behaves* as it\n * does is in [`review.ts`](./review.ts).\n */\n\nexport interface ReviewOptions extends TribunalBindings {\n  readonly project: string;\n  /** Injected so tests can pin every `at`. Defaults to the wall clock. */\n  readonly now?: () => Date;\n}\n\n/** One image the run kept, as it arrives. */\nexport interface CandidateImage {\n  /** Base64 PNG — the same encoding a `Raster` carries, for the same reason. */\n  readonly bytes: string;\n}\n\n/**\n * What a run produced for one subject, over and above the report's record of it.\n *\n * `after` is the candidate and is the only one that can be promoted, which is why\n * it alone carries the sidecar fields. `before` and `diff` exist to be looked at.\n */\nexport interface SubjectImages {\n  readonly after?: CandidateImage & {\n    readonly documentDigest: string;\n    readonly width: number;\n    readonly height: number;\n    readonly missingFonts: readonly string[];\n    readonly accessibility?: AccessibilitySnapshot;\n  };\n  /**\n   * The baseline this run compared against, with its own dimensions when they\n   * could be read.\n   *\n   * Optional, and absent means *not measured* — never *the same size as the\n   * candidate*. That assumption is the thing this field exists to stop: a\n   * baseline drawn to the candidate's box is a width change resampled out of\n   * existence, on the one screen where somebody decides whether it is allowed.\n   */\n  readonly before?: CandidateImage & {\n    readonly width?: number;\n    readonly height?: number;\n  };\n  readonly diff?: CandidateImage;\n}\n\nexport interface BuildIngest {\n  /** The operator's own id for the run — a CI job number, a workflow run id. */\n  readonly build: string;\n  readonly commit: string;\n  readonly branch?: string;\n  readonly report: RunReport;\n  /** Keyed by subject. A subject with no entry is recorded with no images. */\n  readonly images?: Readonly<Record<string, SubjectImages>>;\n}\n\nimport type { TribunalChangelog, TribunalChangelogQuery } from './changelog.js';\n\nexport type Decision = 'approved' | 'rejected';\n\nexport interface DecisionRecord {\n  readonly decision: Decision;\n  readonly by: string;\n  readonly note?: string;\n  readonly at: string;\n}\n\nexport interface BuildSummary {\n  readonly project: string;\n  readonly build: string;\n  readonly commit: string;\n  readonly branch?: string;\n  readonly intent?: string;\n  readonly at: string;\n  readonly identity: RenderIdentity;\n  readonly retention: 'durable' | 'ephemeral';\n  /** One entry per verdict the report used, including the ones with no subjects. */\n  readonly verdicts: Readonly<Record<ObservationRecord['verdict'], number>>;\n  readonly decided: number;\n  /** Subjects whose verdict needs review and that nobody has decided yet. */\n  readonly pending: number;\n  readonly coverage: Coverage;\n}\n\n/**\n * What the run said about the subjects it did not observe.\n *\n * `stated: false` is the whole reason this is a shape rather than two numbers. A\n * summary that showed `failed: 0` for a report that never carried the list would\n * be asserting coverage on the authority of a writer that declined to claim any.\n */\nexport interface Coverage {\n  readonly stated: boolean;\n  readonly failed: number;\n  readonly excluded: number;\n  /** Subjects the run proved this change cannot reach, so never rendered. */\n  readonly unreached: number;\n}\n\nexport interface SubjectView {\n  readonly subject: string;\n  readonly verdict: ObservationRecord['verdict'];\n  readonly because: string;\n  readonly changedPixels: number;\n  readonly regions: readonly RegionRecord[];\n  readonly truncated?: { readonly regions: number; readonly pixels: number };\n  readonly missingFonts?: readonly string[];\n  readonly findings?: readonly FindingRecord[];\n  readonly signals?: ObservationRecord['signals'];\n  /**\n   * What the operator's ignores took out of this comparison, as the run wrote it.\n   *\n   * Carried per subject even though the build also carries a ledger, because the\n   * two answer different questions. The ledger says a rule absorbed 647 pixels\n   * somewhere; this says it absorbed them *here*. A settled list built from the\n   * ledger alone can only say a declaration decided this subject, which is the\n   * sentence a reviewer already read in the verdict.\n   */\n  readonly ignored?: ObservationRecord['ignored'];\n  /** The sensitivity that decided this subject, when one did. */\n  readonly relaxed?: ObservationRecord['relaxed'];\n  /**\n   * Which components moved here per their hashes, and in which bands.\n   *\n   * The half of the record {@link SubjectView.regions} cannot carry. A region is\n   * named from where its box landed, so an edit that reflowed its neighbours\n   * arrives as one blob attributed to the document root; these entries compared\n   * digests and never saw a pixel, so they still hold the component and the\n   * sense. Absent means the baseline carried no hashes — never that nothing\n   * moved.\n   */\n  readonly moved?: ObservationRecord['moved'];\n  /** Which images this build kept. Absent means the run did not save one. */\n  readonly has: { readonly before: boolean; readonly after: boolean; readonly diff: boolean };\n  /**\n   * The candidate's dimensions, when it kept one.\n   *\n   * Carried so a viewer can place region rectangles over the image without\n   * measuring it in the browser first. Region coordinates are in the raster's own\n   * pixel space; a viewer that scaled them by a measured `naturalWidth` would draw\n   * the boxes in the right place only after the image had loaded, and in the wrong\n   * place for one frame before that.\n   */\n  readonly size?: { readonly width: number; readonly height: number };\n  /**\n   * The baseline's own dimensions, when the run measured them.\n   *\n   * Separate from {@link SubjectView.size} rather than folded into it, because\n   * the two being different is a finding. A viewer that had only one pair would\n   * have to draw both layers to it, and a capture that grew by 40 pixels of\n   * width would read as identical everywhere except a hairline at the edge.\n   */\n  readonly baseline?: { readonly width: number; readonly height: number };\n  /** `true` when the candidate carries the sidecar an approval would promote. */\n  readonly approvable: boolean;\n  readonly decision: DecisionRecord | null;\n}\n\n/**\n * A build, and the docket a reviewer reads.\n *\n * `causes` is the ordering the incumbent comparison gets backwards. Ranked by\n * area, a component that only *reflowed* outranks the component that was edited —\n * measured at 6× on one edit — so the docket is grouped by the components the\n * semantic tier named as causes, and collateral is counted rather than listed.\n * One token change across 300 subjects is one review item with a count, never 300\n * lines.\n */\nexport interface BuildDetail extends BuildSummary {\n  readonly subjects: readonly SubjectView[];\n  readonly notObserved: readonly NotObserved[];\n  readonly causes: readonly Cause[];\n  /**\n   * What the run read about its own subjects — the section with no baseline in it.\n   *\n   * Beside `causes` and not among them, because these are not changes and must\n   * never be counted as any: a variation is a difference somebody meant. It is\n   * here because it answers the question a docket cannot. A subject added behind\n   * a flag is `new`, its diff is empty, and what the flag *does* is visible only\n   * by opening two pictures side by side — which is the review nobody performs.\n   * The run already compared the pair, so the answer is carried rather than\n   * looked for.\n   *\n   * Empty when the report declared none. `VariationRecord` unchanged from the\n   * report's, because a store that reshaped it would be a second vocabulary for\n   * one fact.\n   */\n  readonly variations: readonly VariationRecord[];\n\n  /**\n   * What the commit reaches, and per subject whether it reaches that one.\n   *\n   * `null` when the run carried no diff — no ref to read against, or no file\n   * graph to walk — which is different from a diff that reached nothing and is\n   * shown as different.\n   *\n   * The four states a reviewer actually reads are not stored anywhere. They are\n   * this crossed against the verdicts already in `subjects`, and two of them are\n   * questions no comparison can pose on its own: a subject the commit reaches\n   * that did not move, and a subject that moved with nothing in the commit\n   * reaching it.\n   */\n  readonly reach: ReachView | null;\n\n  /**\n   * What the config declared, and what each declaration did in this run.\n   *\n   * The audit surface, carried across the boundary rather than left in a CI log.\n   * A mask that outlived its cause is only ever found by comparing runs — *this\n   * rule absorbed nothing again* — and a review service that dropped the ledger\n   * could show the question but never the answer.\n   */\n  readonly declarations: Declarations;\n\n  /**\n   * Who draws what, over the whole suite.\n   *\n   * `null` when the report carried no composition — a raster-only run has no\n   * boundaries to join. Empty is never written and would say something else\n   * entirely: that the run read its subjects and found no component in them.\n   */\n  readonly composition: readonly Placement[] | null;\n\n  /**\n   * What the run concluded about each thing that moved, in component order.\n   *\n   * The census above is the graph; this is the reading of it. A review page can\n   * derive neither: the run had the diff, the source index that maps a component\n   * to the file declaring it, the props digest each rendering was grouped under,\n   * and the subjects where the same component with the same props held still.\n   * None of those cross the wire, and a page that tried to re-derive the answer\n   * from `composition` and `reach` alone would be guessing at the one question a\n   * reviewer opens a change to ask.\n   *\n   * Empty when the store holds none, which includes a build ingested before this\n   * was carried. So it is read as *no attribution is on record*, and nothing\n   * downstream may turn it into *the run examined this and found no cause*.\n   */\n  readonly movements: readonly MovementView[];\n}\n\n/**\n * Why one component moved in one subject, as the run decided it.\n *\n * `MovementRecord` from the report, minus `alsoIn` — which is the subjects of\n * every sibling row for the same component, and a stored copy of it is a second\n * answer able to disagree with the first.\n *\n * The pair is the key. A component moves for its own reason in each subject it\n * moved in: the same `Button` is `edited` on the page whose file the diff names\n * and `upstream` on the one where a changed parent hands it different props.\n */\nexport interface MovementView {\n  readonly subject: string;\n  readonly component: string;\n  readonly cause: 'edited' | 'token' | 'upstream' | 'contradicted' | 'unexplained';\n  /** One sentence, naming the evidence rather than the category. */\n  readonly because: string;\n  /** Empty means *not known* — a name-only comparison — never *no band*. */\n  readonly bands: readonly string[];\n  /** Subjects where the same component, with the same props, held still. */\n  readonly held: readonly string[];\n\n  /**\n   * Renders of this component with the same props, other than this one, that the\n   * run read — the pool `held` was drawn from.\n   *\n   * Absent is *the run never said*, from a build ingested before this was\n   * carried, and it is the reason `held: []` cannot be drawn as a finding on its\n   * own: without the denominator, *nothing to compare against* and *compared in\n   * four renders and moved in all four* are the same empty list.\n   */\n  readonly compared?: number;\n\n  /** The file the diff named, on the `edited` rung. */\n  readonly file?: string;\n  /** The custom properties that took a new value, on the `token` rung. */\n  readonly tokens?: readonly string[];\n  /** The edited component that reaches this one, on the `upstream` rung. */\n  readonly upstream?: string;\n  /** Components between `upstream` and this one, outermost first. */\n  readonly through?: readonly string[];\n  /** On an unexplained movement: whether the subject was already proven unstable. */\n  readonly standing?: 'flake' | 'suspect';\n}\n\n/**\n * The two ledgers as this store holds them.\n *\n * `null` is *the report carried none*, and it is deliberately one state rather\n * than two. On this format a config with no ignores and a writer that never kept\n * a ledger produce the same absence, so a store that offered two answers would\n * be inventing the difference. What it must not do is answer with an empty\n * ledger, which would report an unaudited build as one that was audited and\n * found clean.\n */\nexport interface Declarations {\n  readonly ignores: IgnoreLedger | null;\n  readonly sensitivities: SensitivityLedger | null;\n}\n\n/**\n * Where one component sits in the suite, as the run's census recorded it.\n *\n * The other direction from {@link ReachView}, and the page needs both. Reach\n * climbs: from a file the diff named, through its importers, to the components\n * an edit could have arrived at. It can therefore never name anything a changed\n * file *draws* — `ProductCard` renders `Card`, `Card` renders `CardFooter`, and\n * an upward walk arrives at none of them. That is why a build page could count\n * the components no rung held and could not say why any of them moved.\n *\n * Nothing here is measured for the tribunal. It is `composition.components` from\n * the report, narrowed to the three edges a sentence needs.\n */\nexport interface Placement {\n  readonly component: string;\n  /** Subjects holding at least one boundary of it, in plan order. */\n  readonly subjects: readonly string[];\n  /** Components that enclose it somewhere in the suite, sorted. */\n  readonly within: readonly string[];\n  /**\n   * Components that mounted it somewhere, sorted.\n   *\n   * Empty on a production build, where React keeps no `_debugOwner` — and empty\n   * is **not** *nothing mounted it*. The report's own field carries the same\n   * ambiguity and the store does not resolve it, because resolving it here would\n   * be a claim about a build this service never saw.\n   */\n  readonly createdBy: readonly string[];\n  /** Components it encloses somewhere, sorted. */\n  readonly renders: readonly string[];\n}\n\n/**\n * The reach section as the page reads it.\n *\n * `subjects` absent is the run saying it had a diff and could not attribute it,\n * with `whole` carrying the reason. Empty would say the commit was understood and\n * reaches none of them, and a page that drew the second when it held the first\n * would let somebody merge on a refusal.\n */\nexport interface ReachView {\n  readonly against: string;\n  readonly changed: readonly string[];\n  readonly components: readonly ReachedComponent[];\n  readonly subjects?: Readonly<Record<string, SubjectReach>>;\n  readonly whole?: string;\n  readonly unscanned?: readonly string[];\n  readonly opaque?: readonly ReachHole[];\n}\n\nexport interface Cause {\n  readonly component: string;\n  readonly file?: string;\n  readonly subjects: readonly string[];\n  readonly pixels: number;\n  /** Regions in the same builds that no component claimed as a cause. */\n  readonly collateralPixels: number;\n}\n\nexport interface SweepReport {\n  /** Builds removed. */\n  readonly builds: number;\n  /** Subject rows removed with them. */\n  readonly subjects: number;\n  /** Stored images removed with them. */\n  readonly objects: number;\n  /**\n   * Decisions those builds carried, which are **kept**, not removed.\n   *\n   * Named for what happened to them, because every other number here is a\n   * removal and an operator reading `decisions: 4` beside them concludes four\n   * approvals were deleted — the one thing this store promises never happens\n   * ([ADR-0021](../../../docs/context/adr/0021-approval-promotes-an-image-that-already-exists.md)).\n   * The count is worth reporting: it is how much attribution outlived the build\n   * that proposed it, and a sweep that returned zero here forever would be a\n   * retention policy quietly disagreeing with the trigger on the table.\n   */\n  readonly decisionsKept: number;\n}\n\nexport interface ReviewStore {\n  ingest(build: BuildIngest): Promise<void>;\n  builds(limit?: number): Promise<readonly BuildSummary[]>;\n  build(id: string): Promise<BuildDetail | null>;\n  image(build: string, subject: string, kind: 'before' | 'after' | 'diff'): Promise<ArrayBuffer | null>;\n  decide(input: {\n    readonly build: string;\n    readonly subject: string;\n    readonly decision: Decision;\n    readonly by: string;\n    readonly note?: string;\n  }): Promise<DecisionRecord>;\n  /**\n   * Why the baselines are what they are — every approval, grouped by what changed.\n   *\n   * Deliberately not derived from `builds`: those expire, and a baseline's\n   * explanation has to outlive the build that proposed it by as long as the\n   * baseline lasts. See [`changelog.ts`](./changelog.ts).\n   */\n  changelog(query?: TribunalChangelogQuery): Promise<TribunalChangelog>;\n  /**\n   * Remove builds older than `keepDays`, and everything that hangs off them.\n   *\n   * `decisions` and `changelog` are not among them, and both carry a permanence\n   * trigger saying so: a promoted baseline whose approval was swept is a change\n   * nobody can attribute to anyone, and one whose changelog entry was swept is a\n   * baseline nobody can account for.\n   */\n  sweep(keepDays: number): Promise<SweepReport>;\n}\n"]}

package/dist/review-write.d.ts

@@ -0,0 +1,35 @@
+import { type RasterStore } from '@variance-authority/raster';
+import { type D1Like, type R2Like } from './bindings.js';
+import { type Row } from './review-rows.js';
+import type { SubjectImages } from './review-types.js';
+/**
+ * The two writes that reach the bucket: keeping what a run uploaded, and
+ * promoting one of those objects to a baseline.
+ *
+ * Apart from [`review.ts`](./review.ts) because these are the operations with a
+ * consequence outside this package. `store` decides what a build keeps;
+ * `promote` is what `variance accept` means when it is a click, and it is the
+ * reason approving cannot be a flag on a row.
+ *
+ * The *ordering* around them is argued at the call sites rather than here —
+ * objects before rows on the way in, promotion before the decision on the way out
+ * — because it is the caller that can get it wrong.
+ */
+export interface StoredKeys {
+    before?: string;
+    after?: string;
+    diff?: string;
+}
+export declare function store(bucket: R2Like, project: string, build: string, subject: string, images: SubjectImages | undefined): Promise<StoredKeys>;
+/**
+ * Approving, as the promotion of an image that already exists.
+ *
+ * Every field of the baseline comes from what the run uploaded: the bytes from
+ * the bucket, the digest and dimensions from the build row, the identity from the
+ * build. Nothing is rendered, nothing is measured, and nothing is defaulted — a
+ * missing candidate is refused, because the only way to fill the gap would be to
+ * paint one, and an approval whose image nobody reviewed is worse than no
+ * approval at all.
+ */
+export declare function promote(bucket: R2Like, baselines: RasterStore, db: D1Like, project: string, build: string, subject: string, row: Row): Promise<void>;
+//# sourceMappingURL=review-write.d.ts.map

package/dist/review-write.js

@@ -0,0 +1,86 @@
+import { RasterStoreError, identityFrom, sidecarFrom, } from '@variance-authority/raster';
+import { base64Of, bytesOf } from './bindings.js';
+import { ReviewError, number, optionalText, text } from './review-rows.js';
+export async function store(bucket, project, build, subject, images) {
+    if (images === undefined)
+        return {};
+    const keys = {};
+    const prefix = `${project}/builds/${encodeURIComponent(build)}/${encodeURIComponent(subject)}`;
+    for (const kind of ['before', 'after', 'diff']) {
+        const image = images[kind];
+        if (image === undefined)
+            continue;
+        const key = `${prefix}.${kind}.png`;
+        await bucket.put(key, bytesOf(image.bytes));
+        keys[kind] = key;
+    }
+    return keys;
+}
+/**
+ * Approving, as the promotion of an image that already exists.
+ *
+ * Every field of the baseline comes from what the run uploaded: the bytes from
+ * the bucket, the digest and dimensions from the build row, the identity from the
+ * build. Nothing is rendered, nothing is measured, and nothing is defaulted — a
+ * missing candidate is refused, because the only way to fill the gap would be to
+ * paint one, and an approval whose image nobody reviewed is worse than no
+ * approval at all.
+ */
+export async function promote(bucket, baselines, db, project, build, subject, row) {
+    const key = optionalText(row, 'after_key', 'a build subject');
+    const digest = optionalText(row, 'candidate_document_digest', 'a build subject');
+    if (key === undefined || digest === undefined) {
+        throw new ReviewError(`subject "${subject}" of build "${build}" cannot be approved: the run did not upload a ` +
+            'candidate for it, and a baseline is an image plus the document it was painted from. ' +
+            'Approving would mean rendering one now, which is recording rather than promoting');
+    }
+    const buildRow = await db
+        .prepare('SELECT identity FROM builds WHERE project = ? AND build = ?')
+        .bind(project, build)
+        .first();
+    const identity = identityFrom(JSON.parse(text(buildRow ?? {}, 'identity', 'a build')));
+    if (identity === null) {
+        throw new ReviewError(`build "${build}" does not carry a renderer identity that can be read back, so there is no ` +
+            'machine to file the promoted baseline under. A baseline with no identity is one every ' +
+            'other machine would compare against and none of them should');
+    }
+    const object = await bucket.get(key);
+    if (object === null) {
+        throw new RasterStoreError(`the candidate image for ${subject} of build "${build}" is recorded at \`${key}\` and the ` +
+            'bucket has no such object. The approval is refused rather than promoting a baseline ' +
+            'this deployment cannot produce the bytes for');
+    }
+    const raster = {
+        documentDigest: digest,
+        identity,
+        width: number(row, 'candidate_width', 'a build subject'),
+        height: number(row, 'candidate_height', 'a build subject'),
+        bytes: base64Of(await object.arrayBuffer()),
+        missingFonts: strings(optionalText(row, 'candidate_missing_fonts', 'a build subject')),
+        ...accessibilityField(optionalText(row, 'candidate_accessibility', 'a build subject'), identity),
+    };
+    await baselines.put({ subject }, raster);
+}
+function accessibilityField(json, identity) {
+    if (json === undefined)
+        return {};
+    const parsed = sidecarFrom({
+        documentDigest: 'candidate',
+        identity,
+        width: 0,
+        height: 0,
+        missingFonts: [],
+        accessibility: JSON.parse(json),
+    });
+    if (parsed?.accessibility === undefined) {
+        throw new ReviewError('the candidate browser accessibility snapshot is malformed');
+    }
+    return { accessibility: parsed.accessibility };
+}
+function strings(json) {
+    if (json === undefined)
+        return [];
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === 'string') : [];
+}
+//# sourceMappingURL=review-write.js.map

package/dist/review-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-write.js","sourceRoot":"","sources":["../src/review-write.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Raster } from '@variance-authority/core';\nimport {\n  RasterStoreError,\n  identityFrom,\n  sidecarFrom,\n  type RasterStore,\n} from '@variance-authority/raster';\nimport { base64Of, bytesOf, type D1Like, type R2Like } from './bindings.js';\nimport { ReviewError, number, optionalText, text, type Row } from './review-rows.js';\nimport type { SubjectImages } from './review-types.js';\n\n/**\n * The two writes that reach the bucket: keeping what a run uploaded, and\n * promoting one of those objects to a baseline.\n *\n * Apart from [`review.ts`](./review.ts) because these are the operations with a\n * consequence outside this package. `store` decides what a build keeps;\n * `promote` is what `variance accept` means when it is a click, and it is the\n * reason approving cannot be a flag on a row.\n *\n * The *ordering* around them is argued at the call sites rather than here —\n * objects before rows on the way in, promotion before the decision on the way out\n * — because it is the caller that can get it wrong.\n */\n\nexport interface StoredKeys {\n  before?: string;\n  after?: string;\n  diff?: string;\n}\n\nexport async function store(\n  bucket: R2Like,\n  project: string,\n  build: string,\n  subject: string,\n  images: SubjectImages | undefined,\n): Promise<StoredKeys> {\n  if (images === undefined) return {};\n\n  const keys: StoredKeys = {};\n  const prefix = `${project}/builds/${encodeURIComponent(build)}/${encodeURIComponent(subject)}`;\n\n  for (const kind of ['before', 'after', 'diff'] as const) {\n    const image = images[kind];\n    if (image === undefined) continue;\n    const key = `${prefix}.${kind}.png`;\n    await bucket.put(key, bytesOf(image.bytes));\n    keys[kind] = key;\n  }\n  return keys;\n}\n\n/**\n * Approving, as the promotion of an image that already exists.\n *\n * Every field of the baseline comes from what the run uploaded: the bytes from\n * the bucket, the digest and dimensions from the build row, the identity from the\n * build. Nothing is rendered, nothing is measured, and nothing is defaulted — a\n * missing candidate is refused, because the only way to fill the gap would be to\n * paint one, and an approval whose image nobody reviewed is worse than no\n * approval at all.\n */\nexport async function promote(\n  bucket: R2Like,\n  baselines: RasterStore,\n  db: D1Like,\n  project: string,\n  build: string,\n  subject: string,\n  row: Row,\n): Promise<void> {\n  const key = optionalText(row, 'after_key', 'a build subject');\n  const digest = optionalText(row, 'candidate_document_digest', 'a build subject');\n\n  if (key === undefined || digest === undefined) {\n    throw new ReviewError(\n      `subject \"${subject}\" of build \"${build}\" cannot be approved: the run did not upload a ` +\n        'candidate for it, and a baseline is an image plus the document it was painted from. ' +\n        'Approving would mean rendering one now, which is recording rather than promoting',\n    );\n  }\n\n  const buildRow = await db\n    .prepare('SELECT identity FROM builds WHERE project = ? AND build = ?')\n    .bind(project, build)\n    .first<Row>();\n  const identity = identityFrom(JSON.parse(text(buildRow ?? {}, 'identity', 'a build')) as unknown);\n\n  if (identity === null) {\n    throw new ReviewError(\n      `build \"${build}\" does not carry a renderer identity that can be read back, so there is no ` +\n        'machine to file the promoted baseline under. A baseline with no identity is one every ' +\n        'other machine would compare against and none of them should',\n    );\n  }\n\n  const object = await bucket.get(key);\n  if (object === null) {\n    throw new RasterStoreError(\n      `the candidate image for ${subject} of build \"${build}\" is recorded at \\`${key}\\` and the ` +\n        'bucket has no such object. The approval is refused rather than promoting a baseline ' +\n        'this deployment cannot produce the bytes for',\n    );\n  }\n\n  const raster: Raster = {\n    documentDigest: digest as Raster['documentDigest'],\n    identity,\n    width: number(row, 'candidate_width', 'a build subject'),\n    height: number(row, 'candidate_height', 'a build subject'),\n    bytes: base64Of(await object.arrayBuffer()),\n    missingFonts: strings(optionalText(row, 'candidate_missing_fonts', 'a build subject')),\n    ...accessibilityField(optionalText(row, 'candidate_accessibility', 'a build subject'), identity),\n  };\n\n  await baselines.put({ subject }, raster);\n}\n\nfunction accessibilityField(\n  json: string | undefined,\n  identity: Raster['identity'],\n): Pick<Raster, 'accessibility'> {\n  if (json === undefined) return {};\n  const parsed = sidecarFrom({\n    documentDigest: 'candidate',\n    identity,\n    width: 0,\n    height: 0,\n    missingFonts: [],\n    accessibility: JSON.parse(json) as unknown,\n  });\n  if (parsed?.accessibility === undefined) {\n    throw new ReviewError('the candidate browser accessibility snapshot is malformed');\n  }\n  return { accessibility: parsed.accessibility };\n}\n\nfunction strings(json: string | undefined): readonly string[] {\n  if (json === undefined) return [];\n  const parsed: unknown = JSON.parse(json);\n  return Array.isArray(parsed) ? parsed.filter((entry): entry is string => typeof entry === 'string') : [];\n}\n"]}

package/dist/review.d.ts

@@ -0,0 +1,53 @@
+import type { ReviewOptions, ReviewStore } from './review-types.js';
+/**
+ * The half [ADR-0019](../../../docs/context/adr/0019-one-comment-that-leads-with-causes.md) put out of
+ * scope: somewhere a change can be looked at, and somewhere a decision about it
+ * survives.
+ *
+ * ## What a build is
+ *
+ * A `RunReport` and the images that run kept. Nothing here invents a format — the
+ * report is what `variance run` already writes, and the images are what it
+ * already saved beside it. A CI job posts one thing it already has.
+ *
+ * ## Approval promotes; it never records
+ *
+ * `variance accept` "never produces an image — it promotes one the run already
+ * produced", and that rule is the reason this file cannot be a simple flag on a
+ * row. A baseline is not pixels: it is pixels **plus** the document digest they
+ * were painted from and the identity that painted them, which is the sidecar the
+ * cheap `describe` path answers from without moving a byte. So a build carries
+ * that metadata per subject, and approving writes it through the same
+ * `RasterStore` a run reads.
+ *
+ * A subject whose candidate was never uploaded therefore **cannot be approved**.
+ * The alternative is a surface that re-renders in order to say yes, and a surface
+ * that can render can record something nobody looked at.
+ *
+ * ## Two things that are never collapsed
+ *
+ * **A coverage list that was never stated is not an empty one.** `RunReport`
+ * distinguishes them because a run that planned 300 subjects, failed on 50 and
+ * found 250 unchanged produces a report in which every observation is clean.
+ * Ingest stores which of the two arrived, and every summary below carries it, so
+ * "nothing to review" cannot be printed on the authority of a writer that never
+ * said what it skipped.
+ *
+ * **Findings that were never collected are not an absence of defects.** Same
+ * distinction, same reason: `[]` means this render was inspected and was clean,
+ * and `undefined` means nothing looked.
+ *
+ * ## What is next door
+ *
+ * The shapes are in [`review-types.ts`](./review-types.ts) so that the Worker and
+ * the React surface can name them without a D1 binding; the two writes that reach
+ * the bucket are in [`review-write.ts`](./review-write.ts); writing a report in is
+ * [`review-ingest.ts`](./review-ingest.ts) and reading a build back out is
+ * [`review-read.ts`](./review-read.ts). What is left here is the store
+ * itself — the order the writes happen in, and what each operation refuses.
+ */
+export type { BuildDetail, BuildIngest, BuildSummary, CandidateImage, Cause, Coverage, Decision, DecisionRecord, ReviewOptions, ReviewStore, SubjectImages, SubjectView, SweepReport, } from './review-types.js';
+export { ReviewError } from './review-rows.js';
+export type { ChangelogChange, ChangelogRow, TribunalChangelog, TribunalChangelogQuery, } from './changelog.js';
+export declare function createReviewStore(options: ReviewOptions): ReviewStore;
+//# sourceMappingURL=review.d.ts.map