@variance-authority/tribunal 0.1.0

package/dist/history-rows.js

@@ -0,0 +1,148 @@
+import { BANDS as FREQUENCY_BANDS, profileById, } from '@variance-authority/core';
+import { BANDS, } from '@variance-authority/history';
+/**
+ * An instant as a comparable number.
+ *
+ * Refuses rather than defaults. A row whose `at` cannot be parsed would land with
+ * a NULL ordering key, sort ahead of or behind everything depending on the query,
+ * and turn `12px → 20px` into `20px → 12px` — a confident sentence that is exactly
+ * backwards.
+ */
+export function instant(at, what) {
+    const parsed = Date.parse(at);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${what} carries "${at}", which is not an ISO-8601 instant`);
+    }
+    return parsed;
+}
+export function text(row, column, what) {
+    const value = row[column];
+    if (typeof value !== 'string') {
+        throw new Error(`${what} has a \`${column}\` that is not text: ${describe(value)}`);
+    }
+    return value;
+}
+function optionalText(row, column, what) {
+    const value = row[column];
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new Error(`${what} has a \`${column}\` that is neither text nor null: ${describe(value)}`);
+    }
+    return value;
+}
+export function number(row, column, what) {
+    const value = row[column];
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`${what} has a \`${column}\` that is not a number: ${describe(value)}`);
+    }
+    return value;
+}
+function band(row, what) {
+    const value = text(row, 'band', what);
+    if (!BANDS.includes(value))
+        throw new Error(`${what} has an unknown band "${value}"`);
+    return value;
+}
+/** Checked against `core`'s table, so a new tier does not become a rejected row. */
+function profile(row, what) {
+    const value = text(row, 'profile', what);
+    const known = profileById(value);
+    if (known === undefined)
+        throw new Error(`${what} has an unknown profile "${value}"`);
+    return value;
+}
+export function toObservation(row) {
+    const what = 'a stored observation';
+    const file = optionalText(row, 'file', what);
+    return {
+        project: text(row, 'project', what),
+        subject: text(row, 'subject', what),
+        component: text(row, 'component', what),
+        band: band(row, what),
+        hash: text(row, 'hash', what),
+        profile: profile(row, what),
+        commit: text(row, 'commit', what),
+        run: text(row, 'run', what),
+        at: text(row, 'at', what),
+        accepted: number(row, 'accepted', what) !== 0,
+        ...(file !== undefined ? { file } : {}),
+    };
+}
+export function toRunRecord(row) {
+    const what = 'a stored run';
+    const swept = row['swept'];
+    return {
+        project: text(row, 'project', what),
+        run: text(row, 'run', what),
+        commit: text(row, 'commit', what),
+        profile: profile(row, what),
+        at: text(row, 'at', what),
+        // Null stays absent. A run recorded before the column existed never said what
+        // it examined, and "did not sweep" is a claim — one that would make an old
+        // history look like a suite nobody ever swept.
+        ...(swept === null || swept === undefined ? {} : { swept: number(row, 'swept', what) !== 0 }),
+    };
+}
+/**
+ * One occurrence of a subject failing to read the same way twice.
+ *
+ * Transcribed from `server/sqlite-rows.ts`, nullability included: a component
+ * that could not be named comes back absent rather than as an empty string,
+ * because empty would read as a component whose name is nothing.
+ */
+export function toInstability(row) {
+    const what = 'a stored instability';
+    const component = optionalText(row, 'component', what);
+    const stored = optionalText(row, 'band', what);
+    const absorbedBy = optionalText(row, 'absorbed_by', what);
+    return {
+        project: text(row, 'project', what),
+        subject: text(row, 'subject', what),
+        ...(component !== undefined ? { component } : {}),
+        ...(stored !== undefined ? { band: frequencyBand(stored, what) } : {}),
+        profile: profile(row, what),
+        commit: text(row, 'commit', what),
+        run: text(row, 'run', what),
+        at: text(row, 'at', what),
+        ...(absorbedBy !== undefined ? { absorbedBy } : {}),
+    };
+}
+/** A frequency band — how often that kind of thing changes — not a hash band. */
+function frequencyBand(value, what) {
+    if (!FREQUENCY_BANDS.includes(value)) {
+        throw new Error(`${what} has an unknown frequency band "${value}"`);
+    }
+    return value;
+}
+export function toApproval(row) {
+    const what = 'a stored approval';
+    const by = optionalText(row, 'approver', what);
+    return {
+        project: text(row, 'project', what),
+        subject: text(row, 'subject', what),
+        run: text(row, 'run', what),
+        at: text(row, 'at', what),
+        ...(by !== undefined ? { by } : {}),
+    };
+}
+export function toTokenValue(row) {
+    const what = 'a stored token value';
+    return {
+        project: text(row, 'project', what),
+        token: text(row, 'token', what),
+        value: text(row, 'value', what),
+        commit: text(row, 'commit', what),
+        at: text(row, 'at', what),
+    };
+}
+function describe(value) {
+    if (value === undefined)
+        return 'absent';
+    if (value === null)
+        return 'null';
+    return `${typeof value} (${String(value).slice(0, 60)})`;
+}
+//# sourceMappingURL=history-rows.js.map

