@variance-authority/tribunal 0.1.0

package/dist/store.d.ts

@@ -0,0 +1,58 @@
+import { type RasterStore } from '@variance-authority/raster';
+import { type TribunalBindings } from './bindings.js';
+/**
+ * Baselines in R2, attributed in D1.
+ *
+ * The third durable backend, after the directory and git-LFS, and it answers to
+ * the same contract for the same reason the other two do: what a baseline
+ * *means* lives in [`@variance-authority/raster`](../../raster), so a verdict
+ * cannot depend on where the bytes were kept. That claim is tested rather than
+ * asserted — this store is one of the implementations in
+ * [`observe/parity.test.ts`](../../observe/src/parity.test.ts), which pins each
+ * expected verdict as well as comparing the backends, because three stores
+ * agreeing on a wrong answer is not a pass.
+ *
+ * ## The split, and why it is not one store
+ *
+ * D1 holds the sidecar; R2 holds the image. That is not two stores pretending to
+ * be one — it is the directory store's `.json`/`.png` pair with the halves in the
+ * services that suit them. Text that gets queried across identities goes where
+ * queries are cheap; bytes that only ever get fetched whole go where bytes are
+ * cheap.
+ *
+ * It inherits the pair's failure mode exactly, and treats it the same way: a row
+ * whose object is gone, or an object whose row is gone, is **damage**, and damage
+ * is never reported as absence. `null` is earned by one outcome only — no row —
+ * because `null` becomes `new`, `new` records whatever this build painted, and
+ * the image it overwrites was the only evidence of what the subject looked like
+ * before.
+ *
+ * ## Write order is the safety property
+ *
+ * `put` writes the object, then the row. The two orders fail differently and only
+ * one of them fails safely:
+ *
+ * - **object first** — a crash between them leaves an object nothing points at.
+ *   Invisible to every read, removed by the next sweep, costs storage.
+ * - **row first** — a crash between them leaves a row pointing at nothing, which
+ *   is a baseline that throws on every subsequent run until a person deletes it.
+ *
+ * D1 and R2 are separate services with no transaction between them, so one of
+ * these happens; this file chooses the one that costs bytes over the one that
+ * stops the suite.
+ */
+export interface BucketStoreOptions extends TribunalBindings {
+    /**
+     * The project these baselines belong to.
+     *
+     * Every row and every object key is scoped by it, so one deployment serves
+     * several repositories without their `story:card` colliding. There is no
+     * default: a store that invented one would put two projects' baselines in one
+     * namespace and the first symptom would be a mass `changed`.
+     */
+    readonly project: string;
+    /** Injected so tests can pin `at`. Defaults to the wall clock. */
+    readonly now?: () => Date;
+}
+export declare function createBucketStore(options: BucketStoreOptions): RasterStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.js

