@variance-authority/tribunal 0.1.0

package/dist/__fixtures__/review.js

@@ -0,0 +1,145 @@
+/**
+ * One report, and the build a run would have posted from it.
+ *
+ * Shared by the files that test [`review.ts`](../review.ts) rather than copied
+ * into each, because the point of every one of them is what the store does with
+ * *this* report — the same three subjects, the same 86 cause pixels against 511
+ * collateral. A second copy that drifted by one pixel would turn an ordering
+ * claim into two claims about two reports.
+ */
+import { PNG } from 'pngjs';
+import { createReviewStore } from '../review.js';
+import { createMemoryR2, createSqliteD1 } from '../testing.js';
+export const IDENTITY = {
+    renderer: 'playwright-chromium',
+    engine: 'chromium@131.0.0',
+    platform: 'linux/x64',
+    deviceScaleFactor: 1,
+    fonts: [],
+};
+export const CANDIDATE = image([0, 0, 0]);
+export const PREVIOUS = image([255, 255, 255]);
+export function image(colour) {
+    const png = new PNG({ width: 2, height: 2 });
+    for (let index = 0; index < png.data.length; index += 4) {
+        png.data[index] = colour[0];
+        png.data[index + 1] = colour[1];
+        png.data[index + 2] = colour[2];
+        png.data[index + 3] = 255;
+    }
+    return PNG.sync.write(png).toString('base64');
+}
+/**
+ * A report as `variance run` writes one: two subjects changed by one edit, where
+ * the reflowed container carries six times the pixels of the component that was
+ * actually edited.
+ */
+export function report(overrides = {}) {
+    return {
+        runVersion: 1,
+        at: '2026-06-01T10:00:00.000Z',
+        identity: IDENTITY,
+        retention: 'durable',
+        intent: 'tighten the toolbar',
+        observations: [
+            {
+                subject: 'story:todos--populated',
+                verdict: 'changed',
+                because: 'the rendered image differs from the baseline',
+                changedPixels: 1530,
+                regions: [
+                    {
+                        x: 0, y: 0, width: 10, height: 10, pixels: 86,
+                        component: 'Toggle', file: 'src/ds/components.tsx', cause: true,
+                    },
+                    {
+                        x: 0, y: 20, width: 40, height: 20, pixels: 511,
+                        component: 'Stack', file: 'src/ds/components.tsx', cause: false,
+                    },
+                ],
+                findings: [],
+            },
+            {
+                subject: 'story:toolbar',
+                verdict: 'unchanged',
+                because: 'the document digests to what the baseline was painted from',
+                changedPixels: 0,
+                regions: [],
+            },
+        ],
+        notObserved: [
+            { subject: 'story:modal', kind: 'failed', because: 'the renderer crashed on navigation' },
+            { subject: 'story:legacy', kind: 'excluded', because: 'excluded by config' },
+        ],
+        ...overrides,
+    };
+}
+export function ingest(overrides = {}) {
+    return {
+        build: 'ci-1001',
+        commit: 'abc123',
+        branch: 'feat/toolbar',
+        report: report(),
+        images: {
+            'story:todos--populated': {
+                after: {
+                    bytes: CANDIDATE,
+                    documentDigest: 'deadbeef',
+                    width: 2,
+                    height: 2,
+                    missingFonts: [],
+                },
+                before: { bytes: PREVIOUS },
+                diff: { bytes: PREVIOUS },
+            },
+        },
+        ...overrides,
+    };
+}
+/**
+ * The three states a variation arrives in, in one report.
+ *
+ * Together they are the distinction the table keeps a nullable column for: an arm
+ * that was measured and differs, one that was measured and reaches nothing, and
+ * one nothing could measure because the parent it named is not in this run.
+ */
+export const VARIATIONS = [
+    {
+        subject: 'story:todos--populated-dark',
+        parent: 'story:todos--populated',
+        identical: false,
+        bands: ['token'],
+        components: ['Toggle'],
+        digest: 'v1:d2eebe6199661536',
+        how: 'named',
+        because: '`story:todos--populated-dark` differs from `story:todos--populated` in token',
+    },
+    {
+        subject: 'story:todos--sale',
+        parent: 'story:todos--populated',
+        identical: true,
+        bands: [],
+        digest: 'v1:ce4228e7c7dcb46f',
+        how: 'declared',
+        because: '`story:todos--sale` renders identically to `story:todos--populated`',
+    },
+    {
+        subject: 'story:todos--orphan',
+        because: 'the parent this subject declares was not observed in this run',
+    },
+];
+/** The hour a build in these fixtures was posted at. */
+export const POSTED = '2026-06-01T12:00:00.000Z';
+/**
+ * A store over an empty database and an empty bucket.
+ *
+ * `now` is a getter rather than a date because the tests that reach retention
+ * move the clock after the build was written, which is the only way to have a
+ * build that is old without waiting for it to become one.
+ */
+export async function openReview(now = () => new Date(POSTED)) {
+    const db = await createSqliteD1();
+    const bucket = createMemoryR2();
+    return { db, bucket, review: createReviewStore({ db, bucket, project: 'todomvc', now }) };
+}
+//# sourceMappingURL=review.js.map

