@variance-authority/tribunal 0.1.0

package/dist/review.fixtures.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 type { RenderIdentity } from '@variance-authority/core';
+import type { RunReport, VariationRecord } from '@variance-authority/report';
+import { type BuildIngest, type ReviewStore } from './review.js';
+import { type MemoryR2, type SqliteD1 } from './testing.js';
+export declare const IDENTITY: RenderIdentity;
+export declare const CANDIDATE: string;
+export declare const PREVIOUS: string;
+export declare function image(colour: readonly [number, number, number]): string;
+/**
+ * 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 declare function report(overrides?: Partial<RunReport>): RunReport;
+export declare function ingest(overrides?: Partial<BuildIngest>): BuildIngest;
+/**
+ * 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 declare const VARIATIONS: readonly VariationRecord[];
+/** The hour a build in these fixtures was posted at. */
+export declare 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 declare function openReview(now?: () => Date): Promise<{
+    db: SqliteD1;
+    bucket: MemoryR2;
+    review: ReviewStore;
+}>;
+//# sourceMappingURL=review.fixtures.d.ts.map

package/dist/review.fixtures.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.fixtures.js.map

package/dist/review.fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.fixtures.js","sourceRoot":"","sources":["../src/review.fixtures.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/review.js

@@ -0,0 +1,245 @@
+import { readChangelog, recordApproval } from './changelog.js';
+import { docket, latestDecisions, summarize, toDeclarations, toNotObserved, toMovement, toPlacement, toReach, toSubjectView, toVariation, } from './review-read.js';
+import { ingestBuild } from './review-ingest.js';
+import { ReviewError, instant, number, optionalText, text } from './review-rows.js';
+import { promote } from './review-write.js';
+import { createBucketStore } from './store.js';
+export { ReviewError } from './review-rows.js';
+export function createReviewStore(options) {
+    const { db, bucket, project } = options;
+    const now = options.now ?? (() => new Date());
+    const baselines = createBucketStore(options);
+    return {
+        async ingest(build) {
+            await ingestBuild({ db, bucket, project }, build);
+        },
+        async builds(limit = 50) {
+            const listed = await db
+                .prepare('SELECT * FROM builds WHERE project = ? ORDER BY at_ms DESC, rowid DESC LIMIT ?')
+                .bind(project, limit)
+                .all();
+            const summaries = [];
+            for (const row of listed.results) {
+                summaries.push(await summarize(db, project, row));
+            }
+            return summaries;
+        },
+        async build(id) {
+            const row = await db
+                .prepare('SELECT * FROM builds WHERE project = ? AND build = ?')
+                .bind(project, id)
+                .first();
+            if (row === null)
+                return null;
+            const summary = await summarize(db, project, row);
+            const subjectRows = await db
+                .prepare('SELECT * FROM build_subjects WHERE project = ? AND build = ? ORDER BY subject')
+                .bind(project, id)
+                .all();
+            const decisions = await latestDecisions(db, project, id);
+            const skipped = await db
+                .prepare('SELECT * FROM build_not_observed WHERE project = ? AND build = ? ORDER BY subject')
+                .bind(project, id)
+                .all();
+            const variations = await db
+                .prepare('SELECT * FROM build_variations WHERE project = ? AND build = ? ORDER BY subject')
+                .bind(project, id)
+                .all();
+            const reachRow = await db
+                .prepare('SELECT * FROM build_reach WHERE project = ? AND build = ?')
+                .bind(project, id)
+                .first();
+            const census = await db
+                .prepare('SELECT * FROM build_composition WHERE project = ? AND build = ? ORDER BY component')
+                .bind(project, id)
+                .all();
+            const attributed = await db
+                .prepare(`SELECT * FROM build_movements WHERE project = ? AND build = ?
+           ORDER BY component, subject`)
+                .bind(project, id)
+                .all();
+            const reachSubjects = reachRow === null
+                ? undefined
+                : await db
+                    .prepare('SELECT * FROM build_reach_subjects WHERE project = ? AND build = ? ORDER BY subject')
+                    .bind(project, id)
+                    .all();
+            const subjects = subjectRows.results.map((subject) => toSubjectView(subject, decisions.get(text(subject, 'subject', 'a build subject')) ?? null));
+            return {
+                ...summary,
+                subjects,
+                notObserved: skipped.results.map(toNotObserved),
+                causes: docket(subjects),
+                variations: variations.results.map(toVariation),
+                reach: reachRow === null ? null : toReach(reachRow, reachSubjects?.results ?? []),
+                // No rows is `null`, not `[]`. A run that produced no semantic snapshots
+                // has no graph to join, and an empty list would say the opposite — that
+                // the suite was read and found to contain no component at all.
+                composition: census.results.length === 0 ? null : census.results.map(toPlacement),
+                movements: attributed.results.map(toMovement),
+                declarations: toDeclarations(row),
+            };
+        },
+        async image(build, subject, kind) {
+            const row = await db
+                .prepare(`SELECT before_key, after_key, diff_key FROM build_subjects
+            WHERE project = ? AND build = ? AND subject = ?`)
+                .bind(project, build, subject)
+                .first();
+            if (row === null)
+                return null;
+            const key = optionalText(row, `${kind}_key`, 'a build subject');
+            if (key === undefined)
+                return null;
+            const object = await bucket.get(key);
+            // An object a row points at and that is not there is damage, not absence —
+            // the same rule the baseline store applies. Here it costs a broken image in
+            // a page rather than a destroyed baseline, so it is reported rather than
+            // fatal, but it is still not answered as "the run kept none".
+            if (object === null) {
+                throw new ReviewError(`build "${build}" says it kept the ${kind} image for ${subject} at \`${key}\`, and the ` +
+                    'bucket has no such object. The row and the object are one artifact; one without the ' +
+                    'other is damage rather than a run that saved nothing');
+            }
+            return object.arrayBuffer();
+        },
+        async decide(input) {
+            const row = await db
+                .prepare('SELECT * FROM build_subjects WHERE project = ? AND build = ? AND subject = ?')
+                .bind(project, input.build, input.subject)
+                .first();
+            if (row === null) {
+                throw new ReviewError(`build "${input.build}" has no subject "${input.subject}". Deciding about a subject a ` +
+                    'build never reported would record an approval nothing can be promoted for');
+            }
+            const at = now().toISOString();
+            // Promotion happens *before* the decision is recorded. The other order can
+            // leave an approval on the page whose baseline was never written, and the
+            // next run would then report the same change again with the reviewer's name
+            // already against it.
+            if (input.decision === 'approved') {
+                await promote(bucket, baselines, db, project, input.build, input.subject, row);
+                // Beside the promotion, and only for one: an approval is the moment a
+                // baseline changed, and it is the last moment at which anything still
+                // knows what the change was. `build_subjects` expires; this does not.
+                await recordApproval(db, project, {
+                    build: input.build,
+                    subject: input.subject,
+                    by: input.by,
+                    at,
+                    regions: text(row, 'regions', 'a build subject'),
+                    ...(input.note !== undefined ? { note: input.note } : {}),
+                    ...(await buildContext(db, project, input.build)),
+                });
+            }
+            await db
+                .prepare(`INSERT INTO decisions (project, build, subject, decision, decided_by, note, at, at_ms)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .bind(project, input.build, input.subject, input.decision, input.by, input.note ?? null, at, instant(at, 'a decision'))
+                .run();
+            return {
+                decision: input.decision,
+                by: input.by,
+                at,
+                ...(input.note !== undefined ? { note: input.note } : {}),
+            };
+        },
+        async changelog(query) {
+            return readChangelog(db, project, query ?? {});
+        },
+        async sweep(keepDays) {
+            if (!Number.isFinite(keepDays) || keepDays < 0) {
+                throw new ReviewError(`a retention window of ${String(keepDays)} days is not a window. Pass the number of ` +
+                    'days of builds to keep; 0 keeps none');
+            }
+            const cutoff = now().getTime() - keepDays * 86_400_000;
+            const expired = await db
+                .prepare('SELECT build FROM builds WHERE project = ? AND at_ms < ?')
+                .bind(project, cutoff)
+                .all();
+            const ids = expired.results.map((row) => text(row, 'build', 'a build'));
+            if (ids.length === 0)
+                return { builds: 0, subjects: 0, objects: 0, decisionsKept: 0 };
+            let objects = 0;
+            let subjects = 0;
+            let decisionsKept = 0;
+            for (const id of ids) {
+                const rows = await db
+                    .prepare('SELECT before_key, after_key, diff_key FROM build_subjects WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .all();
+                const keys = rows.results.flatMap((row) => ['before_key', 'after_key', 'diff_key']
+                    .map((column) => optionalText(row, column, 'a build subject'))
+                    .filter((key) => key !== undefined));
+                if (keys.length > 0)
+                    await bucket.delete(keys);
+                objects += keys.length;
+                subjects += rows.results.length;
+                const counted = await db
+                    .prepare('SELECT COUNT(*) AS n FROM decisions WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .first();
+                decisionsKept += number(counted ?? {}, 'n', 'a decision count');
+                // `decisions` carries a permanence trigger and is deliberately not swept:
+                // a promoted baseline whose approval was deleted is a change nobody can
+                // attribute to anyone. What expires is what a build kept to be *looked
+                // at*, which is images and the verdicts beside them.
+                await db
+                    .prepare('DELETE FROM build_subjects WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_not_observed WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_variations WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_composition WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_movements WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_reach_subjects WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db
+                    .prepare('DELETE FROM build_reach WHERE project = ? AND build = ?')
+                    .bind(project, id)
+                    .run();
+                await db.prepare('DELETE FROM builds WHERE project = ? AND build = ?').bind(project, id).run();
+            }
+            return { builds: ids.length, subjects, objects, decisionsKept };
+        },
+    };
+}
+/**
+ * The two things a changelog entry needs from the build and cannot invent.
+ *
+ * Read at approval time rather than joined at read time, because the build row
+ * is what `sweep` removes. A build that has already gone is not a failure here —
+ * its subjects would have gone with it, so there would be nothing to approve —
+ * but the read is defended anyway, since an entry attributing a baseline to an
+ * empty commit is worse than one that says nothing.
+ */
+async function buildContext(db, project, build) {
+    const row = await db
+        .prepare('SELECT "commit", intent FROM builds WHERE project = ? AND build = ?')
+        .bind(project, build)
+        .first();
+    if (row === null) {
+        throw new ReviewError(`build "${build}" is no longer in this database, so an approval under it could not be ` +
+            'attributed to a commit. A changelog entry naming no commit explains nothing');
+    }
+    const intent = optionalText(row, 'intent', 'a build');
+    return {
+        commit: text(row, 'commit', 'a build'),
+        ...(intent !== undefined ? { intent } : {}),
+    };
+}
+//# sourceMappingURL=review.js.map

package/dist/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../src/review.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EACL,MAAM,EACN,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,UAAU,EACV,WAAW,EACX,OAAO,EACP,aAAa,EACb,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAY,MAAM,kBAAkB,CAAC;AAS9F,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiE/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQ/C,MAAM,UAAU,iBAAiB,CAAC,OAAsB;IACtD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACxC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAS,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE7C,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAK;YAChB,MAAM,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QACpD,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,EAAE;YACrB,MAAM,MAAM,GAAG,MAAM,EAAE;iBACpB,OAAO,CAAC,gFAAgF,CAAC;iBACzF,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC;iBACpB,GAAG,EAAO,CAAC;YAEd,MAAM,SAAS,GAAmB,EAAE,CAAC;YACrC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjC,SAAS,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;YACpD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,EAAE;YACZ,MAAM,GAAG,GAAG,MAAM,EAAE;iBACjB,OAAO,CAAC,sDAAsD,CAAC;iBAC/D,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,KAAK,EAAO,CAAC;YAChB,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAE9B,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;YAClD,MAAM,WAAW,GAAG,MAAM,EAAE;iBACzB,OAAO,CAAC,+EAA+E,CAAC;iBACxF,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,GAAG,EAAO,CAAC;YACd,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YACzD,MAAM,OAAO,GAAG,MAAM,EAAE;iBACrB,OAAO,CAAC,mFAAmF,CAAC;iBAC5F,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,GAAG,EAAO,CAAC;YACd,MAAM,UAAU,GAAG,MAAM,EAAE;iBACxB,OAAO,CAAC,iFAAiF,CAAC;iBAC1F,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,GAAG,EAAO,CAAC;YACd,MAAM,QAAQ,GAAG,MAAM,EAAE;iBACtB,OAAO,CAAC,2DAA2D,CAAC;iBACpE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,KAAK,EAAO,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,EAAE;iBACpB,OAAO,CACN,oFAAoF,CACrF;iBACA,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,GAAG,EAAO,CAAC;YACd,MAAM,UAAU,GAAG,MAAM,EAAE;iBACxB,OAAO,CACN;uCAC6B,CAC9B;iBACA,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;iBACjB,GAAG,EAAO,CAAC;YACd,MAAM,aAAa,GACjB,QAAQ,KAAK,IAAI;gBACf,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,MAAM,EAAE;qBACL,OAAO,CACN,qFAAqF,CACtF;qBACA,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAO,CAAC;YAEpB,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACnD,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC,IAAI,IAAI,CAAC,CAC3F,CAAC;YAEF,OAAO;gBACL,GAAG,OAAO;gBACV,QAAQ;gBACR,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;gBAC/C,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;gBACxB,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;gBAC/C,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,IAAI,EAAE,CAAC;gBACjF,yEAAyE;gBACzE,wEAAwE;gBACxE,+DAA+D;gBAC/D,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;gBACjF,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;gBAC7C,YAAY,EAAE,cAAc,CAAC,GAAG,CAAC;aAClC,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI;YAC9B,MAAM,GAAG,GAAG,MAAM,EAAE;iBACjB,OAAO,CACN;4DACkD,CACnD;iBACA,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;iBAC7B,KAAK,EAAO,CAAC;YAChB,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAE9B,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,IAAI,MAAM,EAAE,iBAAiB,CAAC,CAAC;YAChE,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YAEnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACrC,2EAA2E;YAC3E,4EAA4E;YAC5E,yEAAyE;YACzE,8DAA8D;YAC9D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,MAAM,IAAI,WAAW,CACnB,UAAU,KAAK,sBAAsB,IAAI,cAAc,OAAO,SAAS,GAAG,cAAc;oBACtF,sFAAsF;oBACtF,sDAAsD,CACzD,CAAC;YACJ,CAAC;YACD,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;QAC9B,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,KAAK;YAChB,MAAM,GAAG,GAAG,MAAM,EAAE;iBACjB,OAAO,CAAC,8EAA8E,CAAC;iBACvF,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;iBACzC,KAAK,EAAO,CAAC;YAEhB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,MAAM,IAAI,WAAW,CACnB,UAAU,KAAK,CAAC,KAAK,qBAAqB,KAAK,CAAC,OAAO,gCAAgC;oBACrF,2EAA2E,CAC9E,CAAC;YACJ,CAAC;YAED,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;YAE/B,2EAA2E;YAC3E,0EAA0E;YAC1E,4EAA4E;YAC5E,sBAAsB;YACtB,IAAI,KAAK,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBAClC,MAAM,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBAC/E,sEAAsE;gBACtE,sEAAsE;gBACtE,sEAAsE;gBACtE,MAAM,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,EAAE;oBACF,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,iBAAiB,CAAC;oBAChD,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACzD,GAAG,CAAC,MAAM,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;iBAClD,CAAC,CAAC;YACL,CAAC;YAED,MAAM,EAAE;iBACL,OAAO,CACN;2CACiC,CAClC;iBACA,IAAI,CACH,OAAO,EACP,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,IAAI,IAAI,IAAI,EAClB,EAAE,EACF,OAAO,CAAC,EAAE,EAAE,YAAY,CAAC,CAC1B;iBACA,GAAG,EAAE,CAAC;YAET,OAAO;gBACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,EAAE;gBACF,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1D,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,KAAK;YACnB,OAAO,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAQ;YAClB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,WAAW,CACnB,yBAAyB,MAAM,CAAC,QAAQ,CAAC,4CAA4C;oBACnF,sCAAsC,CACzC,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,QAAQ,GAAG,UAAU,CAAC;YACvD,MAAM,OAAO,GAAG,MAAM,EAAE;iBACrB,OAAO,CAAC,0DAA0D,CAAC;iBACnE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;iBACrB,GAAG,EAAO,CAAC;YAEd,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;YACxE,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;YAEtF,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,IAAI,aAAa,GAAG,CAAC,CAAC;YAEtB,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;gBACrB,MAAM,IAAI,GAAG,MAAM,EAAE;qBAClB,OAAO,CAAC,4FAA4F,CAAC;qBACrG,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAO,CAAC;gBAEd,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CACvC,CAAC,YAAY,EAAE,WAAW,EAAE,UAAU,CAAW;qBAC/C,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;qBAC7D,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CACrD,CAAC;gBAEF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC/C,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC;gBACvB,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;gBAEhC,MAAM,OAAO,GAAG,MAAM,EAAE;qBACrB,OAAO,CAAC,qEAAqE,CAAC;qBAC9E,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,KAAK,EAAO,CAAC;gBAChB,aAAa,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC;gBAEhE,0EAA0E;gBAC1E,wEAAwE;gBACxE,uEAAuE;gBACvE,qDAAqD;gBACrD,MAAM,EAAE;qBACL,OAAO,CAAC,4DAA4D,CAAC;qBACrE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,gEAAgE,CAAC;qBACzE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,8DAA8D,CAAC;qBACvE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,+DAA+D,CAAC;qBACxE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,6DAA6D,CAAC;qBACtE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,kEAAkE,CAAC;qBAC3E,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE;qBACL,OAAO,CAAC,yDAAyD,CAAC;qBAClE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;qBACjB,GAAG,EAAE,CAAC;gBACT,MAAM,EAAE,CAAC,OAAO,CAAC,oDAAoD,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;YACjG,CAAC;YAED,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAClE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,YAAY,CACzB,EAAU,EACV,OAAe,EACf,KAAa;IAEb,MAAM,GAAG,GAAG,MAAM,EAAE;SACjB,OAAO,CAAC,qEAAqE,CAAC;SAC9E,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC;SACpB,KAAK,EAAO,CAAC;IAEhB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,WAAW,CACnB,UAAU,KAAK,wEAAwE;YACrF,6EAA6E,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACtD,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC;QACtC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC","sourcesContent":["import type { D1Like } from './bindings.js';\nimport { readChangelog, recordApproval } from './changelog.js';\nimport {\n  docket,\n  latestDecisions,\n  summarize,\n  toDeclarations,\n  toNotObserved,\n  toMovement,\n  toPlacement,\n  toReach,\n  toSubjectView,\n  toVariation,\n} from './review-read.js';\nimport { ingestBuild } from './review-ingest.js';\nimport { ReviewError, instant, number, optionalText, text, type Row } from './review-rows.js';\nimport type {\n  BuildDetail,\n  BuildSummary,\n  DecisionRecord,\n  ReviewOptions,\n  ReviewStore,\n  SweepReport,\n} from './review-types.js';\nimport { promote } from './review-write.js';\nimport type { TribunalChangelog } from './changelog.js';\nimport { createBucketStore } from './store.js';\n\n/**\n * The half [ADR-0019](../../../docs/context/adr/0019-one-comment-that-leads-with-causes.md) put out of\n * scope: somewhere a change can be looked at, and somewhere a decision about it\n * survives.\n *\n * ## What a build is\n *\n * A `RunReport` and the images that run kept. Nothing here invents a format — the\n * report is what `variance run` already writes, and the images are what it\n * already saved beside it. A CI job posts one thing it already has.\n *\n * ## Approval promotes; it never records\n *\n * `variance accept` \"never produces an image — it promotes one the run already\n * produced\", and that rule is the reason this file cannot be a simple flag on a\n * row. A baseline is not pixels: it is pixels **plus** the document digest they\n * were painted from and the identity that painted them, which is the sidecar the\n * cheap `describe` path answers from without moving a byte. So a build carries\n * that metadata per subject, and approving writes it through the same\n * `RasterStore` a run reads.\n *\n * A subject whose candidate was never uploaded therefore **cannot be approved**.\n * The alternative is a surface that re-renders in order to say yes, and a surface\n * that can render can record something nobody looked at.\n *\n * ## Two things that are never collapsed\n *\n * **A coverage list that was never stated is not an empty one.** `RunReport`\n * distinguishes them because a run that planned 300 subjects, failed on 50 and\n * found 250 unchanged produces a report in which every observation is clean.\n * Ingest stores which of the two arrived, and every summary below carries it, so\n * \"nothing to review\" cannot be printed on the authority of a writer that never\n * said what it skipped.\n *\n * **Findings that were never collected are not an absence of defects.** Same\n * distinction, same reason: `[]` means this render was inspected and was clean,\n * and `undefined` means nothing looked.\n *\n * ## What is next door\n *\n * The shapes are in [`review-types.ts`](./review-types.ts) so that the Worker and\n * the React surface can name them without a D1 binding; the two writes that reach\n * the bucket are in [`review-write.ts`](./review-write.ts); writing a report in is\n * [`review-ingest.ts`](./review-ingest.ts) and reading a build back out is\n * [`review-read.ts`](./review-read.ts). What is left here is the store\n * itself — the order the writes happen in, and what each operation refuses.\n */\n\nexport type {\n  BuildDetail,\n  BuildIngest,\n  BuildSummary,\n  CandidateImage,\n  Cause,\n  Coverage,\n  Decision,\n  DecisionRecord,\n  ReviewOptions,\n  ReviewStore,\n  SubjectImages,\n  SubjectView,\n  SweepReport,\n} from './review-types.js';\nexport { ReviewError } from './review-rows.js';\nexport type {\n  ChangelogChange,\n  ChangelogRow,\n  TribunalChangelog,\n  TribunalChangelogQuery,\n} from './changelog.js';\n\nexport function createReviewStore(options: ReviewOptions): ReviewStore {\n  const { db, bucket, project } = options;\n  const now = options.now ?? ((): Date => new Date());\n  const baselines = createBucketStore(options);\n\n  return {\n    async ingest(build): Promise<void> {\n      await ingestBuild({ db, bucket, project }, build);\n    },\n\n    async builds(limit = 50): Promise<readonly BuildSummary[]> {\n      const listed = await db\n        .prepare('SELECT * FROM builds WHERE project = ? ORDER BY at_ms DESC, rowid DESC LIMIT ?')\n        .bind(project, limit)\n        .all<Row>();\n\n      const summaries: BuildSummary[] = [];\n      for (const row of listed.results) {\n        summaries.push(await summarize(db, project, row));\n      }\n      return summaries;\n    },\n\n    async build(id): Promise<BuildDetail | null> {\n      const row = await db\n        .prepare('SELECT * FROM builds WHERE project = ? AND build = ?')\n        .bind(project, id)\n        .first<Row>();\n      if (row === null) return null;\n\n      const summary = await summarize(db, project, row);\n      const subjectRows = await db\n        .prepare('SELECT * FROM build_subjects WHERE project = ? AND build = ? ORDER BY subject')\n        .bind(project, id)\n        .all<Row>();\n      const decisions = await latestDecisions(db, project, id);\n      const skipped = await db\n        .prepare('SELECT * FROM build_not_observed WHERE project = ? AND build = ? ORDER BY subject')\n        .bind(project, id)\n        .all<Row>();\n      const variations = await db\n        .prepare('SELECT * FROM build_variations WHERE project = ? AND build = ? ORDER BY subject')\n        .bind(project, id)\n        .all<Row>();\n      const reachRow = await db\n        .prepare('SELECT * FROM build_reach WHERE project = ? AND build = ?')\n        .bind(project, id)\n        .first<Row>();\n      const census = await db\n        .prepare(\n          'SELECT * FROM build_composition WHERE project = ? AND build = ? ORDER BY component',\n        )\n        .bind(project, id)\n        .all<Row>();\n      const attributed = await db\n        .prepare(\n          `SELECT * FROM build_movements WHERE project = ? AND build = ?\n           ORDER BY component, subject`,\n        )\n        .bind(project, id)\n        .all<Row>();\n      const reachSubjects =\n        reachRow === null\n          ? undefined\n          : await db\n              .prepare(\n                'SELECT * FROM build_reach_subjects WHERE project = ? AND build = ? ORDER BY subject',\n              )\n              .bind(project, id)\n              .all<Row>();\n\n      const subjects = subjectRows.results.map((subject) =>\n        toSubjectView(subject, decisions.get(text(subject, 'subject', 'a build subject')) ?? null),\n      );\n\n      return {\n        ...summary,\n        subjects,\n        notObserved: skipped.results.map(toNotObserved),\n        causes: docket(subjects),\n        variations: variations.results.map(toVariation),\n        reach: reachRow === null ? null : toReach(reachRow, reachSubjects?.results ?? []),\n        // No rows is `null`, not `[]`. A run that produced no semantic snapshots\n        // has no graph to join, and an empty list would say the opposite — that\n        // the suite was read and found to contain no component at all.\n        composition: census.results.length === 0 ? null : census.results.map(toPlacement),\n        movements: attributed.results.map(toMovement),\n        declarations: toDeclarations(row),\n      };\n    },\n\n    async image(build, subject, kind): Promise<ArrayBuffer | null> {\n      const row = await db\n        .prepare(\n          `SELECT before_key, after_key, diff_key FROM build_subjects\n            WHERE project = ? AND build = ? AND subject = ?`,\n        )\n        .bind(project, build, subject)\n        .first<Row>();\n      if (row === null) return null;\n\n      const key = optionalText(row, `${kind}_key`, 'a build subject');\n      if (key === undefined) return null;\n\n      const object = await bucket.get(key);\n      // An object a row points at and that is not there is damage, not absence —\n      // the same rule the baseline store applies. Here it costs a broken image in\n      // a page rather than a destroyed baseline, so it is reported rather than\n      // fatal, but it is still not answered as \"the run kept none\".\n      if (object === null) {\n        throw new ReviewError(\n          `build \"${build}\" says it kept the ${kind} image for ${subject} at \\`${key}\\`, and the ` +\n            'bucket has no such object. The row and the object are one artifact; one without the ' +\n            'other is damage rather than a run that saved nothing',\n        );\n      }\n      return object.arrayBuffer();\n    },\n\n    async decide(input): Promise<DecisionRecord> {\n      const row = await db\n        .prepare('SELECT * FROM build_subjects WHERE project = ? AND build = ? AND subject = ?')\n        .bind(project, input.build, input.subject)\n        .first<Row>();\n\n      if (row === null) {\n        throw new ReviewError(\n          `build \"${input.build}\" has no subject \"${input.subject}\". Deciding about a subject a ` +\n            'build never reported would record an approval nothing can be promoted for',\n        );\n      }\n\n      const at = now().toISOString();\n\n      // Promotion happens *before* the decision is recorded. The other order can\n      // leave an approval on the page whose baseline was never written, and the\n      // next run would then report the same change again with the reviewer's name\n      // already against it.\n      if (input.decision === 'approved') {\n        await promote(bucket, baselines, db, project, input.build, input.subject, row);\n        // Beside the promotion, and only for one: an approval is the moment a\n        // baseline changed, and it is the last moment at which anything still\n        // knows what the change was. `build_subjects` expires; this does not.\n        await recordApproval(db, project, {\n          build: input.build,\n          subject: input.subject,\n          by: input.by,\n          at,\n          regions: text(row, 'regions', 'a build subject'),\n          ...(input.note !== undefined ? { note: input.note } : {}),\n          ...(await buildContext(db, project, input.build)),\n        });\n      }\n\n      await db\n        .prepare(\n          `INSERT INTO decisions (project, build, subject, decision, decided_by, note, at, at_ms)\n           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,\n        )\n        .bind(\n          project,\n          input.build,\n          input.subject,\n          input.decision,\n          input.by,\n          input.note ?? null,\n          at,\n          instant(at, 'a decision'),\n        )\n        .run();\n\n      return {\n        decision: input.decision,\n        by: input.by,\n        at,\n        ...(input.note !== undefined ? { note: input.note } : {}),\n      };\n    },\n\n    async changelog(query): Promise<TribunalChangelog> {\n      return readChangelog(db, project, query ?? {});\n    },\n\n    async sweep(keepDays): Promise<SweepReport> {\n      if (!Number.isFinite(keepDays) || keepDays < 0) {\n        throw new ReviewError(\n          `a retention window of ${String(keepDays)} days is not a window. Pass the number of ` +\n            'days of builds to keep; 0 keeps none',\n        );\n      }\n\n      const cutoff = now().getTime() - keepDays * 86_400_000;\n      const expired = await db\n        .prepare('SELECT build FROM builds WHERE project = ? AND at_ms < ?')\n        .bind(project, cutoff)\n        .all<Row>();\n\n      const ids = expired.results.map((row) => text(row, 'build', 'a build'));\n      if (ids.length === 0) return { builds: 0, subjects: 0, objects: 0, decisionsKept: 0 };\n\n      let objects = 0;\n      let subjects = 0;\n      let decisionsKept = 0;\n\n      for (const id of ids) {\n        const rows = await db\n          .prepare('SELECT before_key, after_key, diff_key FROM build_subjects WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .all<Row>();\n\n        const keys = rows.results.flatMap((row) =>\n          (['before_key', 'after_key', 'diff_key'] as const)\n            .map((column) => optionalText(row, column, 'a build subject'))\n            .filter((key): key is string => key !== undefined),\n        );\n\n        if (keys.length > 0) await bucket.delete(keys);\n        objects += keys.length;\n        subjects += rows.results.length;\n\n        const counted = await db\n          .prepare('SELECT COUNT(*) AS n FROM decisions WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .first<Row>();\n        decisionsKept += number(counted ?? {}, 'n', 'a decision count');\n\n        // `decisions` carries a permanence trigger and is deliberately not swept:\n        // a promoted baseline whose approval was deleted is a change nobody can\n        // attribute to anyone. What expires is what a build kept to be *looked\n        // at*, which is images and the verdicts beside them.\n        await db\n          .prepare('DELETE FROM build_subjects WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_not_observed WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_variations WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_composition WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_movements WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_reach_subjects WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db\n          .prepare('DELETE FROM build_reach WHERE project = ? AND build = ?')\n          .bind(project, id)\n          .run();\n        await db.prepare('DELETE FROM builds WHERE project = ? AND build = ?').bind(project, id).run();\n      }\n\n      return { builds: ids.length, subjects, objects, decisionsKept };\n    },\n  };\n}\n\n/**\n * The two things a changelog entry needs from the build and cannot invent.\n *\n * Read at approval time rather than joined at read time, because the build row\n * is what `sweep` removes. A build that has already gone is not a failure here —\n * its subjects would have gone with it, so there would be nothing to approve —\n * but the read is defended anyway, since an entry attributing a baseline to an\n * empty commit is worse than one that says nothing.\n */\nasync function buildContext(\n  db: D1Like,\n  project: string,\n  build: string,\n): Promise<{ readonly commit: string; readonly intent?: string }> {\n  const row = await db\n    .prepare('SELECT \"commit\", intent FROM builds WHERE project = ? AND build = ?')\n    .bind(project, build)\n    .first<Row>();\n\n  if (row === null) {\n    throw new ReviewError(\n      `build \"${build}\" is no longer in this database, so an approval under it could not be ` +\n        'attributed to a commit. A changelog entry naming no commit explains nothing',\n    );\n  }\n\n  const intent = optionalText(row, 'intent', 'a build');\n  return {\n    commit: text(row, 'commit', 'a build'),\n    ...(intent !== undefined ? { intent } : {}),\n  };\n}\n"]}

package/dist/schema.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The version this deployment is on, and the one call that puts a database there.
+ *
+ * The statements themselves are in [`migrations.ts`](./migrations.js) and
+ * [`migration-steps.ts`](./migration-steps.js) — this is the reading of them:
+ * which version they land on, what a fresh database gets, and the batch that
+ * applies it. They were one module until the steps outgrew it, and the ten lines
+ * at the bottom of this file are the part an operator is usually looking for.
+ */
+import type { D1Like } from './bindings.js';
+/** Bumped when the stored shape changes in a way an older build would misread. */
+export declare const SCHEMA_VERSION = 14;
+export { MIGRATIONS } from './migration-steps.js';
+export { INITIAL, INITIAL_VERSION } from './migrations.js';
+/**
+ * Every statement, in order — the initial set followed by each step.
+ *
+ * This is what a fresh database gets, and what the tests run against. The split
+ * between them is about *deployment*; nothing downstream of here needs to know a
+ * database was built in more than one sitting.
+ */
+export declare const SCHEMA: readonly string[];
+/**
+ * Create the schema, once, in one batch.
+ *
+ * Exported for the operator to call from `wrangler d1 execute` equivalents or
+ * from a one-off route they mount themselves — **not** called by the Worker on
+ * request. A handler that migrates on first use is a handler that migrates
+ * concurrently under load, and D1 has no advisory lock to serialize it with.
+ *
+ * Applying it twice fails on the first `CREATE TABLE`, which is the intended
+ * behaviour: an operator who cannot tell whether the schema is applied should get
+ * an error rather than a silent no-op that might have half-applied.
+ */
+export declare function applySchema(db: D1Like): Promise<void>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -0,0 +1,39 @@
+/**
+ * The version this deployment is on, and the one call that puts a database there.
+ *
+ * The statements themselves are in [`migrations.ts`](./migrations.js) and
+ * [`migration-steps.ts`](./migration-steps.js) — this is the reading of them:
+ * which version they land on, what a fresh database gets, and the batch that
+ * applies it. They were one module until the steps outgrew it, and the ten lines
+ * at the bottom of this file are the part an operator is usually looking for.
+ */
+import { MIGRATIONS } from './migration-steps.js';
+import { INITIAL } from './migrations.js';
+/** Bumped when the stored shape changes in a way an older build would misread. */
+export const SCHEMA_VERSION = 14;
+export { MIGRATIONS } from './migration-steps.js';
+export { INITIAL, INITIAL_VERSION } from './migrations.js';
+/**
+ * Every statement, in order — the initial set followed by each step.
+ *
+ * This is what a fresh database gets, and what the tests run against. The split
+ * between them is about *deployment*; nothing downstream of here needs to know a
+ * database was built in more than one sitting.
+ */
+export const SCHEMA = [...INITIAL, ...MIGRATIONS.flat()];
+/**
+ * Create the schema, once, in one batch.
+ *
+ * Exported for the operator to call from `wrangler d1 execute` equivalents or
+ * from a one-off route they mount themselves — **not** called by the Worker on
+ * request. A handler that migrates on first use is a handler that migrates
+ * concurrently under load, and D1 has no advisory lock to serialize it with.
+ *
+ * Applying it twice fails on the first `CREATE TABLE`, which is the intended
+ * behaviour: an operator who cannot tell whether the schema is applied should get
+ * an error rather than a silent no-op that might have half-applied.
+ */
+export async function applySchema(db) {
+    await db.batch(SCHEMA.map((statement) => db.prepare(statement)));
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,kFAAkF;AAClF,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAsB,CAAC,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAAU;IAC1C,MAAM,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC","sourcesContent":["/**\n * The version this deployment is on, and the one call that puts a database there.\n *\n * The statements themselves are in [`migrations.ts`](./migrations.js) and\n * [`migration-steps.ts`](./migration-steps.js) — this is the reading of them:\n * which version they land on, what a fresh database gets, and the batch that\n * applies it. They were one module until the steps outgrew it, and the ten lines\n * at the bottom of this file are the part an operator is usually looking for.\n */\n\nimport type { D1Like } from './bindings.js';\nimport { MIGRATIONS } from './migration-steps.js';\nimport { INITIAL } from './migrations.js';\n\n/** Bumped when the stored shape changes in a way an older build would misread. */\nexport const SCHEMA_VERSION = 14;\n\nexport { MIGRATIONS } from './migration-steps.js';\nexport { INITIAL, INITIAL_VERSION } from './migrations.js';\n\n/**\n * Every statement, in order — the initial set followed by each step.\n *\n * This is what a fresh database gets, and what the tests run against. The split\n * between them is about *deployment*; nothing downstream of here needs to know a\n * database was built in more than one sitting.\n */\nexport const SCHEMA: readonly string[] = [...INITIAL, ...MIGRATIONS.flat()];\n\n/**\n * Create the schema, once, in one batch.\n *\n * Exported for the operator to call from `wrangler d1 execute` equivalents or\n * from a one-off route they mount themselves — **not** called by the Worker on\n * request. A handler that migrates on first use is a handler that migrates\n * concurrently under load, and D1 has no advisory lock to serialize it with.\n *\n * Applying it twice fails on the first `CREATE TABLE`, which is the intended\n * behaviour: an operator who cannot tell whether the schema is applied should get\n * an error rather than a silent no-op that might have half-applied.\n */\nexport async function applySchema(db: D1Like): Promise<void> {\n  await db.batch(SCHEMA.map((statement) => db.prepare(statement)));\n}\n"]}