@@ -0,0 +1,278 @@
+import { identityDigest } from '@variance-authority/core';
+import { REFUSAL, RasterStoreError, messageOf, neverFails, sidecarFrom, } from '@variance-authority/raster';
+import { base64Of, bytesOf, requireD1, requireR2, } from './bindings.js';
+/**
+ * Refuse a deployment that never said which project it is.
+ *
+ * Checked here rather than left to the type, because the operator who gets this
+ * wrong reads the value out of an environment or a config file, where the
+ * compiler is not standing. Two of `createTribunal`'s five required options
+ * already answer with a sentence; this one answered `could not reach its
+ * database or its bucket` from the first request that touched a baseline, which
+ * blames the platform for a line in a wrangler file.
+ *
+ * Blank is refused with absent. A project is the namespace every row and object
+ * key is scoped by, and one nobody named is the invented default this option
+ * exists to make impossible.
+ */
+function requireProject(project) {
+    if (typeof project !== 'string' || project.trim() === '') {
+        throw new Error('`project` is required and must not be blank. It scopes every row and every object key, ' +
+            'so one deployment can serve several repositories without their `story:card` colliding; ' +
+            'a deployment that never named itself puts them in one namespace, and the first symptom ' +
+            'is a mass `changed`');
+    }
+}
+export function createBucketStore(options) {
+    const { db, bucket, project } = options;
+    requireD1(db);
+    requireR2(bucket);
+    requireProject(project);
+    const now = options.now ?? (() => new Date());
+    return {
+        retention: 'durable',
+        async find(key, identity) {
+            const mine = identityDigest(identity);
+            const row = await locate(db, project, key, mine);
+            if (row === null)
+                return null;
+            const sidecar = parse(row.sidecar, describeRow(project, key, row.identityDigest));
+            return {
+                raster: { ...sidecar, bytes: await fetchBytes(bucket, row.sidecar.object_key) },
+                comparable: row.identityDigest === mine,
+                storedUnder: sidecar.identity,
+            };
+        },
+        async describe(key, identity) {
+            const mine = identityDigest(identity);
+            const row = await locate(db, project, key, mine);
+            if (row === null)
+                return null;
+            const where = describeRow(project, key, row.identityDigest);
+            const sidecar = parse(row.sidecar, where);
+            // The object is still checked for existence, and this is the entire reason
+            // `R2Like` has a `head`. Answering from the row alone would let `describe`
+            // and `find` disagree about whether a baseline exists, and a verdict that
+            // depends on which of the two a caller asked is not a verdict.
+            if ((await guard(() => bucket.head(row.sidecar.object_key), where)) === null) {
+                throw halfAPair(where, row.sidecar.object_key, 'row');
+            }
+            return {
+                documentDigest: sidecar.documentDigest,
+                comparable: row.identityDigest === mine,
+                storedUnder: sidecar.identity,
+                missingFonts: sidecar.missingFonts,
+                ...(sidecar.components === undefined
+                    ? {}
+                    : { components: sidecar.components.map((hash) => hash.component) }),
+                ...(sidecar.accessibility === undefined
+                    ? {}
+                    : { accessibility: sidecar.accessibility }),
+            };
+        },
+        async put(key, raster) {
+            const label = labelOf(key);
+            const digest = identityDigest(raster.identity);
+            const objectKey = baselineKey(project, digest, key);
+            const where = describeRow(project, key, digest);
+            const at = now().toISOString();
+            await guard(() => bucket.put(objectKey, bytesOf(raster.bytes)), where);
+            await guard(() => db
+                .prepare(`INSERT INTO baselines
+                 (project, identity_digest, subject, label, identity, document_digest,
+                  width, height, missing_fonts, accessibility, object_key, at, at_ms)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+               ON CONFLICT (project, identity_digest, subject, label) DO UPDATE SET
+                 identity = excluded.identity,
+                 document_digest = excluded.document_digest,
+                 width = excluded.width,
+                 height = excluded.height,
+                 missing_fonts = excluded.missing_fonts,
+                 accessibility = excluded.accessibility,
+                 object_key = excluded.object_key,
+                 at = excluded.at,
+                 at_ms = excluded.at_ms`)
+                .bind(project, digest, key.subject, label, JSON.stringify(raster.identity), raster.documentDigest, raster.width, raster.height, JSON.stringify(raster.missingFonts), raster.accessibility === undefined ? null : JSON.stringify(raster.accessibility), objectKey, at, Date.parse(at))
+                .run(), where);
+        },
+        // Wrapped, so a bucket outage costs this run its renders and not its exit
+        // code. The comment that stood here argued the other way — that answering
+        // "miss" to an outage turns a broken bucket into a run that is merely slow —
+        // and a run that is merely slow is the correct outcome: nothing about the
+        // bucket being unreachable changes what any verdict should be. The baseline
+        // half above still refuses out loud, where an outage genuinely would.
+        renderCache: neverFails({
+            async get(digest, identity) {
+                const where = `the render cache for document ${digest}`;
+                const row = await guard(() => db
+                    .prepare(`SELECT identity, document_digest, width, height, missing_fonts, object_key
+                   FROM render_cache
+                  WHERE project = ? AND identity_digest = ? AND document_digest = ?`)
+                    .bind(project, identityDigest(identity), digest)
+                    .first(), where);
+                if (row === null)
+                    return null;
+                return { ...parse(row, where), bytes: await fetchBytes(bucket, row.object_key) };
+            },
+            async put(raster) {
+                const digest = identityDigest(raster.identity);
+                const where = `the render cache for document ${raster.documentDigest}`;
+                const objectKey = `${project}/cache/${digest}/${raster.documentDigest}.png`;
+                await guard(() => bucket.put(objectKey, bytesOf(raster.bytes)), where);
+                await guard(() => db
+                    .prepare(`INSERT OR REPLACE INTO render_cache
+                   (project, identity_digest, document_digest, identity, width, height,
+                    missing_fonts, object_key, at_ms)
+                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .bind(project, digest, raster.documentDigest, JSON.stringify(raster.identity), raster.width, raster.height, JSON.stringify(raster.missingFonts), objectKey, Date.now())
+                    .run(), where);
+            },
+        }),
+    };
+}
+/**
+ * The row for this key under this identity, or the most recent one under any
+ * other, or nothing.
+ *
+ * The lookup is deliberately *not* scoped to the caller's identity, which is the
+ * `RasterStore` contract's own instruction: returning nothing for a baseline that
+ * exists but was written elsewhere reports "we have never seen this", and "we have
+ * seen this, on a machine you are not" is a different and much more useful
+ * sentence — it is the one that produces `incomparable` instead of a silent
+ * re-record.
+ *
+ * Where the directory store scans siblings in whatever order `readdir` returns,
+ * this takes the most recently written. Both satisfy the contract; only one of
+ * them gives the same answer twice when three machines have written the subject,
+ * and an `incomparable` message that names a different machine on each run is a
+ * message nobody can act on.
+ */
+async function locate(db, project, key, mine) {
+    const label = labelOf(key);
+    const where = describeRow(project, key, mine);
+    const row = await guard(() => db
+        .prepare(`SELECT identity, document_digest, width, height, missing_fonts, accessibility, object_key,
+                  identity_digest
+             FROM baselines
+            WHERE project = ? AND subject = ? AND label = ?
+            ORDER BY (identity_digest = ?) DESC, at_ms DESC
+            LIMIT 1`)
+        .bind(project, key.subject, label, mine)
+        .first(), where);
+    return row === null ? null : { sidecar: row, identityDigest: row.identity_digest };
+}
+/**
+ * The bytes a row says are there.
+ *
+ * An absent object is never a miss. The row is the store positively saying a
+ * baseline exists; if the bytes are gone, what happened is that half a baseline
+ * was destroyed, and reporting that as `new` would destroy the other half while
+ * printing success.
+ */
+async function fetchBytes(bucket, objectKey) {
+    const object = await guard(() => bucket.get(objectKey), `the baseline object ${objectKey}`);
+    if (object === null)
+        throw halfAPair(`the baseline object ${objectKey}`, objectKey, 'row');
+    return base64Of(await guard(() => object.arrayBuffer(), `the baseline object ${objectKey}`));
+}
+/**
+ * A sidecar row, checked rather than cast.
+ *
+ * The columns came out of a database this process did not write in this run —
+ * one that may have been written by an older version of this package, or by a
+ * `put` that raced a schema change. Believed unchecked, a malformed `identity`
+ * becomes a digest taken over nothing and a missing `documentDigest` becomes
+ * `undefined` compared against a real one: two invented answers where the honest
+ * one is that the record cannot be read.
+ */
+function parse(row, where) {
+    let identity;
+    let missingFonts;
+    let accessibility;
+    try {
+        identity = JSON.parse(row.identity);
+        missingFonts = JSON.parse(row.missing_fonts);
+        accessibility = row.accessibility == null ? undefined : JSON.parse(row.accessibility);
+    }
+    catch (error) {
+        throw new RasterStoreError(`${where} holds JSON columns that will not parse: ${messageOf(error)}. ${REFUSAL}.`, { cause: error });
+    }
+    const sidecar = sidecarFrom({
+        identity,
+        missingFonts,
+        documentDigest: row.document_digest,
+        width: row.width,
+        height: row.height,
+        ...(accessibility === undefined ? {} : { accessibility }),
+    });
+    if (sidecar === null) {
+        throw new RasterStoreError(`${where} is not a raster record: it parsed, but does not carry a document digest and ` +
+            `the identity that painted it. ${REFUSAL}.`);
+    }
+    return sidecar;
+}
+/**
+ * Every call into D1 and R2 goes through here, and every failure of one becomes
+ * an operator error.
+ *
+ * Not a convenience. A `TypeError` from a binding that was never wired, a 500
+ * from a bucket, a D1 statement refused because the schema is a version behind —
+ * each of them would otherwise propagate as some other kind of exception, and the
+ * one thing that must never happen is that any of them is caught somewhere above
+ * and read as "no baseline".
+ */
+async function guard(call, where) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        throw new RasterStoreError(`the baseline store could not reach its database or its bucket for ${where}: ` +
+            `${messageOf(error)}. ${REFUSAL}.`, { cause: error });
+    }
+}
+/**
+ * One half of the pair without the other.
+ *
+ * The directory store's `halfAPair`, in the vocabulary of two services rather
+ * than two files, and it exists for the same reason: a row with no object and an
+ * object with no row both look exactly like a subject nobody has rendered, if the
+ * lookup is willing to shrug.
+ */
+function halfAPair(where, objectKey, survivor) {
+    return new RasterStoreError(`${where} is half there: the ${survivor} exists and the ` +
+        `${survivor === 'row' ? 'object' : 'row'} does not. A baseline is the pair, so one without ` +
+        `the other is a corrupted baseline rather than a missing one. ${REFUSAL}. Restore ` +
+        `\`${objectKey}\` in the bucket, or delete the row to record the subject afresh.`);
+}
+function baselineKey(project, identity, key) {
+    const name = key.label === undefined ? key.subject : `${key.subject}__${key.label}`;
+    return `${project}/baselines/${identity}/${encodeURIComponent(name)}.png`;
+}
+function describeRow(project, key, identity) {
+    const name = key.label === undefined ? key.subject : `${key.subject} (${key.label})`;
+    return `the baseline for ${name} of project ${project} under identity ${identity}`;
+}
+/**
+ * The label as the database stores it, with absence as the empty string — and an
+ * empty *supplied* label refused rather than folded into it.
+ *
+ * SQLite permits NULL in the columns of an ordinary PRIMARY KEY, so a nullable
+ * `label` would make two unlabelled baselines for one subject two rows that never
+ * collide: the uniqueness that stops a second `put` from replacing the first would
+ * silently not exist, and the store would grow a new baseline per run while
+ * reporting `unchanged` against whichever one it happened to read.
+ *
+ * That forces one encoding to mean two things, so the second one is refused at
+ * the door. `{ subject: 's', label: '' }` is a caller bug either way; the choice
+ * is between diagnosing it and quietly serving it another subject's image.
+ */
+function labelOf(key) {
+    if (key.label === '') {
+        throw new RasterStoreError('a baseline was addressed with an empty label. This store encodes "no label" as the ' +
+            'empty string, so an empty label and no label would be the same baseline — and two ' +
+            'subjects sharing one row is a comparison against the wrong image. Pass no `label` ' +
+            `at all, or a label with something in it. ${REFUSAL}.`);
+    }
+    return key.label ?? '';
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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","sourcesContent":["import { identityDigest, type Digest, type Raster } from '@variance-authority/core';\nimport {\n  REFUSAL,\n  RasterStoreError,\n  messageOf,\n  neverFails,\n  sidecarFrom,\n  type BaselineKey,\n  type Described,\n  type Found,\n  type RasterStore,\n} from '@variance-authority/raster';\nimport {\n  base64Of,\n  bytesOf,\n  requireD1,\n  requireR2,\n  type D1Like,\n  type R2Like,\n  type TribunalBindings,\n} from './bindings.js';\n\n/**\n * Baselines in R2, attributed in D1.\n *\n * The third durable backend, after the directory and git-LFS, and it answers to\n * the same contract for the same reason the other two do: what a baseline\n * *means* lives in [`@variance-authority/raster`](../../raster), so a verdict\n * cannot depend on where the bytes were kept. That claim is tested rather than\n * asserted — this store is one of the implementations in\n * [`observe/parity.test.ts`](../../observe/src/parity.test.ts), which pins each\n * expected verdict as well as comparing the backends, because three stores\n * agreeing on a wrong answer is not a pass.\n *\n * ## The split, and why it is not one store\n *\n * D1 holds the sidecar; R2 holds the image. That is not two stores pretending to\n * be one — it is the directory store's `.json`/`.png` pair with the halves in the\n * services that suit them. Text that gets queried across identities goes where\n * queries are cheap; bytes that only ever get fetched whole go where bytes are\n * cheap.\n *\n * It inherits the pair's failure mode exactly, and treats it the same way: a row\n * whose object is gone, or an object whose row is gone, is **damage**, and damage\n * is never reported as absence. `null` is earned by one outcome only — no row —\n * because `null` becomes `new`, `new` records whatever this build painted, and\n * the image it overwrites was the only evidence of what the subject looked like\n * before.\n *\n * ## Write order is the safety property\n *\n * `put` writes the object, then the row. The two orders fail differently and only\n * one of them fails safely:\n *\n * - **object first** — a crash between them leaves an object nothing points at.\n *   Invisible to every read, removed by the next sweep, costs storage.\n * - **row first** — a crash between them leaves a row pointing at nothing, which\n *   is a baseline that throws on every subsequent run until a person deletes it.\n *\n * D1 and R2 are separate services with no transaction between them, so one of\n * these happens; this file chooses the one that costs bytes over the one that\n * stops the suite.\n */\n\nexport interface BucketStoreOptions extends TribunalBindings {\n  /**\n   * The project these baselines belong to.\n   *\n   * Every row and every object key is scoped by it, so one deployment serves\n   * several repositories without their `story:card` colliding. There is no\n   * default: a store that invented one would put two projects' baselines in one\n   * namespace and the first symptom would be a mass `changed`.\n   */\n  readonly project: string;\n\n  /** Injected so tests can pin `at`. Defaults to the wall clock. */\n  readonly now?: () => Date;\n}\n\n/**\n * Refuse a deployment that never said which project it is.\n *\n * Checked here rather than left to the type, because the operator who gets this\n * wrong reads the value out of an environment or a config file, where the\n * compiler is not standing. Two of `createTribunal`'s five required options\n * already answer with a sentence; this one answered `could not reach its\n * database or its bucket` from the first request that touched a baseline, which\n * blames the platform for a line in a wrangler file.\n *\n * Blank is refused with absent. A project is the namespace every row and object\n * key is scoped by, and one nobody named is the invented default this option\n * exists to make impossible.\n */\nfunction requireProject(project: string): void {\n  if (typeof project !== 'string' || project.trim() === '') {\n    throw new Error(\n      '`project` is required and must not be blank. It scopes every row and every object key, ' +\n        'so one deployment can serve several repositories without their `story:card` colliding; ' +\n        'a deployment that never named itself puts them in one namespace, and the first symptom ' +\n        'is a mass `changed`',\n    );\n  }\n}\n\n/** Shape of every baseline and cache row as it comes back out of D1. */\ninterface SidecarRow {\n  readonly identity: string;\n  readonly document_digest: string;\n  readonly width: number;\n  readonly height: number;\n  readonly missing_fonts: string;\n  readonly object_key: string;\n  readonly accessibility?: string | null;\n}\n\nexport function createBucketStore(options: BucketStoreOptions): RasterStore {\n  const { db, bucket, project } = options;\n  requireD1(db);\n  requireR2(bucket);\n  requireProject(project);\n  const now = options.now ?? ((): Date => new Date());\n\n  return {\n    retention: 'durable',\n\n    async find(key, identity): Promise<Found | null> {\n      const mine = identityDigest(identity);\n      const row = await locate(db, project, key, mine);\n      if (row === null) return null;\n\n      const sidecar = parse(row.sidecar, describeRow(project, key, row.identityDigest));\n      return {\n        raster: { ...sidecar, bytes: await fetchBytes(bucket, row.sidecar.object_key) },\n        comparable: row.identityDigest === mine,\n        storedUnder: sidecar.identity,\n      };\n    },\n\n    async describe(key, identity): Promise<Described | null> {\n      const mine = identityDigest(identity);\n      const row = await locate(db, project, key, mine);\n      if (row === null) return null;\n\n      const where = describeRow(project, key, row.identityDigest);\n      const sidecar = parse(row.sidecar, where);\n\n      // The object is still checked for existence, and this is the entire reason\n      // `R2Like` has a `head`. Answering from the row alone would let `describe`\n      // and `find` disagree about whether a baseline exists, and a verdict that\n      // depends on which of the two a caller asked is not a verdict.\n      if ((await guard(() => bucket.head(row.sidecar.object_key), where)) === null) {\n        throw halfAPair(where, row.sidecar.object_key, 'row');\n      }\n\n      return {\n        documentDigest: sidecar.documentDigest,\n        comparable: row.identityDigest === mine,\n        storedUnder: sidecar.identity,\n        missingFonts: sidecar.missingFonts,\n        ...(sidecar.components === undefined\n          ? {}\n          : { components: sidecar.components.map((hash) => hash.component) }),\n        ...(sidecar.accessibility === undefined\n          ? {}\n          : { accessibility: sidecar.accessibility }),\n      };\n    },\n\n    async put(key, raster): Promise<void> {\n      const label = labelOf(key);\n      const digest = identityDigest(raster.identity);\n      const objectKey = baselineKey(project, digest, key);\n      const where = describeRow(project, key, digest);\n      const at = now().toISOString();\n\n      await guard(() => bucket.put(objectKey, bytesOf(raster.bytes)), where);\n      await guard(\n        () =>\n          db\n            .prepare(\n              `INSERT INTO baselines\n                 (project, identity_digest, subject, label, identity, document_digest,\n                  width, height, missing_fonts, accessibility, object_key, at, at_ms)\n               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n               ON CONFLICT (project, identity_digest, subject, label) DO UPDATE SET\n                 identity = excluded.identity,\n                 document_digest = excluded.document_digest,\n                 width = excluded.width,\n                 height = excluded.height,\n                 missing_fonts = excluded.missing_fonts,\n                 accessibility = excluded.accessibility,\n                 object_key = excluded.object_key,\n                 at = excluded.at,\n                 at_ms = excluded.at_ms`,\n            )\n            .bind(\n              project,\n              digest,\n              key.subject,\n              label,\n              JSON.stringify(raster.identity),\n              raster.documentDigest,\n              raster.width,\n              raster.height,\n              JSON.stringify(raster.missingFonts),\n              raster.accessibility === undefined ? null : JSON.stringify(raster.accessibility),\n              objectKey,\n              at,\n              Date.parse(at),\n            )\n            .run(),\n        where,\n      );\n    },\n\n    // Wrapped, so a bucket outage costs this run its renders and not its exit\n    // code. The comment that stood here argued the other way — that answering\n    // \"miss\" to an outage turns a broken bucket into a run that is merely slow —\n    // and a run that is merely slow is the correct outcome: nothing about the\n    // bucket being unreachable changes what any verdict should be. The baseline\n    // half above still refuses out loud, where an outage genuinely would.\n    renderCache: neverFails({\n      async get(digest, identity): Promise<Raster | null> {\n        const where = `the render cache for document ${digest}`;\n        const row = await guard(\n          () =>\n            db\n              .prepare(\n                `SELECT identity, document_digest, width, height, missing_fonts, object_key\n                   FROM render_cache\n                  WHERE project = ? AND identity_digest = ? AND document_digest = ?`,\n              )\n              .bind(project, identityDigest(identity), digest)\n              .first<SidecarRow>(),\n          where,\n        );\n        if (row === null) return null;\n\n        return { ...parse(row, where), bytes: await fetchBytes(bucket, row.object_key) };\n      },\n\n      async put(raster): Promise<void> {\n        const digest = identityDigest(raster.identity);\n        const where = `the render cache for document ${raster.documentDigest}`;\n        const objectKey = `${project}/cache/${digest}/${raster.documentDigest}.png`;\n\n        await guard(() => bucket.put(objectKey, bytesOf(raster.bytes)), where);\n        await guard(\n          () =>\n            db\n              .prepare(\n                `INSERT OR REPLACE INTO render_cache\n                   (project, identity_digest, document_digest, identity, width, height,\n                    missing_fonts, object_key, at_ms)\n                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n              )\n              .bind(\n                project,\n                digest,\n                raster.documentDigest,\n                JSON.stringify(raster.identity),\n                raster.width,\n                raster.height,\n                JSON.stringify(raster.missingFonts),\n                objectKey,\n                Date.now(),\n              )\n              .run(),\n          where,\n        );\n      },\n    }),\n  };\n}\n\n/**\n * The row for this key under this identity, or the most recent one under any\n * other, or nothing.\n *\n * The lookup is deliberately *not* scoped to the caller's identity, which is the\n * `RasterStore` contract's own instruction: returning nothing for a baseline that\n * exists but was written elsewhere reports \"we have never seen this\", and \"we have\n * seen this, on a machine you are not\" is a different and much more useful\n * sentence — it is the one that produces `incomparable` instead of a silent\n * re-record.\n *\n * Where the directory store scans siblings in whatever order `readdir` returns,\n * this takes the most recently written. Both satisfy the contract; only one of\n * them gives the same answer twice when three machines have written the subject,\n * and an `incomparable` message that names a different machine on each run is a\n * message nobody can act on.\n */\nasync function locate(\n  db: D1Like,\n  project: string,\n  key: BaselineKey,\n  mine: Digest,\n): Promise<{ readonly sidecar: SidecarRow; readonly identityDigest: string } | null> {\n  const label = labelOf(key);\n  const where = describeRow(project, key, mine);\n\n  const row = await guard(\n    () =>\n      db\n        .prepare(\n          `SELECT identity, document_digest, width, height, missing_fonts, accessibility, object_key,\n                  identity_digest\n             FROM baselines\n            WHERE project = ? AND subject = ? AND label = ?\n            ORDER BY (identity_digest = ?) DESC, at_ms DESC\n            LIMIT 1`,\n        )\n        .bind(project, key.subject, label, mine)\n        .first<SidecarRow & { readonly identity_digest: string }>(),\n    where,\n  );\n\n  return row === null ? null : { sidecar: row, identityDigest: row.identity_digest };\n}\n\n/**\n * The bytes a row says are there.\n *\n * An absent object is never a miss. The row is the store positively saying a\n * baseline exists; if the bytes are gone, what happened is that half a baseline\n * was destroyed, and reporting that as `new` would destroy the other half while\n * printing success.\n */\nasync function fetchBytes(bucket: R2Like, objectKey: string): Promise<string> {\n  const object = await guard(() => bucket.get(objectKey), `the baseline object ${objectKey}`);\n  if (object === null) throw halfAPair(`the baseline object ${objectKey}`, objectKey, 'row');\n  return base64Of(await guard(() => object.arrayBuffer(), `the baseline object ${objectKey}`));\n}\n\n/**\n * A sidecar row, checked rather than cast.\n *\n * The columns came out of a database this process did not write in this run —\n * one that may have been written by an older version of this package, or by a\n * `put` that raced a schema change. Believed unchecked, a malformed `identity`\n * becomes a digest taken over nothing and a missing `documentDigest` becomes\n * `undefined` compared against a real one: two invented answers where the honest\n * one is that the record cannot be read.\n */\nfunction parse(row: SidecarRow, where: string): Omit<Raster, 'bytes'> {\n  let identity: unknown;\n  let missingFonts: unknown;\n  let accessibility: unknown;\n  try {\n    identity = JSON.parse(row.identity) as unknown;\n    missingFonts = JSON.parse(row.missing_fonts) as unknown;\n    accessibility = row.accessibility == null ? undefined : (JSON.parse(row.accessibility) as unknown);\n  } catch (error) {\n    throw new RasterStoreError(\n      `${where} holds JSON columns that will not parse: ${messageOf(error)}. ${REFUSAL}.`,\n      { cause: error },\n    );\n  }\n\n  const sidecar = sidecarFrom({\n    identity,\n    missingFonts,\n    documentDigest: row.document_digest,\n    width: row.width,\n    height: row.height,\n    ...(accessibility === undefined ? {} : { accessibility }),\n  });\n\n  if (sidecar === null) {\n    throw new RasterStoreError(\n      `${where} is not a raster record: it parsed, but does not carry a document digest and ` +\n        `the identity that painted it. ${REFUSAL}.`,\n    );\n  }\n  return sidecar;\n}\n\n/**\n * Every call into D1 and R2 goes through here, and every failure of one becomes\n * an operator error.\n *\n * Not a convenience. A `TypeError` from a binding that was never wired, a 500\n * from a bucket, a D1 statement refused because the schema is a version behind —\n * each of them would otherwise propagate as some other kind of exception, and the\n * one thing that must never happen is that any of them is caught somewhere above\n * and read as \"no baseline\".\n */\nasync function guard<T>(call: () => Promise<T>, where: string): Promise<T> {\n  try {\n    return await call();\n  } catch (error) {\n    throw new RasterStoreError(\n      `the baseline store could not reach its database or its bucket for ${where}: ` +\n        `${messageOf(error)}. ${REFUSAL}.`,\n      { cause: error },\n    );\n  }\n}\n\n/**\n * One half of the pair without the other.\n *\n * The directory store's `halfAPair`, in the vocabulary of two services rather\n * than two files, and it exists for the same reason: a row with no object and an\n * object with no row both look exactly like a subject nobody has rendered, if the\n * lookup is willing to shrug.\n */\nfunction halfAPair(where: string, objectKey: string, survivor: 'row' | 'object'): RasterStoreError {\n  return new RasterStoreError(\n    `${where} is half there: the ${survivor} exists and the ` +\n      `${survivor === 'row' ? 'object' : 'row'} does not. A baseline is the pair, so one without ` +\n      `the other is a corrupted baseline rather than a missing one. ${REFUSAL}. Restore ` +\n      `\\`${objectKey}\\` in the bucket, or delete the row to record the subject afresh.`,\n  );\n}\n\nfunction baselineKey(project: string, identity: Digest, key: BaselineKey): string {\n  const name = key.label === undefined ? key.subject : `${key.subject}__${key.label}`;\n  return `${project}/baselines/${identity}/${encodeURIComponent(name)}.png`;\n}\n\nfunction describeRow(project: string, key: BaselineKey, identity: string): string {\n  const name = key.label === undefined ? key.subject : `${key.subject} (${key.label})`;\n  return `the baseline for ${name} of project ${project} under identity ${identity}`;\n}\n\n/**\n * The label as the database stores it, with absence as the empty string — and an\n * empty *supplied* label refused rather than folded into it.\n *\n * SQLite permits NULL in the columns of an ordinary PRIMARY KEY, so a nullable\n * `label` would make two unlabelled baselines for one subject two rows that never\n * collide: the uniqueness that stops a second `put` from replacing the first would\n * silently not exist, and the store would grow a new baseline per run while\n * reporting `unchanged` against whichever one it happened to read.\n *\n * That forces one encoding to mean two things, so the second one is refused at\n * the door. `{ subject: 's', label: '' }` is a caller bug either way; the choice\n * is between diagnosing it and quietly serving it another subject's image.\n */\nfunction labelOf(key: BaselineKey): string {\n  if (key.label === '') {\n    throw new RasterStoreError(\n      'a baseline was addressed with an empty label. This store encodes \"no label\" as the ' +\n        'empty string, so an empty label and no label would be the same baseline — and two ' +\n        'subjects sharing one row is a comparison against the wrong image. Pass no `label` ' +\n        `at all, or a label with something in it. ${REFUSAL}.`,\n    );\n  }\n  return key.label ?? '';\n}\n"]}

package/dist/testing.d.ts

@@ -0,0 +1,38 @@
+import { type R2Like } from './bindings.js';
+import { type SqliteDatabase } from './node/database.js';
+/**
+ * A database with the schema already applied, and a way to let go of it.
+ *
+ * The same shape [`node/database.ts`](./node/database.ts) hands a running
+ * service — this is that adapter, over `':memory:'`, with the schema applied
+ * unconditionally because a fresh in-memory file is never anything else.
+ */
+export type SqliteD1 = SqliteDatabase;
+/**
+ * A `D1Like` over `node:sqlite`, with the schema already applied.
+ *
+ * Deliberately not its own implementation. The wrapper is
+ * {@link wrapSqlite}, the one an operator's service runs, so a test that passes
+ * here is a test of the shipped adapter rather than of a second one written to
+ * agree with it. What differs is only the lifecycle: this applies `SCHEMA`
+ * outright, where `openDatabase` has to tell a fresh file from a deployed one.
+ *
+ * A path may be passed for a test that wants a file it can reopen; `':memory:'`
+ * is the default and disappears with the handle.
+ */
+export declare function createSqliteD1(path?: string): Promise<SqliteD1>;
+export interface MemoryR2 extends R2Like {
+    /** Every key currently held, sorted. The assertion surface for retention tests. */
+    keys(): readonly string[];
+    /** Base64 of one object, for a test that wants to compare bytes rather than count them. */
+    read(key: string): string | undefined;
+    /**
+     * Make the next `count` calls of any kind throw.
+     *
+     * Because "a store failure is never a verdict" is the rule this whole package
+     * is arranged around, and a rule with no test that breaks it is a comment.
+     */
+    fail(message: string, count?: number): void;
+}
+export declare function createMemoryR2(): MemoryR2;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -0,0 +1,92 @@
+import { createRequire } from 'node:module';
+import { base64Of } from './bindings.js';
+import { wrapSqlite } from './node/database.js';
+import { applySchema } from './schema.js';
+/**
+ * Cloudflare, doubled — and doubled at the level where the doubling is honest.
+ *
+ * A fake that answered queries from a `Map` would test this package's control
+ * flow and nothing else: the schema, the indexes, the append-only triggers, the
+ * `ON CONFLICT` clause and every `ORDER BY` would be strings nobody executed.
+ * D1 *is* SQLite, and `node:sqlite` is already a dependency of
+ * [`@variance-authority/server`](../../server), so the double below runs the real
+ * statements against a real engine. What the tests then verify is the SQL, not a
+ * paraphrase of it.
+ *
+ * **What it does not verify** is Cloudflare. Request limits, object-size
+ * ceilings, quotas, consistency between two Workers writing at once, and whether
+ * D1's `batch` is transactional in the way this package needs — none of those are
+ * measured, here or anywhere else in this repository. They are stated as unmet in
+ * [ADR-0023](../../../docs/context/adr/0023-a-service-is-named-for-what-it-is.md) and the checkpoint rather than
+ * implied to be fine by a green suite.
+ *
+ * Exported as `@variance-authority/tribunal/testing` because it is also the
+ * thing an operator wants: a way to run their own wiring — their routes, their
+ * ingest, their retention settings — in a plain `vitest` process, with no
+ * `wrangler`, no container, and no account.
+ */
+const { DatabaseSync: Database } = createRequire(import.meta.url)('node:sqlite');
+/**
+ * A `D1Like` over `node:sqlite`, with the schema already applied.
+ *
+ * Deliberately not its own implementation. The wrapper is
+ * {@link wrapSqlite}, the one an operator's service runs, so a test that passes
+ * here is a test of the shipped adapter rather than of a second one written to
+ * agree with it. What differs is only the lifecycle: this applies `SCHEMA`
+ * outright, where `openDatabase` has to tell a fresh file from a deployed one.
+ *
+ * A path may be passed for a test that wants a file it can reopen; `':memory:'`
+ * is the default and disappears with the handle.
+ */
+export async function createSqliteD1(path = ':memory:') {
+    const database = new Database(path);
+    const db = wrapSqlite(database);
+    await applySchema(db);
+    return db;
+}
+export function createMemoryR2() {
+    const objects = new Map();
+    let failures = 0;
+    let reason = '';
+    const check = () => {
+        if (failures <= 0)
+            return;
+        failures -= 1;
+        throw new Error(reason);
+    };
+    const object = (buffer) => ({
+        arrayBuffer: async () => buffer,
+    });
+    return {
+        async get(key) {
+            check();
+            const stored = objects.get(key);
+            return stored === undefined ? null : object(stored);
+        },
+        async head(key) {
+            check();
+            return objects.has(key) ? { key } : null;
+        },
+        async put(key, value) {
+            check();
+            objects.set(key, value);
+            return { key };
+        },
+        async delete(keys) {
+            check();
+            for (const key of typeof keys === 'string' ? [keys] : keys)
+                objects.delete(key);
+            return undefined;
+        },
+        keys: () => [...objects.keys()].sort(),
+        read: (key) => {
+            const stored = objects.get(key);
+            return stored === undefined ? undefined : base64Of(stored);
+        },
+        fail: (message, count = 1) => {
+            reason = message;
+            failures = count;
+        },
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport type { DatabaseSync } from 'node:sqlite';\nimport { base64Of, type R2Like, type R2ObjectLike } from './bindings.js';\nimport { wrapSqlite, type SqliteDatabase } from './node/database.js';\nimport { applySchema } from './schema.js';\n\n/**\n * Cloudflare, doubled — and doubled at the level where the doubling is honest.\n *\n * A fake that answered queries from a `Map` would test this package's control\n * flow and nothing else: the schema, the indexes, the append-only triggers, the\n * `ON CONFLICT` clause and every `ORDER BY` would be strings nobody executed.\n * D1 *is* SQLite, and `node:sqlite` is already a dependency of\n * [`@variance-authority/server`](../../server), so the double below runs the real\n * statements against a real engine. What the tests then verify is the SQL, not a\n * paraphrase of it.\n *\n * **What it does not verify** is Cloudflare. Request limits, object-size\n * ceilings, quotas, consistency between two Workers writing at once, and whether\n * D1's `batch` is transactional in the way this package needs — none of those are\n * measured, here or anywhere else in this repository. They are stated as unmet in\n * [ADR-0023](../../../docs/context/adr/0023-a-service-is-named-for-what-it-is.md) and the checkpoint rather than\n * implied to be fine by a green suite.\n *\n * Exported as `@variance-authority/tribunal/testing` because it is also the\n * thing an operator wants: a way to run their own wiring — their routes, their\n * ingest, their retention settings — in a plain `vitest` process, with no\n * `wrangler`, no container, and no account.\n */\n\nconst { DatabaseSync: Database } = createRequire(import.meta.url)('node:sqlite') as {\n  DatabaseSync: new (path: string) => DatabaseSync;\n};\n\n/**\n * A database with the schema already applied, and a way to let go of it.\n *\n * The same shape [`node/database.ts`](./node/database.ts) hands a running\n * service — this is that adapter, over `':memory:'`, with the schema applied\n * unconditionally because a fresh in-memory file is never anything else.\n */\nexport type SqliteD1 = SqliteDatabase;\n\n/**\n * A `D1Like` over `node:sqlite`, with the schema already applied.\n *\n * Deliberately not its own implementation. The wrapper is\n * {@link wrapSqlite}, the one an operator's service runs, so a test that passes\n * here is a test of the shipped adapter rather than of a second one written to\n * agree with it. What differs is only the lifecycle: this applies `SCHEMA`\n * outright, where `openDatabase` has to tell a fresh file from a deployed one.\n *\n * A path may be passed for a test that wants a file it can reopen; `':memory:'`\n * is the default and disappears with the handle.\n */\nexport async function createSqliteD1(path = ':memory:'): Promise<SqliteD1> {\n  const database = new Database(path);\n  const db = wrapSqlite(database);\n  await applySchema(db);\n  return db;\n}\n\nexport interface MemoryR2 extends R2Like {\n  /** Every key currently held, sorted. The assertion surface for retention tests. */\n  keys(): readonly string[];\n  /** Base64 of one object, for a test that wants to compare bytes rather than count them. */\n  read(key: string): string | undefined;\n  /**\n   * Make the next `count` calls of any kind throw.\n   *\n   * Because \"a store failure is never a verdict\" is the rule this whole package\n   * is arranged around, and a rule with no test that breaks it is a comment.\n   */\n  fail(message: string, count?: number): void;\n}\n\nexport function createMemoryR2(): MemoryR2 {\n  const objects = new Map<string, ArrayBuffer>();\n  let failures = 0;\n  let reason = '';\n\n  const check = (): void => {\n    if (failures <= 0) return;\n    failures -= 1;\n    throw new Error(reason);\n  };\n\n  const object = (buffer: ArrayBuffer): R2ObjectLike => ({\n    arrayBuffer: async (): Promise<ArrayBuffer> => buffer,\n  });\n\n  return {\n    async get(key: string): Promise<R2ObjectLike | null> {\n      check();\n      const stored = objects.get(key);\n      return stored === undefined ? null : object(stored);\n    },\n    async head(key: string): Promise<unknown | null> {\n      check();\n      return objects.has(key) ? { key } : null;\n    },\n    async put(key: string, value: ArrayBuffer): Promise<unknown> {\n      check();\n      objects.set(key, value);\n      return { key };\n    },\n    async delete(keys: string | readonly string[]): Promise<unknown> {\n      check();\n      for (const key of typeof keys === 'string' ? [keys] : keys) objects.delete(key);\n      return undefined;\n    },\n\n    keys: () => [...objects.keys()].sort(),\n    read: (key: string) => {\n      const stored = objects.get(key);\n      return stored === undefined ? undefined : base64Of(stored);\n    },\n    fail: (message: string, count = 1): void => {\n      reason = message;\n      failures = count;\n    },\n  };\n}\n"]}

package/dist/ui/__probe.d.ts

@@ -0,0 +1,3 @@
+import type { BuildDetail } from '../review.js';
+export declare function probe(build: BuildDetail): number;
+//# sourceMappingURL=__probe.d.ts.map

package/dist/ui/__probe.js

@@ -0,0 +1,5 @@
+import { clusterChanges } from '@variance-authority/report';
+export function probe(build) {
+    return clusterChanges(build.subjects).changes.length;
+}
+//# sourceMappingURL=__probe.js.map

package/dist/ui/__probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"__probe.js","sourceRoot":"","sources":["../../src/ui/__probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,MAAM,UAAU,KAAK,CAAC,KAAkB;IACtC,OAAO,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;AACvD,CAAC","sourcesContent":["import { clusterChanges } from '@variance-authority/report';\nimport type { BuildDetail } from '../review.js';\n\nexport function probe(build: BuildDetail): number {\n  return clusterChanges(build.subjects).changes.length;\n}\n"]}

package/dist/ui/attribution.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What the run decided about each thing that moved, addressed by the pair.
+ *
+ * The build page used to answer *why did this move* by walking the census
+ * itself — up from the component that moved, through what encloses it, to a name
+ * the diff reaches. That walk was a reconstruction, and it worked from the
+ * thinner half of the record: the census carries edges, and the run that wrote it
+ * also had the diff, the source index that maps a component to the file declaring
+ * it, the props digest each rendering was grouped under, and the subjects where
+ * the same component with the same props held still. It reached a conclusion from
+ * all four and wrote one sentence per movement. None of it crossed the wire.
+ *
+ * So the page asks rather than re-derives. What is here is the addressing — a
+ * movement is about a *pair*, and the two questions a surface asks of it are
+ * *what happened to this component here* and *what happened to it anywhere* —
+ * plus the one fold that turns a component's several answers into the band it is
+ * read under.
+ *
+ * ## The pair is not a formality
+ *
+ * The same `Button` is `edited` on the page whose file the diff names and
+ * `upstream` on the page where a changed parent hands it a different label. A
+ * surface keyed by component alone shows one of those and is wrong about the
+ * other, and which one it is wrong about depends on iteration order.
+ */
+import type { BuildDetail, MovementView } from '../review-types.js';
+/** The five rungs, as the report's ladder names them. */
+export type Rung = MovementView['cause'];
+/** One build's attributions, indexed the two ways a surface asks for them. */
+export interface Attributions {
+    /** What the run concluded about this component in this render. */
+    readonly at: (component: string, subject: string) => MovementView | undefined;
+    /** Every conclusion about this component, in the order the store returned. */
+    readonly about: (component: string) => readonly MovementView[];
+}
+export declare function attributionsOf(build: BuildDetail): Attributions;
+/**
+ * One component's rung, over every render it moved in.
+ *
+ * `undefined` when the run recorded nothing about it — which is not a rung and
+ * must never be drawn as one. A build ingested before attributions were carried
+ * returns this for everything, and a reader that turned it into *unexplained*
+ * would be reporting a missing input as a finding.
+ */
+export declare function rungAcross(movements: readonly MovementView[]): Rung | undefined;
+//# sourceMappingURL=attribution.d.ts.map