package/dist/__fixtures__/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../src/__fixtures__/review.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One report, and the build a run would have posted from it.\n *\n * Shared by the files that test [`review.ts`](../review.ts) rather than copied\n * into each, because the point of every one of them is what the store does with\n * *this* report — the same three subjects, the same 86 cause pixels against 511\n * collateral. A second copy that drifted by one pixel would turn an ordering\n * claim into two claims about two reports.\n */\n\nimport { PNG } from 'pngjs';\nimport type { Digest, RenderIdentity } from '@variance-authority/core';\nimport type { RunReport, VariationRecord } from '@variance-authority/report';\nimport { createReviewStore, type BuildIngest, type ReviewStore } from '../review.js';\nimport { createMemoryR2, createSqliteD1, type MemoryR2, type SqliteD1 } from '../testing.js';\n\nexport const IDENTITY: RenderIdentity = {\n  renderer: 'playwright-chromium',\n  engine: 'chromium@131.0.0',\n  platform: 'linux/x64',\n  deviceScaleFactor: 1,\n  fonts: [],\n};\n\nexport const CANDIDATE = image([0, 0, 0]);\nexport const PREVIOUS = image([255, 255, 255]);\n\nexport function image(colour: readonly [number, number, number]): string {\n  const png = new PNG({ width: 2, height: 2 });\n  for (let index = 0; index < png.data.length; index += 4) {\n    png.data[index] = colour[0];\n    png.data[index + 1] = colour[1];\n    png.data[index + 2] = colour[2];\n    png.data[index + 3] = 255;\n  }\n  return PNG.sync.write(png).toString('base64');\n}\n\n/**\n * A report as `variance run` writes one: two subjects changed by one edit, where\n * the reflowed container carries six times the pixels of the component that was\n * actually edited.\n */\nexport function report(overrides: Partial<RunReport> = {}): RunReport {\n  return {\n    runVersion: 1,\n    at: '2026-06-01T10:00:00.000Z',\n    identity: IDENTITY,\n    retention: 'durable',\n    intent: 'tighten the toolbar',\n    observations: [\n      {\n        subject: 'story:todos--populated',\n        verdict: 'changed',\n        because: 'the rendered image differs from the baseline',\n        changedPixels: 1530,\n        regions: [\n          {\n            x: 0, y: 0, width: 10, height: 10, pixels: 86,\n            component: 'Toggle', file: 'src/ds/components.tsx', cause: true,\n          },\n          {\n            x: 0, y: 20, width: 40, height: 20, pixels: 511,\n            component: 'Stack', file: 'src/ds/components.tsx', cause: false,\n          },\n        ],\n        findings: [],\n      },\n      {\n        subject: 'story:toolbar',\n        verdict: 'unchanged',\n        because: 'the document digests to what the baseline was painted from',\n        changedPixels: 0,\n        regions: [],\n      },\n    ],\n    notObserved: [\n      { subject: 'story:modal', kind: 'failed', because: 'the renderer crashed on navigation' },\n      { subject: 'story:legacy', kind: 'excluded', because: 'excluded by config' },\n    ],\n    ...overrides,\n  };\n}\n\nexport function ingest(overrides: Partial<BuildIngest> = {}): BuildIngest {\n  return {\n    build: 'ci-1001',\n    commit: 'abc123',\n    branch: 'feat/toolbar',\n    report: report(),\n    images: {\n      'story:todos--populated': {\n        after: {\n          bytes: CANDIDATE,\n          documentDigest: 'deadbeef' as Digest,\n          width: 2,\n          height: 2,\n          missingFonts: [],\n        },\n        before: { bytes: PREVIOUS },\n        diff: { bytes: PREVIOUS },\n      },\n    },\n    ...overrides,\n  };\n}\n\n/**\n * The three states a variation arrives in, in one report.\n *\n * Together they are the distinction the table keeps a nullable column for: an arm\n * that was measured and differs, one that was measured and reaches nothing, and\n * one nothing could measure because the parent it named is not in this run.\n */\nexport const VARIATIONS: readonly VariationRecord[] = [\n  {\n    subject: 'story:todos--populated-dark',\n    parent: 'story:todos--populated',\n    identical: false,\n    bands: ['token'],\n    components: ['Toggle'],\n    digest: 'v1:d2eebe6199661536',\n    how: 'named',\n    because: '`story:todos--populated-dark` differs from `story:todos--populated` in token',\n  },\n  {\n    subject: 'story:todos--sale',\n    parent: 'story:todos--populated',\n    identical: true,\n    bands: [],\n    digest: 'v1:ce4228e7c7dcb46f',\n    how: 'declared',\n    because: '`story:todos--sale` renders identically to `story:todos--populated`',\n  },\n  {\n    subject: 'story:todos--orphan',\n    because: 'the parent this subject declares was not observed in this run',\n  },\n];\n\n/** The hour a build in these fixtures was posted at. */\nexport const POSTED = '2026-06-01T12:00:00.000Z';\n\n/**\n * A store over an empty database and an empty bucket.\n *\n * `now` is a getter rather than a date because the tests that reach retention\n * move the clock after the build was written, which is the only way to have a\n * build that is old without waiting for it to become one.\n */\nexport async function openReview(\n  now: () => Date = () => new Date(POSTED),\n): Promise<{ db: SqliteD1; bucket: MemoryR2; review: ReviewStore }> {\n  const db = await createSqliteD1();\n  const bucket = createMemoryR2();\n  return { db, bucket, review: createReviewStore({ db, bucket, project: 'todomvc', now }) };\n}\n"]}