package/dist/history-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-rows.js","sourceRoot":"","sources":["../src/history-rows.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BANDS as FREQUENCY_BANDS,\n  profileById,\n  type Digest,\n  type ProfileId,\n} from '@variance-authority/core';\nimport {\n  BANDS,\n  type Approval,\n  type Band,\n  type FrequencyBand,\n  type Instability,\n  type Observation,\n  type RunRecord,\n  type TokenValue,\n} from '@variance-authority/history';\n\n/**\n * Reading a row back is validation, not a cast.\n *\n * SQLite is typed per value rather than per column, and `STRICT` only constrains\n * what this build writes. A row written by a future version, or by a person at a\n * `wrangler d1 execute` prompt, arrives here as whatever it is; casting it would\n * let a number become a component name and a NULL become the string \"null\" three\n * layers later.\n *\n * That argument is the whole of this file, and it is why it is a file: every\n * reader below is one refusal, and the same handful of them is used by the append\n * path, the filters, the slices and the reach query alike. `instant` sits with\n * them because it is the same refusal applied to a bound rather than to a column.\n * Nothing here knows any SQL, and [`history.ts`](./history.ts) knows nothing\n * about what a stored value is allowed to be.\n */\n\nexport type Row = Record<string, unknown>;\n\n/**\n * An instant as a comparable number.\n *\n * Refuses rather than defaults. A row whose `at` cannot be parsed would land with\n * a NULL ordering key, sort ahead of or behind everything depending on the query,\n * and turn `12px → 20px` into `20px → 12px` — a confident sentence that is exactly\n * backwards.\n */\nexport function instant(at: string, what: string): number {\n  const parsed = Date.parse(at);\n  if (Number.isNaN(parsed)) {\n    throw new Error(`${what} carries \"${at}\", which is not an ISO-8601 instant`);\n  }\n  return parsed;\n}\n\nexport function text(row: Row, column: string, what: string): string {\n  const value = row[column];\n  if (typeof value !== 'string') {\n    throw new Error(`${what} has a \\`${column}\\` that is not text: ${describe(value)}`);\n  }\n  return value;\n}\n\nfunction optionalText(row: Row, column: string, what: string): string | undefined {\n  const value = row[column];\n  if (value === null || value === undefined) return undefined;\n  if (typeof value !== 'string') {\n    throw new Error(`${what} has a \\`${column}\\` that is neither text nor null: ${describe(value)}`);\n  }\n  return value;\n}\n\nexport function number(row: Row, column: string, what: string): number {\n  const value = row[column];\n  if (typeof value === 'bigint') return Number(value);\n  if (typeof value !== 'number' || !Number.isFinite(value)) {\n    throw new Error(`${what} has a \\`${column}\\` that is not a number: ${describe(value)}`);\n  }\n  return value;\n}\n\nfunction band(row: Row, what: string): Band {\n  const value = text(row, 'band', what);\n  if (!BANDS.includes(value as Band)) throw new Error(`${what} has an unknown band \"${value}\"`);\n  return value as Band;\n}\n\n/** Checked against `core`'s table, so a new tier does not become a rejected row. */\nfunction profile(row: Row, what: string): ProfileId {\n  const value = text(row, 'profile', what);\n  const known: unknown = profileById(value as ProfileId);\n  if (known === undefined) throw new Error(`${what} has an unknown profile \"${value}\"`);\n  return value as ProfileId;\n}\n\nexport function toObservation(row: Row): Observation {\n  const what = 'a stored observation';\n  const file = optionalText(row, 'file', what);\n\n  return {\n    project: text(row, 'project', what),\n    subject: text(row, 'subject', what),\n    component: text(row, 'component', what),\n    band: band(row, what),\n    hash: text(row, 'hash', what) as Digest,\n    profile: profile(row, what),\n    commit: text(row, 'commit', what),\n    run: text(row, 'run', what),\n    at: text(row, 'at', what),\n    accepted: number(row, 'accepted', what) !== 0,\n    ...(file !== undefined ? { file } : {}),\n  };\n}\n\nexport function toRunRecord(row: Row): RunRecord {\n  const what = 'a stored run';\n  const swept = row['swept'];\n\n  return {\n    project: text(row, 'project', what),\n    run: text(row, 'run', what),\n    commit: text(row, 'commit', what),\n    profile: profile(row, what),\n    at: text(row, 'at', what),\n    // Null stays absent. A run recorded before the column existed never said what\n    // it examined, and \"did not sweep\" is a claim — one that would make an old\n    // history look like a suite nobody ever swept.\n    ...(swept === null || swept === undefined ? {} : { swept: number(row, 'swept', what) !== 0 }),\n  };\n}\n\n/**\n * One occurrence of a subject failing to read the same way twice.\n *\n * Transcribed from `server/sqlite-rows.ts`, nullability included: a component\n * that could not be named comes back absent rather than as an empty string,\n * because empty would read as a component whose name is nothing.\n */\nexport function toInstability(row: Row): Instability {\n  const what = 'a stored instability';\n  const component = optionalText(row, 'component', what);\n  const stored = optionalText(row, 'band', what);\n  const absorbedBy = optionalText(row, 'absorbed_by', what);\n\n  return {\n    project: text(row, 'project', what),\n    subject: text(row, 'subject', what),\n    ...(component !== undefined ? { component } : {}),\n    ...(stored !== undefined ? { band: frequencyBand(stored, what) } : {}),\n    profile: profile(row, what),\n    commit: text(row, 'commit', what),\n    run: text(row, 'run', what),\n    at: text(row, 'at', what),\n    ...(absorbedBy !== undefined ? { absorbedBy } : {}),\n  };\n}\n\n/** A frequency band — how often that kind of thing changes — not a hash band. */\nfunction frequencyBand(value: string, what: string): FrequencyBand {\n  if (!FREQUENCY_BANDS.includes(value as FrequencyBand)) {\n    throw new Error(`${what} has an unknown frequency band \"${value}\"`);\n  }\n  return value as FrequencyBand;\n}\n\nexport function toApproval(row: Row): Approval {\n  const what = 'a stored approval';\n  const by = optionalText(row, 'approver', what);\n\n  return {\n    project: text(row, 'project', what),\n    subject: text(row, 'subject', what),\n    run: text(row, 'run', what),\n    at: text(row, 'at', what),\n    ...(by !== undefined ? { by } : {}),\n  };\n}\n\nexport function toTokenValue(row: Row): TokenValue {\n  const what = 'a stored token value';\n  return {\n    project: text(row, 'project', what),\n    token: text(row, 'token', what),\n    value: text(row, 'value', what),\n    commit: text(row, 'commit', what),\n    at: text(row, 'at', what),\n  };\n}\n\nfunction describe(value: unknown): string {\n  if (value === undefined) return 'absent';\n  if (value === null) return 'null';\n  return `${typeof value} (${String(value).slice(0, 60)})`;\n}\n"]}

package/dist/history.d.ts

@@ -0,0 +1,40 @@
+import { type HistoryBackend } from '@variance-authority/server';
+import { type D1Like } from './bindings.js';
+/**
+ * The history record, on D1.
+ *
+ * A second implementation of `HistoryBackend`, and deliberately a *transcription*
+ * of [`server/backend-sqlite.ts`](../../server/src/backend-sqlite.ts) rather than
+ * a fresh design. The seam exists so that replacing the engine changes one file
+ * and not what a row means; the way to honour that is for the two files to be
+ * boringly alike — same filters, same limit arithmetic, same correlated subquery
+ * for `arrived`, same refusal to cast a row it read back.
+ *
+ * **No arithmetic happens here.** Churn, journeys and reach are computed by
+ * `churnFrom`/`journeyFrom`/`reachFrom` in `@variance-authority/server`, over the
+ * rows this returns. That is what stops two backends disagreeing about what a
+ * number means, and it is why this file has no idea what a rate is.
+ *
+ * ## The two places D1 is not SQLite-in-a-process
+ *
+ * **No `BEGIN IMMEDIATE`.** Atomicity comes from `batch`, which D1 documents as
+ * one implicit transaction that rolls back entirely on failure. Every write here
+ * is one batch, so a run and its rows still land together or not at all.
+ *
+ * **No serialization around a read-then-write.** The SQLite backend takes the
+ * write lock before checking whether a run id is already registered; two Workers
+ * cannot. So the check is not what enforces lineage — the `WHERE NOT EXISTS`
+ * guard on the insert is, and the unique index behind it. The read survives only
+ * to produce a sentence naming both commits, because a caller who gets
+ * `UNIQUE constraint failed` has to come and read this file to find out what
+ * happened.
+ *
+ * ## What is next door
+ *
+ * Reading a stored value back is [`history-rows.ts`](./history-rows.ts), and it
+ * is a separate file for the same reason no arithmetic happens here: what a row
+ * is allowed to be is not a property of any one query, and this file knows
+ * nothing about it.
+ */
+export declare function createD1Backend(db: D1Like): HistoryBackend;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.js

@@ -0,0 +1,186 @@
+import { HistoryWriteConflict, } from '@variance-authority/server';
+import { requireD1 } from './bindings.js';
+import { areaFilter, componentFilter, currentRows, currentTokenRows, reachRows, slice, subjectFilter, tokenFilter, windowFilter, } from './history-queries.js';
+import { instant, text, toApproval, toInstability, toObservation, toRunRecord, toTokenValue, } from './history-rows.js';
+/**
+ * The history record, on D1.
+ *
+ * A second implementation of `HistoryBackend`, and deliberately a *transcription*
+ * of [`server/backend-sqlite.ts`](../../server/src/backend-sqlite.ts) rather than
+ * a fresh design. The seam exists so that replacing the engine changes one file
+ * and not what a row means; the way to honour that is for the two files to be
+ * boringly alike — same filters, same limit arithmetic, same correlated subquery
+ * for `arrived`, same refusal to cast a row it read back.
+ *
+ * **No arithmetic happens here.** Churn, journeys and reach are computed by
+ * `churnFrom`/`journeyFrom`/`reachFrom` in `@variance-authority/server`, over the
+ * rows this returns. That is what stops two backends disagreeing about what a
+ * number means, and it is why this file has no idea what a rate is.
+ *
+ * ## The two places D1 is not SQLite-in-a-process
+ *
+ * **No `BEGIN IMMEDIATE`.** Atomicity comes from `batch`, which D1 documents as
+ * one implicit transaction that rolls back entirely on failure. Every write here
+ * is one batch, so a run and its rows still land together or not at all.
+ *
+ * **No serialization around a read-then-write.** The SQLite backend takes the
+ * write lock before checking whether a run id is already registered; two Workers
+ * cannot. So the check is not what enforces lineage — the `WHERE NOT EXISTS`
+ * guard on the insert is, and the unique index behind it. The read survives only
+ * to produce a sentence naming both commits, because a caller who gets
+ * `UNIQUE constraint failed` has to come and read this file to find out what
+ * happened.
+ *
+ * ## What is next door
+ *
+ * Reading a stored value back is [`history-rows.ts`](./history-rows.ts), and it
+ * is a separate file for the same reason no arithmetic happens here: what a row
+ * is allowed to be is not a property of any one query, and this file knows
+ * nothing about it.
+ */
+export function createD1Backend(db) {
+    requireD1(db);
+    return {
+        async append(run, observations, tokens, instabilities = []) {
+            const registered = await registeredCommit(db, run);
+            if (registered !== null && registered !== run.commit)
+                throw conflict(run, registered);
+            const shipped = carriesAnApproval(observations);
+            const statements = [
+                // One statement, and it is the lineage rule rather than a convenience.
+                // If a row already exists for this `(project, run, profile)` with *this*
+                // commit, the `NOT EXISTS` is false and nothing is inserted — re-appending
+                // a run is legitimate, because a caller whose components were approved
+                // separately writes twice, and a run counted twice halves every rate
+                // derived from it forever.
+                //
+                // If a row exists with a *different* commit, the `NOT EXISTS` is true, the
+                // insert proceeds, and `runs_identity` refuses it — which aborts the whole
+                // batch. That is the only part of this that holds under two concurrent
+                // Workers, and it is why the check above is a message rather than a guard.
+                db
+                    .prepare(`INSERT INTO runs (project, run, "commit", profile, at, at_ms, swept)
+             SELECT ?, ?, ?, ?, ?, ?, ?
+              WHERE NOT EXISTS (
+                    SELECT 1 FROM runs
+                     WHERE project = ? AND run = ? AND profile = ? AND "commit" = ?)`)
+                    .bind(run.project, run.run, run.commit, run.profile, run.at, instant(run.at, 'run'), 
+                // NULL when the caller did not say. Transcribed with its reason: a
+                // run stored as having examined nothing puts a denominator under a
+                // flake rate that nobody measured.
+                run.swept === undefined ? null : run.swept ? 1 : 0, run.project, run.run, run.profile, run.commit),
+            ];
+            for (const row of observations) {
+                statements.push(db
+                    .prepare(`INSERT INTO observations
+                 (project, subject, component, band, hash, profile, "commit", run, at, at_ms,
+                  accepted, file)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .bind(row.project, row.subject, row.component, row.band, row.hash, row.profile, row.commit, row.run, row.at, instant(row.at, 'observation'), row.accepted ? 1 : 0, row.file ?? null));
+            }
+            for (const row of tokens) {
+                statements.push(db
+                    .prepare(`INSERT INTO token_values (project, token, value, "commit", at, at_ms, run, accepted)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .bind(row.project, row.token, row.value, row.commit, row.at, instant(row.at, 'token value'), run.run, shipped ? 1 : 0));
+            }
+            for (const row of instabilities) {
+                statements.push(db
+                    .prepare(`INSERT INTO instabilities
+                 (project, subject, component, band, profile, "commit", run, at, at_ms, absorbed_by)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .bind(row.project, row.subject, 
+                // Null, not the empty string: readings that could not be resolved
+                // to a component named nobody, which is not the same as the
+                // disagreement belonging to no component.
+                row.component ?? null, row.band ?? null, row.profile, row.commit, row.run, row.at, instant(row.at, 'instability'), row.absorbedBy ?? null));
+            }
+            try {
+                await db.batch(statements);
+            }
+            catch (error) {
+                // The guard above fired between the check and the write. Re-read so the
+                // operator gets the two commits rather than an index name.
+                const current = await registeredCommit(db, run).catch(() => null);
+                if (current !== null && current !== run.commit)
+                    throw conflict(run, current);
+                throw error;
+            }
+        },
+        async appendApprovals(approvals) {
+            if (approvals.length === 0)
+                return;
+            // `OR IGNORE` against `approvals_identity`, transcribed: approving twice is
+            // approving once, and a refusal would turn a second click into a failure.
+            await db.batch(approvals.map((approval) => db
+                .prepare(`INSERT OR IGNORE INTO approvals (project, subject, run, at, at_ms, approver)
+               VALUES (?, ?, ?, ?, ?, ?)`)
+                .bind(approval.project, approval.subject, approval.run, approval.at, instant(approval.at, 'approval'), approval.by ?? null)));
+        },
+        async approvalsOf(query) {
+            return slice(db, 'approvals', windowFilter(query), query.limit, toApproval);
+        },
+        async currentOf(query) {
+            return currentRows(db, query);
+        },
+        async currentTokens(query) {
+            return currentTokenRows(db, query);
+        },
+        async lastObservation(query) {
+            const filter = areaFilter(query);
+            const row = await db
+                .prepare(`SELECT * FROM observations WHERE 1 = 1${filter.sql} ORDER BY at_ms DESC, rowid DESC LIMIT 1`)
+                .bind(...filter.params)
+                .first();
+            return row === null ? null : toObservation(row);
+        },
+        async runsIn(query) {
+            return slice(db, 'runs', windowFilter(query), query.limit, toRunRecord);
+        },
+        async observationsOf(query) {
+            return slice(db, 'observations', componentFilter(query), query.limit, toObservation);
+        },
+        async instabilitiesOf(query) {
+            return slice(db, 'instabilities', subjectFilter(query), query.limit, toInstability);
+        },
+        async valuesOf(query) {
+            return slice(db, 'token_values', tokenFilter(query), query.limit, toTokenValue);
+        },
+        async reachOf(query) {
+            return reachRows(db, query);
+        },
+        /**
+         * Nothing to close.
+         *
+         * A binding is not a handle this code opened, and a Worker that closed one
+         * would break every other request sharing the isolate. Present because the
+         * interface has it, and empty for the same reason a stateless service has no
+         * shutdown.
+         */
+        async close() { },
+    };
+}
+async function registeredCommit(db, run) {
+    const row = await db
+        .prepare('SELECT "commit" FROM runs WHERE project = ? AND run = ? AND profile = ?')
+        .bind(run.project, run.run, run.profile)
+        .first();
+    return row === null ? null : text(row, 'commit', 'a stored run');
+}
+function conflict(run, recorded) {
+    return new HistoryWriteConflict(`run "${run.run}" of project "${run.project}" under ${run.profile} is already recorded ` +
+        `at commit ${recorded}; this write claims ${run.commit}. A run id that points at two ` +
+        'commits makes every question asked by lineage unanswerable, so the write is refused ' +
+        'rather than appended alongside it');
+}
+/**
+ * Whether the write itself already carried an approval.
+ *
+ * Transcribed from the SQLite backend, and provenance about the write in both.
+ * Which values a journey is made of is decided by `journeyFrom`, which both
+ * backends share and which asks the approvals table.
+ */
+function carriesAnApproval(observations) {
+    return observations.length === 0 || observations.some((row) => row.accepted);
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Approval,\n  Instability,\n  Observation,\n  RunRecord,\n  TokenValue,\n} from '@variance-authority/history';\nimport {\n  HistoryWriteConflict,\n  type HistoryBackend,\n  type ReachRows,\n  type Slice,\n} from '@variance-authority/server';\nimport { requireD1, type D1Like, type D1PreparedLike } from './bindings.js';\nimport {\n  areaFilter,\n  componentFilter,\n  currentRows,\n  currentTokenRows,\n  reachRows,\n  slice,\n  subjectFilter,\n  tokenFilter,\n  windowFilter,\n} from './history-queries.js';\nimport {\n  instant,\n  text,\n  toApproval,\n  toInstability,\n  toObservation,\n  toRunRecord,\n  toTokenValue,\n  type Row,\n} from './history-rows.js';\n\n/**\n * The history record, on D1.\n *\n * A second implementation of `HistoryBackend`, and deliberately a *transcription*\n * of [`server/backend-sqlite.ts`](../../server/src/backend-sqlite.ts) rather than\n * a fresh design. The seam exists so that replacing the engine changes one file\n * and not what a row means; the way to honour that is for the two files to be\n * boringly alike — same filters, same limit arithmetic, same correlated subquery\n * for `arrived`, same refusal to cast a row it read back.\n *\n * **No arithmetic happens here.** Churn, journeys and reach are computed by\n * `churnFrom`/`journeyFrom`/`reachFrom` in `@variance-authority/server`, over the\n * rows this returns. That is what stops two backends disagreeing about what a\n * number means, and it is why this file has no idea what a rate is.\n *\n * ## The two places D1 is not SQLite-in-a-process\n *\n * **No `BEGIN IMMEDIATE`.** Atomicity comes from `batch`, which D1 documents as\n * one implicit transaction that rolls back entirely on failure. Every write here\n * is one batch, so a run and its rows still land together or not at all.\n *\n * **No serialization around a read-then-write.** The SQLite backend takes the\n * write lock before checking whether a run id is already registered; two Workers\n * cannot. So the check is not what enforces lineage — the `WHERE NOT EXISTS`\n * guard on the insert is, and the unique index behind it. The read survives only\n * to produce a sentence naming both commits, because a caller who gets\n * `UNIQUE constraint failed` has to come and read this file to find out what\n * happened.\n *\n * ## What is next door\n *\n * Reading a stored value back is [`history-rows.ts`](./history-rows.ts), and it\n * is a separate file for the same reason no arithmetic happens here: what a row\n * is allowed to be is not a property of any one query, and this file knows\n * nothing about it.\n */\n\nexport function createD1Backend(db: D1Like): HistoryBackend {\n  requireD1(db);\n\n  return {\n    async append(run, observations, tokens, instabilities = []): Promise<void> {\n      const registered = await registeredCommit(db, run);\n      if (registered !== null && registered !== run.commit) throw conflict(run, registered);\n\n      const shipped = carriesAnApproval(observations);\n      const statements: D1PreparedLike[] = [\n        // One statement, and it is the lineage rule rather than a convenience.\n        // If a row already exists for this `(project, run, profile)` with *this*\n        // commit, the `NOT EXISTS` is false and nothing is inserted — re-appending\n        // a run is legitimate, because a caller whose components were approved\n        // separately writes twice, and a run counted twice halves every rate\n        // derived from it forever.\n        //\n        // If a row exists with a *different* commit, the `NOT EXISTS` is true, the\n        // insert proceeds, and `runs_identity` refuses it — which aborts the whole\n        // batch. That is the only part of this that holds under two concurrent\n        // Workers, and it is why the check above is a message rather than a guard.\n        db\n          .prepare(\n            `INSERT INTO runs (project, run, \"commit\", profile, at, at_ms, swept)\n             SELECT ?, ?, ?, ?, ?, ?, ?\n              WHERE NOT EXISTS (\n                    SELECT 1 FROM runs\n                     WHERE project = ? AND run = ? AND profile = ? AND \"commit\" = ?)`,\n          )\n          .bind(\n            run.project,\n            run.run,\n            run.commit,\n            run.profile,\n            run.at,\n            instant(run.at, 'run'),\n            // NULL when the caller did not say. Transcribed with its reason: a\n            // run stored as having examined nothing puts a denominator under a\n            // flake rate that nobody measured.\n            run.swept === undefined ? null : run.swept ? 1 : 0,\n            run.project,\n            run.run,\n            run.profile,\n            run.commit,\n          ),\n      ];\n\n      for (const row of observations) {\n        statements.push(\n          db\n            .prepare(\n              `INSERT INTO observations\n                 (project, subject, component, band, hash, profile, \"commit\", run, at, at_ms,\n                  accepted, file)\n               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n            )\n            .bind(\n              row.project,\n              row.subject,\n              row.component,\n              row.band,\n              row.hash,\n              row.profile,\n              row.commit,\n              row.run,\n              row.at,\n              instant(row.at, 'observation'),\n              row.accepted ? 1 : 0,\n              row.file ?? null,\n            ),\n        );\n      }\n\n      for (const row of tokens) {\n        statements.push(\n          db\n            .prepare(\n              `INSERT INTO token_values (project, token, value, \"commit\", at, at_ms, run, accepted)\n               VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,\n            )\n            .bind(\n              row.project,\n              row.token,\n              row.value,\n              row.commit,\n              row.at,\n              instant(row.at, 'token value'),\n              run.run,\n              shipped ? 1 : 0,\n            ),\n        );\n      }\n\n      for (const row of instabilities) {\n        statements.push(\n          db\n            .prepare(\n              `INSERT INTO instabilities\n                 (project, subject, component, band, profile, \"commit\", run, at, at_ms, absorbed_by)\n               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n            )\n            .bind(\n              row.project,\n              row.subject,\n              // Null, not the empty string: readings that could not be resolved\n              // to a component named nobody, which is not the same as the\n              // disagreement belonging to no component.\n              row.component ?? null,\n              row.band ?? null,\n              row.profile,\n              row.commit,\n              row.run,\n              row.at,\n              instant(row.at, 'instability'),\n              row.absorbedBy ?? null,\n            ),\n        );\n      }\n\n      try {\n        await db.batch(statements);\n      } catch (error) {\n        // The guard above fired between the check and the write. Re-read so the\n        // operator gets the two commits rather than an index name.\n        const current = await registeredCommit(db, run).catch(() => null);\n        if (current !== null && current !== run.commit) throw conflict(run, current);\n        throw error;\n      }\n    },\n\n    async appendApprovals(approvals): Promise<void> {\n      if (approvals.length === 0) return;\n\n      // `OR IGNORE` against `approvals_identity`, transcribed: approving twice is\n      // approving once, and a refusal would turn a second click into a failure.\n      await db.batch(\n        approvals.map((approval) =>\n          db\n            .prepare(\n              `INSERT OR IGNORE INTO approvals (project, subject, run, at, at_ms, approver)\n               VALUES (?, ?, ?, ?, ?, ?)`,\n            )\n            .bind(\n              approval.project,\n              approval.subject,\n              approval.run,\n              approval.at,\n              instant(approval.at, 'approval'),\n              approval.by ?? null,\n            ),\n        ),\n      );\n    },\n\n    async approvalsOf(query): Promise<Slice<Approval>> {\n      return slice(db, 'approvals', windowFilter(query), query.limit, toApproval);\n    },\n\n    async currentOf(query): Promise<readonly Observation[]> {\n      return currentRows(db, query);\n    },\n\n    async currentTokens(query): Promise<readonly TokenValue[]> {\n      return currentTokenRows(db, query);\n    },\n\n    async lastObservation(query): Promise<Observation | null> {\n      const filter = areaFilter(query);\n      const row = await db\n        .prepare(\n          `SELECT * FROM observations WHERE 1 = 1${filter.sql} ORDER BY at_ms DESC, rowid DESC LIMIT 1`,\n        )\n        .bind(...filter.params)\n        .first<Row>();\n\n      return row === null ? null : toObservation(row);\n    },\n\n    async runsIn(query): Promise<Slice<RunRecord>> {\n      return slice(db, 'runs', windowFilter(query), query.limit, toRunRecord);\n    },\n\n    async observationsOf(query): Promise<Slice<Observation>> {\n      return slice(db, 'observations', componentFilter(query), query.limit, toObservation);\n    },\n\n    async instabilitiesOf(query): Promise<Slice<Instability>> {\n      return slice(db, 'instabilities', subjectFilter(query), query.limit, toInstability);\n    },\n\n    async valuesOf(query): Promise<Slice<TokenValue>> {\n      return slice(db, 'token_values', tokenFilter(query), query.limit, toTokenValue);\n    },\n\n    async reachOf(query): Promise<ReachRows> {\n      return reachRows(db, query);\n    },\n\n    /**\n     * Nothing to close.\n     *\n     * A binding is not a handle this code opened, and a Worker that closed one\n     * would break every other request sharing the isolate. Present because the\n     * interface has it, and empty for the same reason a stateless service has no\n     * shutdown.\n     */\n    async close(): Promise<void> {},\n  };\n}\n\nasync function registeredCommit(db: D1Like, run: RunRecord): Promise<string | null> {\n  const row = await db\n    .prepare('SELECT \"commit\" FROM runs WHERE project = ? AND run = ? AND profile = ?')\n    .bind(run.project, run.run, run.profile)\n    .first<Row>();\n\n  return row === null ? null : text(row, 'commit', 'a stored run');\n}\n\nfunction conflict(run: RunRecord, recorded: string): HistoryWriteConflict {\n  return new HistoryWriteConflict(\n    `run \"${run.run}\" of project \"${run.project}\" under ${run.profile} is already recorded ` +\n      `at commit ${recorded}; this write claims ${run.commit}. A run id that points at two ` +\n      'commits makes every question asked by lineage unanswerable, so the write is refused ' +\n      'rather than appended alongside it',\n  );\n}\n\n/**\n * Whether the write itself already carried an approval.\n *\n * Transcribed from the SQLite backend, and provenance about the write in both.\n * Which values a journey is made of is decided by `journeyFrom`, which both\n * backends share and which asks the approvals table.\n */\nfunction carriesAnApproval(observations: readonly Observation[]): boolean {\n  return observations.length === 0 || observations.some((row) => row.accepted);\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The contract half — what a deployment is made of, with nothing that runs.
+ *
+ * The entrypoint an operator imports to declare their bindings and apply their
+ * schema. Everything that touches a request is behind `./store`, `./history`,
+ * `./review` and `./worker`, so a build script that only needs the SQL does not
+ * pull in the router, and a Worker that only serves baselines does not pull in
+ * React.
+ */
+export type { D1Like, D1PreparedLike, D1Value, R2Like, R2ObjectLike, TribunalBindings, } from './bindings.js';
+export { base64Of, bytesOf } from './bindings.js';
+export { INITIAL_VERSION, MIGRATIONS, SCHEMA, SCHEMA_VERSION, applySchema } from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * The contract half — what a deployment is made of, with nothing that runs.
+ *
+ * The entrypoint an operator imports to declare their bindings and apply their
+ * schema. Everything that touches a request is behind `./store`, `./history`,
+ * `./review` and `./worker`, so a build script that only needs the SQL does not
+ * pull in the router, and a Worker that only serves baselines does not pull in
+ * React.
+ */
+export { base64Of, bytesOf } from './bindings.js';
+export { INITIAL_VERSION, MIGRATIONS, SCHEMA, SCHEMA_VERSION, applySchema } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC","sourcesContent":["/**\n * The contract half — what a deployment is made of, with nothing that runs.\n *\n * The entrypoint an operator imports to declare their bindings and apply their\n * schema. Everything that touches a request is behind `./store`, `./history`,\n * `./review` and `./worker`, so a build script that only needs the SQL does not\n * pull in the router, and a Worker that only serves baselines does not pull in\n * React.\n */\n\nexport type {\n  D1Like,\n  D1PreparedLike,\n  D1Value,\n  R2Like,\n  R2ObjectLike,\n  TribunalBindings,\n} from './bindings.js';\nexport { base64Of, bytesOf } from './bindings.js';\nexport { INITIAL_VERSION, MIGRATIONS, SCHEMA, SCHEMA_VERSION, applySchema } from './schema.js';\n"]}

package/dist/migration-steps.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every shape this database has taken since it shipped, one entry per version.
+ *
+ * Apart from [`migrations.ts`](./migrations.js), which holds the frozen initial
+ * set, because the two are edited under opposite rules: that file must never
+ * change again, and this one only ever grows. Keeping them in one module meant
+ * every new table was appended a screen below a block carrying a comment saying
+ * it was frozen.
+ *
+ * The reading of both — which version they land on, and the batch that applies
+ * them — is in [`schema.ts`](./schema.js).
+ */
+/**
+ * One entry per version after `INITIAL_VERSION`, in order.
+ *
+ * A database that is already deployed cannot be given a new table by editing the
+ * statements that created it — `wrangler d1 migrations apply` tracks which files
+ * it has run, and a rewritten `0001` is a file it will never run again. So the
+ * initial set is frozen at the version it shipped at and every later shape is a
+ * step, generated into its own `.sql` beside it.
+ *
+ * Each step ends by writing its own version, so a database is never at a version
+ * whose shape it does not have — and a fresh database applying the initial set
+ * and every step in order arrives at exactly the same place as one that was
+ * deployed three versions ago.
+ *
+ * Additive only. A step that dropped or rewrote a column would be asking an
+ * append-only store to forget something, which is the one thing every trigger in
+ * this file exists to refuse.
+ */
+export declare const MIGRATIONS: readonly (readonly string[])[];
+//# sourceMappingURL=migration-steps.d.ts.map