package/dist/bindings.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The platform, named in full, in one file, by us.
+ *
+ * Every other module here takes a `D1Like` and an `R2Like` and never a
+ * Cloudflare type. That is not portability theatre — it is the same rule
+ * [ADR-0013](../../../docs/context/adr/0013-packages-are-named-for-their-requirements.md)
+ * applies everywhere else in this repository: a package requires what it says it
+ * requires. Depending on `@cloudflare/workers-types` would put a global
+ * `DOM`-shaped ambient declaration into the build of a package the CLI links
+ * against, and it would make the store untestable without a Workers runtime.
+ *
+ * What is declared below is exactly the surface used, and nothing else. It is
+ * structurally satisfied by the real `D1Database` and `R2Bucket` — an operator's
+ * Worker passes `env.DB` and `env.BUCKET` straight in and TypeScript accepts it,
+ * because a wider interface is assignable to a narrower one.
+ *
+ * **The cost is stated rather than hidden.** These are hand-written shapes, so a
+ * breaking change to D1 or R2 is a runtime failure here rather than a compile
+ * error. The mitigation is that the surface is tiny: five methods on D1, three on
+ * R2, all of them years old and all of them exercised by the tests through a
+ * `node:sqlite`-backed double that runs the same SQL a real D1 would.
+ */
+/** A value D1 accepts as a bound parameter. D1 has no `bigint` and no `Buffer`. */
+export type D1Value = string | number | null | ArrayBuffer;
+export interface D1PreparedLike {
+    bind(...values: readonly D1Value[]): D1PreparedLike;
+    first<Row>(): Promise<Row | null>;
+    all<Row>(): Promise<{
+        readonly results: readonly Row[];
+    }>;
+    run(): Promise<unknown>;
+}
+/**
+ * A SQL database that runs one statement or a batch of them.
+ *
+ * D1 is SQLite, so this is satisfied by the platform binding and by
+ * `node:sqlite` through a thin wrapper, which is what lets the same store back
+ * a Worker and a file on a machine somebody owns.
+ */
+export interface D1Like {
+    prepare(sql: string): D1PreparedLike;
+    /**
+     * Several statements, committed together or not at all.
+     *
+     * The whole reason the history backend can satisfy its atomicity requirement
+     * on a platform with no `BEGIN`. D1 wraps a batch in an implicit transaction
+     * and rolls the whole thing back if any statement fails, which is what
+     * [spec 0002](../../../docs/specs/0002-history-store.md) needs: rows without
+     * their run leave a change with no denominator, and a run without its rows is
+     * a quiet run that was not quiet.
+     *
+     * **Unverified against the platform.** See the known limits in
+     * [ADR-0023](../../../docs/context/adr/0023-a-service-is-named-for-what-it-is.md) — the
+     * double used in tests is genuinely transactional, and the claim that D1 is
+     * has never been measured here.
+     */
+    batch(statements: readonly D1PreparedLike[]): Promise<unknown>;
+}
+export interface R2ObjectLike {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * An object store addressed by key, holding image bytes and nothing else.
+ *
+ * Four methods, because that is all the store uses: read, exists, write, remove.
+ * A bucket is never listed and never scanned — every key this package reads is
+ * one a row already named.
+ */
+export interface R2Like {
+    /** `null` means the bucket answered and there is no such object. */
+    get(key: string): Promise<R2ObjectLike | null>;
+    /**
+     * Existence without the bytes.
+     *
+     * Here for one reason: `describe` must agree with `find` about whether a
+     * baseline exists. A sidecar row whose object is gone would be a description to
+     * the cheap lookup and a corrupted pair to the full one, and the verdict would
+     * then depend on which question the caller happened to ask. The directory store
+     * spends a `stat` for exactly this; this spends a HEAD.
+     */
+    head(key: string): Promise<unknown | null>;
+    put(key: string, value: ArrayBuffer): Promise<unknown>;
+    delete(keys: string | readonly string[]): Promise<unknown>;
+}
+/**
+ * The two bindings, together, because nothing here works with one of them.
+ *
+ * A deployment with a database and no bucket can record that a subject changed
+ * and cannot show anyone what it looks like; a deployment with a bucket and no
+ * database has images nobody can address. Taking them as a pair means the
+ * missing one is a wiring error at construction rather than a `TypeError` on the
+ * first request that happens to need it.
+ */
+export interface TribunalBindings {
+    readonly db: D1Like;
+    readonly bucket: R2Like;
+}
+/**
+ * Base64 in, `ArrayBuffer` out — the one conversion this package does twice.
+ *
+ * A `Raster` carries its bytes as base64 precisely so it survives JSON hops, and
+ * R2 stores bytes. `atob` is the conversion both Workers and Node 22 have; going
+ * through `Buffer` would tie this file to Node and would be the only thing in the
+ * package that could not run on the platform it is named for.
+ */
+export declare function bytesOf(base64: string): ArrayBuffer;
+/** The other direction. Chunked, because `String.fromCharCode` has an argument limit. */
+export declare function base64Of(buffer: ArrayBuffer): string;
+/**
+ * Refuse a deployment whose bindings never arrived.
+ *
+ * The operator who gets this wrong wrote a `wrangler.jsonc` — spelled the
+ * binding `D1` instead of `DB`, or added the R2 bucket to production and not to
+ * a preview environment — and the compiler is not standing there. Without this,
+ * `undefined` is carried all the way to the first statement that touches it and
+ * surfaces as `Cannot read properties of undefined (reading 'prepare')` on one
+ * request, while routes that happen not to reach the missing half keep working.
+ *
+ * `worker-entry` already turns every construction refusal into a 500 whose body
+ * is the sentence, and it already falls back for `PROJECT` and `RETENTION_DAYS`
+ * rather than letting them fail late. The two bindings are the settings most
+ * likely to be wrong and were the only ones with no sentence.
+ *
+ * Shape-checked rather than merely present, because a binding pointing at the
+ * wrong kind of resource is the same mistake one line further along, and
+ * `R2Like` and `D1Like` share no method name for the two to be confused by.
+ * Split in two because `./history` takes a database and no bucket, and one
+ * function with an optional second argument cannot tell that door from a store
+ * whose bucket is missing.
+ */
+export declare function requireD1(db: unknown): void;
+/** The other half. See {@link requireD1}. */
+export declare function requireR2(bucket: unknown): void;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.js

@@ -0,0 +1,88 @@
+/**
+ * The platform, named in full, in one file, by us.
+ *
+ * Every other module here takes a `D1Like` and an `R2Like` and never a
+ * Cloudflare type. That is not portability theatre — it is the same rule
+ * [ADR-0013](../../../docs/context/adr/0013-packages-are-named-for-their-requirements.md)
+ * applies everywhere else in this repository: a package requires what it says it
+ * requires. Depending on `@cloudflare/workers-types` would put a global
+ * `DOM`-shaped ambient declaration into the build of a package the CLI links
+ * against, and it would make the store untestable without a Workers runtime.
+ *
+ * What is declared below is exactly the surface used, and nothing else. It is
+ * structurally satisfied by the real `D1Database` and `R2Bucket` — an operator's
+ * Worker passes `env.DB` and `env.BUCKET` straight in and TypeScript accepts it,
+ * because a wider interface is assignable to a narrower one.
+ *
+ * **The cost is stated rather than hidden.** These are hand-written shapes, so a
+ * breaking change to D1 or R2 is a runtime failure here rather than a compile
+ * error. The mitigation is that the surface is tiny: five methods on D1, three on
+ * R2, all of them years old and all of them exercised by the tests through a
+ * `node:sqlite`-backed double that runs the same SQL a real D1 would.
+ */
+/**
+ * Base64 in, `ArrayBuffer` out — the one conversion this package does twice.
+ *
+ * A `Raster` carries its bytes as base64 precisely so it survives JSON hops, and
+ * R2 stores bytes. `atob` is the conversion both Workers and Node 22 have; going
+ * through `Buffer` would tie this file to Node and would be the only thing in the
+ * package that could not run on the platform it is named for.
+ */
+export function bytesOf(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes.buffer;
+}
+/** The other direction. Chunked, because `String.fromCharCode` has an argument limit. */
+export function base64Of(buffer) {
+    const bytes = new Uint8Array(buffer);
+    const chunk = 0x8000;
+    let binary = '';
+    for (let index = 0; index < bytes.length; index += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+    }
+    return btoa(binary);
+}
+/**
+ * Refuse a deployment whose bindings never arrived.
+ *
+ * The operator who gets this wrong wrote a `wrangler.jsonc` — spelled the
+ * binding `D1` instead of `DB`, or added the R2 bucket to production and not to
+ * a preview environment — and the compiler is not standing there. Without this,
+ * `undefined` is carried all the way to the first statement that touches it and
+ * surfaces as `Cannot read properties of undefined (reading 'prepare')` on one
+ * request, while routes that happen not to reach the missing half keep working.
+ *
+ * `worker-entry` already turns every construction refusal into a 500 whose body
+ * is the sentence, and it already falls back for `PROJECT` and `RETENTION_DAYS`
+ * rather than letting them fail late. The two bindings are the settings most
+ * likely to be wrong and were the only ones with no sentence.
+ *
+ * Shape-checked rather than merely present, because a binding pointing at the
+ * wrong kind of resource is the same mistake one line further along, and
+ * `R2Like` and `D1Like` share no method name for the two to be confused by.
+ * Split in two because `./history` takes a database and no bucket, and one
+ * function with an optional second argument cannot tell that door from a store
+ * whose bucket is missing.
+ */
+export function requireD1(db) {
+    if (db === null || typeof db !== 'object' || typeof db.prepare !== 'function') {
+        throw new Error('`db` is not a D1 binding. A Worker receives it as `env.DB`, declared under `d1_databases` ' +
+            'in `wrangler.jsonc` with the `binding` name matching what the entry reads; a name that ' +
+            'does not match arrives as `undefined`, and the first request to touch a row is where you ' +
+            'would otherwise hear about it');
+    }
+}
+/** The other half. See {@link requireD1}. */
+export function requireR2(bucket) {
+    if (bucket === null || typeof bucket !== 'object' || typeof bucket.get !== 'function') {
+        throw new Error('`bucket` is not an R2 binding. A Worker receives it as `env.BUCKET`, declared under ' +
+            '`r2_buckets` in `wrangler.jsonc`; declaring it for production and not for a preview ' +
+            'environment is the common shape of this, and the sidecar rows would be written without ' +
+            'the images they describe');
+    }
+}
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAkFH;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,QAAQ,CAAC,MAAmB;IAC1C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC;IACrB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC;QACzD,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAC,EAAW;IACnC,IAAI,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAQ,EAAa,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,4FAA4F;YAC1F,yFAAyF;YACzF,2FAA2F;YAC3F,+BAA+B,CAClC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,SAAS,CAAC,MAAe;IACvC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAQ,MAAiB,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAClG,MAAM,IAAI,KAAK,CACb,sFAAsF;YACpF,sFAAsF;YACtF,yFAAyF;YACzF,0BAA0B,CAC7B,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["/**\n * The platform, named in full, in one file, by us.\n *\n * Every other module here takes a `D1Like` and an `R2Like` and never a\n * Cloudflare type. That is not portability theatre — it is the same rule\n * [ADR-0013](../../../docs/context/adr/0013-packages-are-named-for-their-requirements.md)\n * applies everywhere else in this repository: a package requires what it says it\n * requires. Depending on `@cloudflare/workers-types` would put a global\n * `DOM`-shaped ambient declaration into the build of a package the CLI links\n * against, and it would make the store untestable without a Workers runtime.\n *\n * What is declared below is exactly the surface used, and nothing else. It is\n * structurally satisfied by the real `D1Database` and `R2Bucket` — an operator's\n * Worker passes `env.DB` and `env.BUCKET` straight in and TypeScript accepts it,\n * because a wider interface is assignable to a narrower one.\n *\n * **The cost is stated rather than hidden.** These are hand-written shapes, so a\n * breaking change to D1 or R2 is a runtime failure here rather than a compile\n * error. The mitigation is that the surface is tiny: five methods on D1, three on\n * R2, all of them years old and all of them exercised by the tests through a\n * `node:sqlite`-backed double that runs the same SQL a real D1 would.\n */\n\n/** A value D1 accepts as a bound parameter. D1 has no `bigint` and no `Buffer`. */\nexport type D1Value = string | number | null | ArrayBuffer;\n\nexport interface D1PreparedLike {\n  bind(...values: readonly D1Value[]): D1PreparedLike;\n  first<Row>(): Promise<Row | null>;\n  all<Row>(): Promise<{ readonly results: readonly Row[] }>;\n  run(): Promise<unknown>;\n}\n\n/**\n * A SQL database that runs one statement or a batch of them.\n *\n * D1 is SQLite, so this is satisfied by the platform binding and by\n * `node:sqlite` through a thin wrapper, which is what lets the same store back\n * a Worker and a file on a machine somebody owns.\n */\nexport interface D1Like {\n  prepare(sql: string): D1PreparedLike;\n\n  /**\n   * Several statements, committed together or not at all.\n   *\n   * The whole reason the history backend can satisfy its atomicity requirement\n   * on a platform with no `BEGIN`. D1 wraps a batch in an implicit transaction\n   * and rolls the whole thing back if any statement fails, which is what\n   * [spec 0002](../../../docs/specs/0002-history-store.md) needs: rows without\n   * their run leave a change with no denominator, and a run without its rows is\n   * a quiet run that was not quiet.\n   *\n   * **Unverified against the platform.** See the known limits in\n   * [ADR-0023](../../../docs/context/adr/0023-a-service-is-named-for-what-it-is.md) — the\n   * double used in tests is genuinely transactional, and the claim that D1 is\n   * has never been measured here.\n   */\n  batch(statements: readonly D1PreparedLike[]): Promise<unknown>;\n}\n\nexport interface R2ObjectLike {\n  arrayBuffer(): Promise<ArrayBuffer>;\n}\n\n/**\n * An object store addressed by key, holding image bytes and nothing else.\n *\n * Four methods, because that is all the store uses: read, exists, write, remove.\n * A bucket is never listed and never scanned — every key this package reads is\n * one a row already named.\n */\nexport interface R2Like {\n  /** `null` means the bucket answered and there is no such object. */\n  get(key: string): Promise<R2ObjectLike | null>;\n  /**\n   * Existence without the bytes.\n   *\n   * Here for one reason: `describe` must agree with `find` about whether a\n   * baseline exists. A sidecar row whose object is gone would be a description to\n   * the cheap lookup and a corrupted pair to the full one, and the verdict would\n   * then depend on which question the caller happened to ask. The directory store\n   * spends a `stat` for exactly this; this spends a HEAD.\n   */\n  head(key: string): Promise<unknown | null>;\n  put(key: string, value: ArrayBuffer): Promise<unknown>;\n  delete(keys: string | readonly string[]): Promise<unknown>;\n}\n\n/**\n * The two bindings, together, because nothing here works with one of them.\n *\n * A deployment with a database and no bucket can record that a subject changed\n * and cannot show anyone what it looks like; a deployment with a bucket and no\n * database has images nobody can address. Taking them as a pair means the\n * missing one is a wiring error at construction rather than a `TypeError` on the\n * first request that happens to need it.\n */\nexport interface TribunalBindings {\n  readonly db: D1Like;\n  readonly bucket: R2Like;\n}\n\n/**\n * Base64 in, `ArrayBuffer` out — the one conversion this package does twice.\n *\n * A `Raster` carries its bytes as base64 precisely so it survives JSON hops, and\n * R2 stores bytes. `atob` is the conversion both Workers and Node 22 have; going\n * through `Buffer` would tie this file to Node and would be the only thing in the\n * package that could not run on the platform it is named for.\n */\nexport function bytesOf(base64: string): ArrayBuffer {\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let index = 0; index < binary.length; index += 1) {\n    bytes[index] = binary.charCodeAt(index);\n  }\n  return bytes.buffer;\n}\n\n/** The other direction. Chunked, because `String.fromCharCode` has an argument limit. */\nexport function base64Of(buffer: ArrayBuffer): string {\n  const bytes = new Uint8Array(buffer);\n  const chunk = 0x8000;\n  let binary = '';\n  for (let index = 0; index < bytes.length; index += chunk) {\n    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));\n  }\n  return btoa(binary);\n}\n\n/**\n * Refuse a deployment whose bindings never arrived.\n *\n * The operator who gets this wrong wrote a `wrangler.jsonc` — spelled the\n * binding `D1` instead of `DB`, or added the R2 bucket to production and not to\n * a preview environment — and the compiler is not standing there. Without this,\n * `undefined` is carried all the way to the first statement that touches it and\n * surfaces as `Cannot read properties of undefined (reading 'prepare')` on one\n * request, while routes that happen not to reach the missing half keep working.\n *\n * `worker-entry` already turns every construction refusal into a 500 whose body\n * is the sentence, and it already falls back for `PROJECT` and `RETENTION_DAYS`\n * rather than letting them fail late. The two bindings are the settings most\n * likely to be wrong and were the only ones with no sentence.\n *\n * Shape-checked rather than merely present, because a binding pointing at the\n * wrong kind of resource is the same mistake one line further along, and\n * `R2Like` and `D1Like` share no method name for the two to be confused by.\n * Split in two because `./history` takes a database and no bucket, and one\n * function with an optional second argument cannot tell that door from a store\n * whose bucket is missing.\n */\nexport function requireD1(db: unknown): void {\n  if (db === null || typeof db !== 'object' || typeof (db as D1Like).prepare !== 'function') {\n    throw new Error(\n      '`db` is not a D1 binding. A Worker receives it as `env.DB`, declared under `d1_databases` ' +\n        'in `wrangler.jsonc` with the `binding` name matching what the entry reads; a name that ' +\n        'does not match arrives as `undefined`, and the first request to touch a row is where you ' +\n        'would otherwise hear about it',\n    );\n  }\n}\n\n/** The other half. See {@link requireD1}. */\nexport function requireR2(bucket: unknown): void {\n  if (bucket === null || typeof bucket !== 'object' || typeof (bucket as R2Like).get !== 'function') {\n    throw new Error(\n      '`bucket` is not an R2 binding. A Worker receives it as `env.BUCKET`, declared under ' +\n        '`r2_buckets` in `wrangler.jsonc`; declaring it for production and not for a preview ' +\n        'environment is the common shape of this, and the sidecar rows would be written without ' +\n        'the images they describe',\n    );\n  }\n}\n"]}

package/dist/changelog.d.ts

@@ -0,0 +1,132 @@
+import { type RegionRecord } from '@variance-authority/report';
+import type { D1Like } from './bindings.js';
+/**
+ * Why a baseline in this database is what it is.
+ *
+ * The other half of the same subsystem the git-LFS backend answers with a commit
+ * message. There, the baseline is a commit and the explanation goes in the
+ * message; here, the baseline is a row and the explanation goes in a row beside
+ * it. Both are read back by asking the store that holds the bytes, which is the
+ * only arrangement in which the explanation cannot drift away from the thing it
+ * explains.
+ *
+ * ## Why it copies rather than joins
+ *
+ * Everything in this table is already in `build_subjects` and `builds` at the
+ * moment it is written, and a view over those two would be shorter. It would also
+ * be empty after `sweep`: builds expire — that is what a review surface's storage
+ * budget is — and the explanation of a baseline has to outlive the build that
+ * proposed it by exactly as long as the baseline lasts, which is forever. So the
+ * regions, the commit, the intent and the reviewer are **frozen** into the row at
+ * the moment of approval, the same way a commit message is frozen into a commit.
+ *
+ * A row is written only for an **approval**. A rejection is a decision and it is
+ * recorded in `decisions`, but no baseline changed, and a changelog that carried
+ * rejections would answer *why does this baseline look like this* with entries
+ * about baselines that are not there.
+ *
+ * ## Clustered on the way out, not on the way in
+ *
+ * One row per approved subject, and the shapes are grouped when somebody reads.
+ * Approval here is per subject — a reviewer clicks through a docket rather than
+ * running one command over a report — so there is no moment at which a "batch"
+ * exists to cluster. Grouping at read time also means a shape approved across
+ * three sessions reads as one change, which is what it was.
+ */
+/** One approved subject, exactly as the build described it. */
+export interface ChangelogRow {
+    readonly build: string;
+    readonly subject: string;
+    readonly commit: string;
+    readonly intent?: string;
+    readonly by: string;
+    readonly note?: string;
+    readonly at: string;
+    /**
+     * The regions the build reported, frozen.
+     *
+     * The only measurement kept, and kept because the fingerprints inside it are
+     * what a shape *is* — the grouping is recomputed from these on every read. No
+     * aggregate sits beside them: a changed-pixel total measures displacement
+     * rather than magnitude and is bound to the machine that rendered it, and a
+     * column of them in a permanent table is an invitation to compare two numbers
+     * that were never comparable.
+     */
+    readonly regions: readonly RegionRecord[];
+}
+/** One change, as it was approved — the same unit the commit-message half uses. */
+export interface ChangelogChange {
+    readonly fingerprint: string;
+    readonly component?: string;
+    readonly file?: string;
+    /**
+     * Approved subjects this shape landed in, most recently approved first.
+     *
+     * Approval order rather than a sort, and the same order as `by` beside it, so
+     * the two lists can be read against each other: the reviewer at the top is the
+     * one who approved the subject at the top.
+     */
+    readonly subjects: readonly string[];
+    /** The builds the approvals came from, newest first. */
+    readonly builds: readonly string[];
+    /** Everyone who approved part of this shape, most recent first. */
+    readonly by: readonly string[];
+    /** The most recent approval in the group. */
+    readonly at: string;
+    readonly intent?: string;
+    readonly note?: string;
+}
+export interface TribunalChangelog {
+    readonly changes: readonly ChangelogChange[];
+    /**
+     * Approved subjects no shape could group.
+     *
+     * A run that attributed nothing — the ephemeral and raster-only paths — still
+     * approved something, and counting it is how the total stays a total. Dropping
+     * these would make a changelog that covers eleven of forty approvals look like
+     * a changelog of eleven approvals.
+     */
+    readonly ungrouped: readonly ChangelogRow[];
+}
+export interface TribunalChangelogQuery {
+    /** Substring, case-insensitive, against the component a shape was attributed to. */
+    readonly component?: string;
+    /** Exact, because a subject id is exact. */
+    readonly subject?: string;
+    /** Rows to read, newest first. Defaults to 500. */
+    readonly limit?: number;
+    /** Only approvals at or after this instant. ISO 8601. */
+    readonly since?: string;
+}
+/**
+ * Freeze the explanation of one approval.
+ *
+ * Called from `decide` after the promotion and before the decision row, in the
+ * same order and for the same reason: the promotion is the thing with a
+ * consequence, and a changelog entry for a baseline that was never written would
+ * be an explanation of nothing.
+ *
+ * Never invents a build's `commit` or `intent` — both come from the build row the
+ * approval is about, and a build that cannot be read is a refusal in `promote`
+ * long before this runs.
+ */
+export declare function recordApproval(db: D1Like, project: string, input: {
+    readonly build: string;
+    readonly subject: string;
+    readonly by: string;
+    readonly note?: string;
+    readonly at: string;
+    readonly commit: string;
+    readonly intent?: string;
+    readonly regions: string;
+}): Promise<void>;
+/**
+ * Every baseline this project has promoted, grouped by what changed.
+ *
+ * The filters narrow what is *read*, never what is explained: `--subject` selects
+ * rows and then the shapes those rows carry are grouped whole, so a shape
+ * approved in forty subjects still reports forty when you ask about one of them.
+ * Answering with a group of one would say the change was smaller than it was.
+ */
+export declare function readChangelog(db: D1Like, project: string, query?: TribunalChangelogQuery): Promise<TribunalChangelog>;
+//# sourceMappingURL=changelog.d.ts.map