@variance-authority/tribunal 0.1.0

package/dist/migrations.js

@@ -0,0 +1,283 @@
+/**
+ * The database as it first shipped, as statements rather than as a script.
+ *
+ * D1's `exec` accepts multiple statements only when each one is on a single
+ * line, which a trigger body cannot be, and splitting a script on `;` would cut
+ * every trigger in half — the semicolons inside `BEGIN … END` are part of the
+ * statement. So the schema is a list from the start, applied with `batch`, and
+ * there is no parser here that could get it wrong.
+ *
+ * ## Two halves
+ *
+ * The first half is this spec's own: baselines, the render cache, builds,
+ * per-subject verdicts, and decisions. The second half is
+ * [spec 0002](../../../docs/specs/0002-history-store.md)'s, and it is a
+ * deliberate transcription of
+ * [`server/backend-sqlite.ts`](../../server/src/backend-sqlite.ts) — the same
+ * columns, the same indexes, and above all the same append-only triggers with
+ * the same wording. Two backends that disagree about what a row is are two
+ * different records wearing one name, and the trigger messages are the part an
+ * operator actually reads, so they are copied rather than paraphrased.
+ *
+ * ## Two rules the tables enforce that no code has to remember
+ *
+ * **The identity partition is the primary key.** `baselines` is keyed by
+ * `(project, identity_digest, subject, label)`. A baseline written by one
+ * machine is not reachable as this machine's, because it is a different row —
+ * the same argument [ADR-0011](../../../docs/context/adr/0011-durable-and-ephemeral-retention.md)
+ * makes about the directory store's layout, and with the same absence of a check
+ * somebody could forget to write.
+ *
+ * **Instants are stored twice.** The original text, and its parsed
+ * milliseconds; every window is compared on the number. ISO-8601 sorts lexically
+ * only while every timestamp shares one offset, and a store fed by CI jobs in
+ * two regions does not.
+ */
+/**
+ * The version the frozen initial set lands a database on.
+ *
+ * Exported because the step list in
+ * [`migration-steps.ts`](./migration-steps.js) is indexed against it: step `i`
+ * lands on `INITIAL_VERSION + i + 1`. An operator holding a deployed database
+ * reads its `schema_version`, and without this the only way to line that number
+ * up with a step is to derive it from `SCHEMA_VERSION - MIGRATIONS.length`.
+ */
+export const INITIAL_VERSION = 3;
+/**
+ * What a run kept, and what a review decided, in order — as this database first
+ * shipped.
+ *
+ * Order matters: tables before their indexes, and both before the triggers that
+ * reference them.
+ *
+ * Frozen at {@link INITIAL_VERSION}. Everything since is a step in
+ * [`migration-steps.ts`](./migration-steps.js), for the reason given there; a
+ * new table added here would reach a fresh deployment and no existing one.
+ */
+export const INITIAL = [
+    `CREATE TABLE schema_version (
+     version INTEGER NOT NULL
+   ) STRICT`,
+    `INSERT INTO schema_version (version) VALUES (${INITIAL_VERSION})`,
+    // ---------------------------------------------------------------- baselines
+    // `label` is NOT NULL with '' standing for absent, and an empty label is
+    // refused at the door (see `store.ts`). SQLite permits NULL in the columns of
+    // an ordinary PRIMARY KEY, which would make two unlabelled baselines for one
+    // subject two rows that never collide — the uniqueness that stops a second
+    // `put` overwriting the first would silently not exist.
+    `CREATE TABLE baselines (
+     project         TEXT NOT NULL,
+     identity_digest TEXT NOT NULL,
+     subject         TEXT NOT NULL,
+     label           TEXT NOT NULL,
+     identity        TEXT NOT NULL,
+     document_digest TEXT NOT NULL,
+     width           INTEGER NOT NULL,
+     height          INTEGER NOT NULL,
+     missing_fonts   TEXT NOT NULL,
+     object_key      TEXT NOT NULL,
+     at              TEXT NOT NULL,
+     at_ms           INTEGER NOT NULL,
+     PRIMARY KEY (project, identity_digest, subject, label)
+   ) STRICT`,
+    // The sibling scan. `find` must be able to say "we have seen this, on a
+    // machine you are not", which is a lookup across identities for one key —
+    // a different leading column from the primary key's, so it needs its own index
+    // or every wrong-machine run becomes a full table scan.
+    `CREATE INDEX baselines_across_identities ON baselines (project, subject, label, at_ms DESC)`,
+    `CREATE TABLE render_cache (
+     project         TEXT NOT NULL,
+     identity_digest TEXT NOT NULL,
+     document_digest TEXT NOT NULL,
+     identity        TEXT NOT NULL,
+     width           INTEGER NOT NULL,
+     height          INTEGER NOT NULL,
+     missing_fonts   TEXT NOT NULL,
+     object_key      TEXT NOT NULL,
+     at_ms           INTEGER NOT NULL,
+     PRIMARY KEY (project, identity_digest, document_digest)
+   ) STRICT`,
+    // ------------------------------------------------------------------- review
+    // `says_not_observed` is a flag about the *writer*, not about the run: `1`
+    // means the report stated its coverage list, `0` means it never said. A report
+    // that skipped nothing and a report that declined to say are different claims,
+    // and collapsing them lets "nothing to review" be printed on the authority of a
+    // writer that never looked (`report`'s `notObserved`).
+    `CREATE TABLE builds (
+     project           TEXT NOT NULL,
+     build             TEXT NOT NULL,
+     "commit"          TEXT NOT NULL,
+     branch            TEXT,
+     intent            TEXT,
+     at                TEXT NOT NULL,
+     at_ms             INTEGER NOT NULL,
+     identity          TEXT NOT NULL,
+     identity_digest   TEXT NOT NULL,
+     retention         TEXT NOT NULL,
+     run_version       INTEGER NOT NULL,
+     says_not_observed INTEGER NOT NULL,
+     PRIMARY KEY (project, build)
+   ) STRICT`,
+    `CREATE INDEX builds_recent ON builds (project, at_ms DESC)`,
+    // No `label` column, and that is the report's shape rather than an omission:
+    // `ObservationRecord` carries a subject and no label, so a build cannot
+    // distinguish two images of one subject. `baselines` can, because `put` can.
+    // The day a run reports labels this table grows a column and the promotion path
+    // stops hard-coding ''.
+    // The `candidate_*` columns are what makes approval a promotion rather than a
+    // recording. A baseline is an image *plus* the document digest it was painted
+    // from and the identity that painted it — the sidecar the cheap `describe` path
+    // answers from. A review surface holding only pixels could not write one, so it
+    // would have to re-render to approve, and a surface that can render can record
+    // something nobody looked at. They are nullable because a build may carry a
+    // verdict for a subject whose image it did not keep; approving that subject is
+    // refused rather than invented.
+    `CREATE TABLE build_subjects (
+     project        TEXT NOT NULL,
+     build          TEXT NOT NULL,
+     subject        TEXT NOT NULL,
+     verdict        TEXT NOT NULL,
+     because        TEXT NOT NULL,
+     changed_pixels INTEGER NOT NULL,
+     regions        TEXT NOT NULL,
+     truncated      TEXT,
+     missing_fonts  TEXT,
+     findings       TEXT,
+     before_key     TEXT,
+     after_key      TEXT,
+     diff_key       TEXT,
+     candidate_document_digest TEXT,
+     candidate_width           INTEGER,
+     candidate_height          INTEGER,
+     candidate_missing_fonts   TEXT,
+     PRIMARY KEY (project, build, subject)
+   ) STRICT`,
+    `CREATE TABLE build_not_observed (
+     project TEXT NOT NULL,
+     build   TEXT NOT NULL,
+     subject TEXT NOT NULL,
+     kind    TEXT NOT NULL,
+     because TEXT NOT NULL,
+     PRIMARY KEY (project, build, subject)
+   ) STRICT`,
+    // Append-only, like everything else that records a fact about a moment. A
+    // reviewer who approves and then changes their mind leaves two rows; the second
+    // decision is only reviewable because the first one is still there.
+    `CREATE TABLE decisions (
+     seq       INTEGER PRIMARY KEY AUTOINCREMENT,
+     project   TEXT NOT NULL,
+     build     TEXT NOT NULL,
+     subject   TEXT NOT NULL,
+     decision  TEXT NOT NULL,
+     decided_by TEXT NOT NULL,
+     note      TEXT,
+     at        TEXT NOT NULL,
+     at_ms     INTEGER NOT NULL
+   ) STRICT`,
+    `CREATE INDEX decisions_latest ON decisions (project, build, subject, seq DESC)`,
+    `CREATE TRIGGER decisions_are_append_only BEFORE UPDATE ON decisions BEGIN
+     SELECT RAISE(ABORT, 'decisions are append-only: a rewritten decision erases the review it replaced, and the earlier one is what makes the later one reviewable');
+   END`,
+    `CREATE TRIGGER decisions_are_permanent BEFORE DELETE ON decisions BEGIN
+     SELECT RAISE(ABORT, 'decisions are append-only: a deleted approval leaves a promoted baseline nobody can attribute to anyone');
+   END`,
+    // ------------------------------------------------------------------ history
+    // Transcribed from `server/backend-sqlite.ts`. Same columns, same indexes,
+    // same trigger wording — see the note at the top of this file.
+    `CREATE TABLE runs (
+     project  TEXT NOT NULL,
+     run      TEXT NOT NULL,
+     "commit" TEXT NOT NULL,
+     profile  TEXT NOT NULL,
+     at       TEXT NOT NULL,
+     at_ms    INTEGER NOT NULL,
+     -- Nullable, and the null is load-bearing: a run that never said what it
+     -- examined must not be read as one that examined nothing, because that
+     -- number becomes the denominator of a flake rate.
+     swept    INTEGER
+   ) STRICT`,
+    `CREATE UNIQUE INDEX runs_identity ON runs (project, run, profile)`,
+    `CREATE INDEX runs_window ON runs (project, at_ms)`,
+    `CREATE TABLE observations (
+     project   TEXT NOT NULL,
+     subject   TEXT NOT NULL,
+     component TEXT NOT NULL,
+     band      TEXT NOT NULL,
+     hash      TEXT NOT NULL,
+     profile   TEXT NOT NULL,
+     "commit"  TEXT NOT NULL,
+     run       TEXT NOT NULL,
+     at        TEXT NOT NULL,
+     at_ms     INTEGER NOT NULL,
+     accepted  INTEGER NOT NULL,
+     file      TEXT
+   ) STRICT`,
+    `CREATE INDEX observations_area      ON observations (project, subject, component, band, at_ms)`,
+    `CREATE INDEX observations_component ON observations (project, component, at_ms)`,
+    `CREATE INDEX observations_reach     ON observations (project, component, subject, at_ms)`,
+    `CREATE TABLE token_values (
+     project  TEXT NOT NULL,
+     token    TEXT NOT NULL,
+     value    TEXT NOT NULL,
+     "commit" TEXT NOT NULL,
+     at       TEXT NOT NULL,
+     at_ms    INTEGER NOT NULL,
+     run      TEXT NOT NULL,
+     accepted INTEGER NOT NULL
+   ) STRICT`,
+    `CREATE INDEX token_values_journey ON token_values (project, token, at_ms)`,
+    `CREATE TABLE instabilities (
+     project     TEXT NOT NULL,
+     subject     TEXT NOT NULL,
+     component   TEXT,
+     band        TEXT,
+     profile     TEXT NOT NULL,
+     "commit"    TEXT NOT NULL,
+     run         TEXT NOT NULL,
+     at          TEXT NOT NULL,
+     at_ms       INTEGER NOT NULL,
+     absorbed_by TEXT
+   ) STRICT`,
+    `CREATE INDEX instabilities_subject ON instabilities (project, subject, at_ms)`,
+    `CREATE TABLE approvals (
+     project  TEXT NOT NULL,
+     subject  TEXT NOT NULL,
+     run      TEXT NOT NULL,
+     at       TEXT NOT NULL,
+     at_ms    INTEGER NOT NULL,
+     approver TEXT
+   ) STRICT`,
+    `CREATE UNIQUE INDEX approvals_identity ON approvals (project, subject, run)`,
+    `CREATE INDEX approvals_window ON approvals (project, at_ms)`,
+    `CREATE TRIGGER runs_are_append_only BEFORE UPDATE ON runs BEGIN
+     SELECT RAISE(ABORT, 'runs are append-only: a recorded run is a fact about a moment, and rewriting one changes a denominator somebody already read');
+   END`,
+    `CREATE TRIGGER runs_are_permanent BEFORE DELETE ON runs BEGIN
+     SELECT RAISE(ABORT, 'runs are append-only: deleting a quiet run inflates every rate computed over its window');
+   END`,
+    `CREATE TRIGGER observations_are_append_only BEFORE UPDATE ON observations BEGIN
+     SELECT RAISE(ABORT, 'observations are append-only: two hashes for one key are two rows, and an update is the merge this store exists to avoid');
+   END`,
+    `CREATE TRIGGER observations_are_permanent BEFORE DELETE ON observations BEGIN
+     SELECT RAISE(ABORT, 'observations are append-only: a deleted change is a change nobody can ever ask about again');
+   END`,
+    `CREATE TRIGGER token_values_are_append_only BEFORE UPDATE ON token_values BEGIN
+     SELECT RAISE(ABORT, 'token values are append-only: a rewritten value breaks the journey that was the reason for keeping it');
+   END`,
+    `CREATE TRIGGER token_values_are_permanent BEFORE DELETE ON token_values BEGIN
+     SELECT RAISE(ABORT, 'token values are append-only: a removed step turns a drift total into a lower bound with nothing saying so');
+   END`,
+    `CREATE TRIGGER instabilities_are_append_only BEFORE UPDATE ON instabilities BEGIN
+     SELECT RAISE(ABORT, 'instabilities are append-only: an occurrence is a fact about one run, and rewriting one changes a rate somebody already acted on');
+   END`,
+    `CREATE TRIGGER instabilities_are_permanent BEFORE DELETE ON instabilities BEGIN
+     SELECT RAISE(ABORT, 'instabilities are append-only: deleting an occurrence is how a flake that was fixed becomes a flake that never happened');
+   END`,
+    `CREATE TRIGGER approvals_are_append_only BEFORE UPDATE ON approvals BEGIN
+     SELECT RAISE(ABORT, 'approvals are append-only: a rewritten acceptance changes what a reviewer agreed to after they agreed to it');
+   END`,
+    `CREATE TRIGGER approvals_are_permanent BEFORE DELETE ON approvals BEGIN
+     SELECT RAISE(ABORT, 'approvals are append-only: a deleted acceptance turns a reviewed change back into an unreviewed one, and every drift total over it drops');
+   END`,
+];
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAsB;IACxC;;YAEU;IACV,gDAAgD,eAAe,GAAG;IAElE,6EAA6E;IAE7E,yEAAyE;IACzE,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,wDAAwD;IACxD;;;;;;;;;;;;;;YAcU;IAEV,wEAAwE;IACxE,0EAA0E;IAC1E,+EAA+E;IAC/E,wDAAwD;IACxD,6FAA6F;IAE7F;;;;;;;;;;;YAWU;IAEV,6EAA6E;IAE7E,2EAA2E;IAC3E,+EAA+E;IAC/E,+EAA+E;IAC/E,gFAAgF;IAChF,uDAAuD;IACvD;;;;;;;;;;;;;;YAcU;IACV,4DAA4D;IAE5D,6EAA6E;IAC7E,wEAAwE;IACxE,6EAA6E;IAC7E,gFAAgF;IAChF,wBAAwB;IACxB,8EAA8E;IAC9E,8EAA8E;IAC9E,gFAAgF;IAChF,gFAAgF;IAChF,+EAA+E;IAC/E,4EAA4E;IAC5E,+EAA+E;IAC/E,gCAAgC;IAChC;;;;;;;;;;;;;;;;;;;YAmBU;IAEV;;;;;;;YAOU;IAEV,0EAA0E;IAC1E,gFAAgF;IAChF,oEAAoE;IACpE;;;;;;;;;;YAUU;IACV,gFAAgF;IAEhF;;OAEK;IACL;;OAEK;IAEL,6EAA6E;IAC7E,2EAA2E;IAC3E,+DAA+D;IAE/D;;;;;;;;;;;YAWU;IACV,mEAAmE;IACnE,mDAAmD;IAEnD;;;;;;;;;;;;;YAaU;IACV,gGAAgG;IAChG,iFAAiF;IACjF,0FAA0F;IAE1F;;;;;;;;;YASU;IACV,2EAA2E;IAE3E;;;;;;;;;;;YAWU;IACV,+EAA+E;IAE/E;;;;;;;YAOU;IACV,6EAA6E;IAC7E,6DAA6D;IAE7D;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;IACL;;OAEK;CACN,CAAC","sourcesContent":["/**\n * The database as it first shipped, as statements rather than as a script.\n *\n * D1's `exec` accepts multiple statements only when each one is on a single\n * line, which a trigger body cannot be, and splitting a script on `;` would cut\n * every trigger in half — the semicolons inside `BEGIN … END` are part of the\n * statement. So the schema is a list from the start, applied with `batch`, and\n * there is no parser here that could get it wrong.\n *\n * ## Two halves\n *\n * The first half is this spec's own: baselines, the render cache, builds,\n * per-subject verdicts, and decisions. The second half is\n * [spec 0002](../../../docs/specs/0002-history-store.md)'s, and it is a\n * deliberate transcription of\n * [`server/backend-sqlite.ts`](../../server/src/backend-sqlite.ts) — the same\n * columns, the same indexes, and above all the same append-only triggers with\n * the same wording. Two backends that disagree about what a row is are two\n * different records wearing one name, and the trigger messages are the part an\n * operator actually reads, so they are copied rather than paraphrased.\n *\n * ## Two rules the tables enforce that no code has to remember\n *\n * **The identity partition is the primary key.** `baselines` is keyed by\n * `(project, identity_digest, subject, label)`. A baseline written by one\n * machine is not reachable as this machine's, because it is a different row —\n * the same argument [ADR-0011](../../../docs/context/adr/0011-durable-and-ephemeral-retention.md)\n * makes about the directory store's layout, and with the same absence of a check\n * somebody could forget to write.\n *\n * **Instants are stored twice.** The original text, and its parsed\n * milliseconds; every window is compared on the number. ISO-8601 sorts lexically\n * only while every timestamp shares one offset, and a store fed by CI jobs in\n * two regions does not.\n */\n\n\n/**\n * The version the frozen initial set lands a database on.\n *\n * Exported because the step list in\n * [`migration-steps.ts`](./migration-steps.js) is indexed against it: step `i`\n * lands on `INITIAL_VERSION + i + 1`. An operator holding a deployed database\n * reads its `schema_version`, and without this the only way to line that number\n * up with a step is to derive it from `SCHEMA_VERSION - MIGRATIONS.length`.\n */\nexport const INITIAL_VERSION = 3;\n\n/**\n * What a run kept, and what a review decided, in order — as this database first\n * shipped.\n *\n * Order matters: tables before their indexes, and both before the triggers that\n * reference them.\n *\n * Frozen at {@link INITIAL_VERSION}. Everything since is a step in\n * [`migration-steps.ts`](./migration-steps.js), for the reason given there; a\n * new table added here would reach a fresh deployment and no existing one.\n */\nexport const INITIAL: readonly string[] = [\n  `CREATE TABLE schema_version (\n     version INTEGER NOT NULL\n   ) STRICT`,\n  `INSERT INTO schema_version (version) VALUES (${INITIAL_VERSION})`,\n\n  // ---------------------------------------------------------------- baselines\n\n  // `label` is NOT NULL with '' standing for absent, and an empty label is\n  // refused at the door (see `store.ts`). SQLite permits NULL in the columns of\n  // an ordinary PRIMARY KEY, which would make two unlabelled baselines for one\n  // subject two rows that never collide — the uniqueness that stops a second\n  // `put` overwriting the first would silently not exist.\n  `CREATE TABLE baselines (\n     project         TEXT NOT NULL,\n     identity_digest TEXT NOT NULL,\n     subject         TEXT NOT NULL,\n     label           TEXT NOT NULL,\n     identity        TEXT NOT NULL,\n     document_digest TEXT NOT NULL,\n     width           INTEGER NOT NULL,\n     height          INTEGER NOT NULL,\n     missing_fonts   TEXT NOT NULL,\n     object_key      TEXT NOT NULL,\n     at              TEXT NOT NULL,\n     at_ms           INTEGER NOT NULL,\n     PRIMARY KEY (project, identity_digest, subject, label)\n   ) STRICT`,\n\n  // The sibling scan. `find` must be able to say \"we have seen this, on a\n  // machine you are not\", which is a lookup across identities for one key —\n  // a different leading column from the primary key's, so it needs its own index\n  // or every wrong-machine run becomes a full table scan.\n  `CREATE INDEX baselines_across_identities ON baselines (project, subject, label, at_ms DESC)`,\n\n  `CREATE TABLE render_cache (\n     project         TEXT NOT NULL,\n     identity_digest TEXT NOT NULL,\n     document_digest TEXT NOT NULL,\n     identity        TEXT NOT NULL,\n     width           INTEGER NOT NULL,\n     height          INTEGER NOT NULL,\n     missing_fonts   TEXT NOT NULL,\n     object_key      TEXT NOT NULL,\n     at_ms           INTEGER NOT NULL,\n     PRIMARY KEY (project, identity_digest, document_digest)\n   ) STRICT`,\n\n  // ------------------------------------------------------------------- review\n\n  // `says_not_observed` is a flag about the *writer*, not about the run: `1`\n  // means the report stated its coverage list, `0` means it never said. A report\n  // that skipped nothing and a report that declined to say are different claims,\n  // and collapsing them lets \"nothing to review\" be printed on the authority of a\n  // writer that never looked (`report`'s `notObserved`).\n  `CREATE TABLE builds (\n     project           TEXT NOT NULL,\n     build             TEXT NOT NULL,\n     \"commit\"          TEXT NOT NULL,\n     branch            TEXT,\n     intent            TEXT,\n     at                TEXT NOT NULL,\n     at_ms             INTEGER NOT NULL,\n     identity          TEXT NOT NULL,\n     identity_digest   TEXT NOT NULL,\n     retention         TEXT NOT NULL,\n     run_version       INTEGER NOT NULL,\n     says_not_observed INTEGER NOT NULL,\n     PRIMARY KEY (project, build)\n   ) STRICT`,\n  `CREATE INDEX builds_recent ON builds (project, at_ms DESC)`,\n\n  // No `label` column, and that is the report's shape rather than an omission:\n  // `ObservationRecord` carries a subject and no label, so a build cannot\n  // distinguish two images of one subject. `baselines` can, because `put` can.\n  // The day a run reports labels this table grows a column and the promotion path\n  // stops hard-coding ''.\n  // The `candidate_*` columns are what makes approval a promotion rather than a\n  // recording. A baseline is an image *plus* the document digest it was painted\n  // from and the identity that painted it — the sidecar the cheap `describe` path\n  // answers from. A review surface holding only pixels could not write one, so it\n  // would have to re-render to approve, and a surface that can render can record\n  // something nobody looked at. They are nullable because a build may carry a\n  // verdict for a subject whose image it did not keep; approving that subject is\n  // refused rather than invented.\n  `CREATE TABLE build_subjects (\n     project        TEXT NOT NULL,\n     build          TEXT NOT NULL,\n     subject        TEXT NOT NULL,\n     verdict        TEXT NOT NULL,\n     because        TEXT NOT NULL,\n     changed_pixels INTEGER NOT NULL,\n     regions        TEXT NOT NULL,\n     truncated      TEXT,\n     missing_fonts  TEXT,\n     findings       TEXT,\n     before_key     TEXT,\n     after_key      TEXT,\n     diff_key       TEXT,\n     candidate_document_digest TEXT,\n     candidate_width           INTEGER,\n     candidate_height          INTEGER,\n     candidate_missing_fonts   TEXT,\n     PRIMARY KEY (project, build, subject)\n   ) STRICT`,\n\n  `CREATE TABLE build_not_observed (\n     project TEXT NOT NULL,\n     build   TEXT NOT NULL,\n     subject TEXT NOT NULL,\n     kind    TEXT NOT NULL,\n     because TEXT NOT NULL,\n     PRIMARY KEY (project, build, subject)\n   ) STRICT`,\n\n  // Append-only, like everything else that records a fact about a moment. A\n  // reviewer who approves and then changes their mind leaves two rows; the second\n  // decision is only reviewable because the first one is still there.\n  `CREATE TABLE decisions (\n     seq       INTEGER PRIMARY KEY AUTOINCREMENT,\n     project   TEXT NOT NULL,\n     build     TEXT NOT NULL,\n     subject   TEXT NOT NULL,\n     decision  TEXT NOT NULL,\n     decided_by TEXT NOT NULL,\n     note      TEXT,\n     at        TEXT NOT NULL,\n     at_ms     INTEGER NOT NULL\n   ) STRICT`,\n  `CREATE INDEX decisions_latest ON decisions (project, build, subject, seq DESC)`,\n\n  `CREATE TRIGGER decisions_are_append_only BEFORE UPDATE ON decisions BEGIN\n     SELECT RAISE(ABORT, 'decisions are append-only: a rewritten decision erases the review it replaced, and the earlier one is what makes the later one reviewable');\n   END`,\n  `CREATE TRIGGER decisions_are_permanent BEFORE DELETE ON decisions BEGIN\n     SELECT RAISE(ABORT, 'decisions are append-only: a deleted approval leaves a promoted baseline nobody can attribute to anyone');\n   END`,\n\n  // ------------------------------------------------------------------ history\n  // Transcribed from `server/backend-sqlite.ts`. Same columns, same indexes,\n  // same trigger wording — see the note at the top of this file.\n\n  `CREATE TABLE runs (\n     project  TEXT NOT NULL,\n     run      TEXT NOT NULL,\n     \"commit\" TEXT NOT NULL,\n     profile  TEXT NOT NULL,\n     at       TEXT NOT NULL,\n     at_ms    INTEGER NOT NULL,\n     -- Nullable, and the null is load-bearing: a run that never said what it\n     -- examined must not be read as one that examined nothing, because that\n     -- number becomes the denominator of a flake rate.\n     swept    INTEGER\n   ) STRICT`,\n  `CREATE UNIQUE INDEX runs_identity ON runs (project, run, profile)`,\n  `CREATE INDEX runs_window ON runs (project, at_ms)`,\n\n  `CREATE TABLE observations (\n     project   TEXT NOT NULL,\n     subject   TEXT NOT NULL,\n     component TEXT NOT NULL,\n     band      TEXT NOT NULL,\n     hash      TEXT NOT NULL,\n     profile   TEXT NOT NULL,\n     \"commit\"  TEXT NOT NULL,\n     run       TEXT NOT NULL,\n     at        TEXT NOT NULL,\n     at_ms     INTEGER NOT NULL,\n     accepted  INTEGER NOT NULL,\n     file      TEXT\n   ) STRICT`,\n  `CREATE INDEX observations_area      ON observations (project, subject, component, band, at_ms)`,\n  `CREATE INDEX observations_component ON observations (project, component, at_ms)`,\n  `CREATE INDEX observations_reach     ON observations (project, component, subject, at_ms)`,\n\n  `CREATE TABLE token_values (\n     project  TEXT NOT NULL,\n     token    TEXT NOT NULL,\n     value    TEXT NOT NULL,\n     \"commit\" TEXT NOT NULL,\n     at       TEXT NOT NULL,\n     at_ms    INTEGER NOT NULL,\n     run      TEXT NOT NULL,\n     accepted INTEGER NOT NULL\n   ) STRICT`,\n  `CREATE INDEX token_values_journey ON token_values (project, token, at_ms)`,\n\n  `CREATE TABLE instabilities (\n     project     TEXT NOT NULL,\n     subject     TEXT NOT NULL,\n     component   TEXT,\n     band        TEXT,\n     profile     TEXT NOT NULL,\n     \"commit\"    TEXT NOT NULL,\n     run         TEXT NOT NULL,\n     at          TEXT NOT NULL,\n     at_ms       INTEGER NOT NULL,\n     absorbed_by TEXT\n   ) STRICT`,\n  `CREATE INDEX instabilities_subject ON instabilities (project, subject, at_ms)`,\n\n  `CREATE TABLE approvals (\n     project  TEXT NOT NULL,\n     subject  TEXT NOT NULL,\n     run      TEXT NOT NULL,\n     at       TEXT NOT NULL,\n     at_ms    INTEGER NOT NULL,\n     approver TEXT\n   ) STRICT`,\n  `CREATE UNIQUE INDEX approvals_identity ON approvals (project, subject, run)`,\n  `CREATE INDEX approvals_window ON approvals (project, at_ms)`,\n\n  `CREATE TRIGGER runs_are_append_only BEFORE UPDATE ON runs BEGIN\n     SELECT RAISE(ABORT, 'runs are append-only: a recorded run is a fact about a moment, and rewriting one changes a denominator somebody already read');\n   END`,\n  `CREATE TRIGGER runs_are_permanent BEFORE DELETE ON runs BEGIN\n     SELECT RAISE(ABORT, 'runs are append-only: deleting a quiet run inflates every rate computed over its window');\n   END`,\n  `CREATE TRIGGER observations_are_append_only BEFORE UPDATE ON observations BEGIN\n     SELECT RAISE(ABORT, 'observations are append-only: two hashes for one key are two rows, and an update is the merge this store exists to avoid');\n   END`,\n  `CREATE TRIGGER observations_are_permanent BEFORE DELETE ON observations BEGIN\n     SELECT RAISE(ABORT, 'observations are append-only: a deleted change is a change nobody can ever ask about again');\n   END`,\n  `CREATE TRIGGER token_values_are_append_only BEFORE UPDATE ON token_values BEGIN\n     SELECT RAISE(ABORT, 'token values are append-only: a rewritten value breaks the journey that was the reason for keeping it');\n   END`,\n  `CREATE TRIGGER token_values_are_permanent BEFORE DELETE ON token_values BEGIN\n     SELECT RAISE(ABORT, 'token values are append-only: a removed step turns a drift total into a lower bound with nothing saying so');\n   END`,\n  `CREATE TRIGGER instabilities_are_append_only BEFORE UPDATE ON instabilities BEGIN\n     SELECT RAISE(ABORT, 'instabilities are append-only: an occurrence is a fact about one run, and rewriting one changes a rate somebody already acted on');\n   END`,\n  `CREATE TRIGGER instabilities_are_permanent BEFORE DELETE ON instabilities BEGIN\n     SELECT RAISE(ABORT, 'instabilities are append-only: deleting an occurrence is how a flake that was fixed becomes a flake that never happened');\n   END`,\n  `CREATE TRIGGER approvals_are_append_only BEFORE UPDATE ON approvals BEGIN\n     SELECT RAISE(ABORT, 'approvals are append-only: a rewritten acceptance changes what a reviewer agreed to after they agreed to it');\n   END`,\n  `CREATE TRIGGER approvals_are_permanent BEFORE DELETE ON approvals BEGIN\n     SELECT RAISE(ABORT, 'approvals are append-only: a deleted acceptance turns a reviewed change back into an unreviewed one, and every drift total over it drops');\n   END`,\n];\n"]}

package/dist/next.d.ts

@@ -0,0 +1,94 @@
+import type { Tribunal } from './worker.js';
+/**
+ * The Worker, mounted inside a Next.js App Router app — which on Cloudflare means
+ * [vinext](https://vinext.io).
+ *
+ * The whole adapter is one idea: a Next route handler is
+ * `(Request) => Response | Promise<Response>`, and so is
+ * {@link Tribunal.fetch}. What is left is a mount prefix to strip and one
+ * decision the operator has to make, below.
+ *
+ * ```ts
+ * // app/variance/[[...path]]/route.ts
+ * import { createTribunal } from '@variance-authority/tribunal/worker';
+ * import { createTribunalRoutes } from '@variance-authority/tribunal/next';
+ *
+ * const worker = createTribunal({
+ *   db: process.env.DB, bucket: process.env.BUCKET, project: 'todomvc',
+ *   ingestToken: process.env.VARIANCE_INGEST_TOKEN!,
+ *   reviewToken: process.env.VARIANCE_REVIEW_TOKEN!,
+ * });
+ *
+ * export const { GET, POST, HEAD } = createTribunalRoutes(worker, {
+ *   basePath: '/variance',
+ *   authorize: async (request) => (await isSignedIn(request)) ? 'review' : null,
+ * });
+ * ```
+ *
+ * ## The one decision this adapter does not make for you
+ *
+ * A browser rendering the review surface must not be handed the review token —
+ * a token in a page is a token in everybody's devtools, and this one **promotes
+ * baselines**. So the token stays on the server and the handler attaches it,
+ * which means the handler, not the token, is now the gate.
+ *
+ * `authorize` is that gate, and it has no default. Returning `'review'` for every
+ * request would publish an approve button to the internet, and a package that
+ * shipped that as a convenience would be shipping the failure. An operator who
+ * genuinely wants the surface open writes `() => 'review'` themselves, in their
+ * own file, where the next person reviewing that repository can see it.
+ *
+ * A request that `authorize` refuses is answered 401 here, without reaching the
+ * Worker — so the app's own session and the deployment's tokens stay two
+ * separate things, and neither is asked to be the other.
+ */
+export interface TribunalRouteOptions {
+    /**
+     * Where the route is mounted, e.g. `/variance` for `app/variance/[[...path]]`.
+     *
+     * Stripped before the request reaches the Worker, which knows only its own
+     * paths. Without it every request would arrive as `/variance/review/builds`
+     * and 404 against a route table that has never heard of the prefix.
+     */
+    readonly basePath?: string;
+    /**
+     * Which capability this request is allowed, decided by the operator's own app.
+     *
+     * `null` is a 401. There is no default — see the note above.
+     */
+    authorize(request: Request): Promise<'ingest' | 'review' | null> | 'ingest' | 'review' | null;
+    /**
+     * The tokens the Worker was constructed with.
+     *
+     * Passed again rather than read off the worker, because a `Tribunal` is
+     * deliberately a `fetch` handler and nothing else: a handler that could be
+     * asked for its own secrets is a handler that can leak them by being logged.
+     */
+    readonly tokens: {
+        readonly ingest: string;
+        readonly review: string;
+    };
+}
+/**
+ * The three method exports a Next.js route file needs.
+ *
+ * `GET`, `POST` and `HEAD` are the same handler; the framework wants them named.
+ * Spread them straight out of a route module — `export const { GET, POST, HEAD }
+ * = createTribunalRoutes(...)`.
+ */
+export interface TribunalRoutes {
+    GET(request: Request): Promise<Response>;
+    POST(request: Request): Promise<Response>;
+    HEAD(request: Request): Promise<Response>;
+}
+/**
+ * Mount the service inside an app that already knows who its users are.
+ *
+ * Strips `basePath`, asks `authorize` what this request is allowed, and
+ * **replaces** the authorization header with the token that answer implies —
+ * replaces, so a caller cannot present its own bearer and choose its own
+ * capability. A refusal is answered 401 without the Worker seeing the request,
+ * which keeps the app's session and the deployment's tokens two separate things.
+ */
+export declare function createTribunalRoutes(worker: Tribunal, options: TribunalRouteOptions): TribunalRoutes;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.js

@@ -0,0 +1,44 @@
+/**
+ * Mount the service inside an app that already knows who its users are.
+ *
+ * Strips `basePath`, asks `authorize` what this request is allowed, and
+ * **replaces** the authorization header with the token that answer implies —
+ * replaces, so a caller cannot present its own bearer and choose its own
+ * capability. A refusal is answered 401 without the Worker seeing the request,
+ * which keeps the app's session and the deployment's tokens two separate things.
+ */
+export function createTribunalRoutes(worker, options) {
+    const basePath = (options.basePath ?? '').replace(/\/$/, '');
+    const handle = async (request) => {
+        const granted = await options.authorize(request);
+        if (granted === null) {
+            return new Response(JSON.stringify({ error: 'not authorized for this deployment' }), {
+                status: 401,
+                headers: { 'content-type': 'application/json; charset=utf-8' },
+            });
+        }
+        const url = new URL(request.url);
+        if (basePath !== '' && url.pathname.startsWith(basePath)) {
+            url.pathname = url.pathname.slice(basePath.length) || '/';
+        }
+        const headers = new Headers(request.headers);
+        // Replaced rather than added. A caller that sent its own bearer would
+        // otherwise decide its own capability, and `authorize` would be advisory.
+        headers.set('authorization', `Bearer ${granted === 'ingest' ? options.tokens.ingest : options.tokens.review}`);
+        return worker.fetch(new Request(url, {
+            method: request.method,
+            headers,
+            ...(request.method === 'GET' || request.method === 'HEAD'
+                ? {}
+                : { body: await request.arrayBuffer() }),
+        }));
+    };
+    return {
+        GET: handle,
+        POST: handle,
+        // A `HEAD` is a `GET` whose body Next discards. Declared so the framework
+        // does not answer 405 for a request every image preloader makes.
+        HEAD: handle,
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAsFA;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAgB,EAChB,OAA6B;IAE7B,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE7D,MAAM,MAAM,GAAG,KAAK,EAAE,OAAgB,EAAqB,EAAE;QAC3D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC,EAAE;gBACnF,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE;aAC/D,CAAC,CAAC;QACL,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;QAC5D,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7C,sEAAsE;QACtE,0EAA0E;QAC1E,OAAO,CAAC,GAAG,CACT,eAAe,EACf,UAAU,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CACjF,CAAC;QAEF,OAAO,MAAM,CAAC,KAAK,CACjB,IAAI,OAAO,CAAC,GAAG,EAAE;YACf,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO;YACP,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBACvD,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SAC3C,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,EAAE,MAAM;QACX,IAAI,EAAE,MAAM;QACZ,0EAA0E;QAC1E,iEAAiE;QACjE,IAAI,EAAE,MAAM;KACb,CAAC;AACJ,CAAC","sourcesContent":["import type { Tribunal } from './worker.js';\n\n/**\n * The Worker, mounted inside a Next.js App Router app — which on Cloudflare means\n * [vinext](https://vinext.io).\n *\n * The whole adapter is one idea: a Next route handler is\n * `(Request) => Response | Promise<Response>`, and so is\n * {@link Tribunal.fetch}. What is left is a mount prefix to strip and one\n * decision the operator has to make, below.\n *\n * ```ts\n * // app/variance/[[...path]]/route.ts\n * import { createTribunal } from '@variance-authority/tribunal/worker';\n * import { createTribunalRoutes } from '@variance-authority/tribunal/next';\n *\n * const worker = createTribunal({\n *   db: process.env.DB, bucket: process.env.BUCKET, project: 'todomvc',\n *   ingestToken: process.env.VARIANCE_INGEST_TOKEN!,\n *   reviewToken: process.env.VARIANCE_REVIEW_TOKEN!,\n * });\n *\n * export const { GET, POST, HEAD } = createTribunalRoutes(worker, {\n *   basePath: '/variance',\n *   authorize: async (request) => (await isSignedIn(request)) ? 'review' : null,\n * });\n * ```\n *\n * ## The one decision this adapter does not make for you\n *\n * A browser rendering the review surface must not be handed the review token —\n * a token in a page is a token in everybody's devtools, and this one **promotes\n * baselines**. So the token stays on the server and the handler attaches it,\n * which means the handler, not the token, is now the gate.\n *\n * `authorize` is that gate, and it has no default. Returning `'review'` for every\n * request would publish an approve button to the internet, and a package that\n * shipped that as a convenience would be shipping the failure. An operator who\n * genuinely wants the surface open writes `() => 'review'` themselves, in their\n * own file, where the next person reviewing that repository can see it.\n *\n * A request that `authorize` refuses is answered 401 here, without reaching the\n * Worker — so the app's own session and the deployment's tokens stay two\n * separate things, and neither is asked to be the other.\n */\n\nexport interface TribunalRouteOptions {\n  /**\n   * Where the route is mounted, e.g. `/variance` for `app/variance/[[...path]]`.\n   *\n   * Stripped before the request reaches the Worker, which knows only its own\n   * paths. Without it every request would arrive as `/variance/review/builds`\n   * and 404 against a route table that has never heard of the prefix.\n   */\n  readonly basePath?: string;\n\n  /**\n   * Which capability this request is allowed, decided by the operator's own app.\n   *\n   * `null` is a 401. There is no default — see the note above.\n   */\n  authorize(request: Request): Promise<'ingest' | 'review' | null> | 'ingest' | 'review' | null;\n\n  /**\n   * The tokens the Worker was constructed with.\n   *\n   * Passed again rather than read off the worker, because a `Tribunal` is\n   * deliberately a `fetch` handler and nothing else: a handler that could be\n   * asked for its own secrets is a handler that can leak them by being logged.\n   */\n  readonly tokens: { readonly ingest: string; readonly review: string };\n}\n\n/**\n * The three method exports a Next.js route file needs.\n *\n * `GET`, `POST` and `HEAD` are the same handler; the framework wants them named.\n * Spread them straight out of a route module — `export const { GET, POST, HEAD }\n * = createTribunalRoutes(...)`.\n */\nexport interface TribunalRoutes {\n  GET(request: Request): Promise<Response>;\n  POST(request: Request): Promise<Response>;\n  HEAD(request: Request): Promise<Response>;\n}\n\n/**\n * Mount the service inside an app that already knows who its users are.\n *\n * Strips `basePath`, asks `authorize` what this request is allowed, and\n * **replaces** the authorization header with the token that answer implies —\n * replaces, so a caller cannot present its own bearer and choose its own\n * capability. A refusal is answered 401 without the Worker seeing the request,\n * which keeps the app's session and the deployment's tokens two separate things.\n */\nexport function createTribunalRoutes(\n  worker: Tribunal,\n  options: TribunalRouteOptions,\n): TribunalRoutes {\n  const basePath = (options.basePath ?? '').replace(/\\/$/, '');\n\n  const handle = async (request: Request): Promise<Response> => {\n    const granted = await options.authorize(request);\n    if (granted === null) {\n      return new Response(JSON.stringify({ error: 'not authorized for this deployment' }), {\n        status: 401,\n        headers: { 'content-type': 'application/json; charset=utf-8' },\n      });\n    }\n\n    const url = new URL(request.url);\n    if (basePath !== '' && url.pathname.startsWith(basePath)) {\n      url.pathname = url.pathname.slice(basePath.length) || '/';\n    }\n\n    const headers = new Headers(request.headers);\n    // Replaced rather than added. A caller that sent its own bearer would\n    // otherwise decide its own capability, and `authorize` would be advisory.\n    headers.set(\n      'authorization',\n      `Bearer ${granted === 'ingest' ? options.tokens.ingest : options.tokens.review}`,\n    );\n\n    return worker.fetch(\n      new Request(url, {\n        method: request.method,\n        headers,\n        ...(request.method === 'GET' || request.method === 'HEAD'\n          ? {}\n          : { body: await request.arrayBuffer() }),\n      }),\n    );\n  };\n\n  return {\n    GET: handle,\n    POST: handle,\n    // A `HEAD` is a `GET` whose body Next discards. Declared so the framework\n    // does not answer 405 for a request every image preloader makes.\n    HEAD: handle,\n  };\n}\n"]}

package/dist/node/bin.d.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { type TribunalDatabase } from './database.js';
+import { type TribunalService } from './serve.js';
+/**
+ * `variance-authority-tribunal` — the thing the operator runs.
+ *
+ * A process, a port, a file, a directory and two tokens. The same review
+ * service a Cloudflare deployment serves, with SQLite where D1 was and a
+ * directory where R2 was; every route, every refusal and every status code is
+ * the same code.
+ *
+ * Configuration is environment variables rather than flags, matching
+ * [`server`](../../../server/src/bin.ts) — a service is started by a supervisor,
+ * a unit file or a container, and all three pass an environment.
+ *
+ * ## The three things this refuses
+ *
+ * **No tokens, no service.** Inherited from `createTribunal` rather than
+ * re-implemented: two bearer tokens, sixteen characters each, and not the same
+ * string. The refusal is the constructor's and it is quoted straight to stderr.
+ *
+ * **A project, named.** There is no default. An invented one puts two
+ * repositories' baselines in one namespace and the first symptom is a mass
+ * `changed` — the argument is the package's, and `worker-entry` only falls back
+ * to `default` because a Worker environment has nobody to ask. A person typing a
+ * command does.
+ *
+ * **Loopback unless somebody typed otherwise.** Exposure is a decision, not an
+ * accident of a bind address. And on a non-loopback bind the **review surface is
+ * not served at all** — see {@link authorizeFor}, which is the one piece of
+ * policy this file owns.
+ */
+export declare const PORT_VARIABLE = "VARIANCE_TRIBUNAL_PORT";
+export declare const HOST_VARIABLE = "VARIANCE_TRIBUNAL_HOST";
+export declare const DATABASE_VARIABLE = "VARIANCE_TRIBUNAL_DB";
+export declare const STORAGE_VARIABLE = "VARIANCE_TRIBUNAL_STORAGE";
+export declare const PROJECT_VARIABLE = "VARIANCE_TRIBUNAL_PROJECT";
+export declare const INGEST_TOKEN_VARIABLE = "VARIANCE_TRIBUNAL_INGEST_TOKEN";
+export declare const REVIEW_TOKEN_VARIABLE = "VARIANCE_TRIBUNAL_REVIEW_TOKEN";
+export declare const RETENTION_VARIABLE = "VARIANCE_TRIBUNAL_RETENTION_DAYS";
+export declare const REVIEWER_VARIABLE = "VARIANCE_TRIBUNAL_REVIEWER";
+export declare const TRUST_NETWORK_VARIABLE = "VARIANCE_TRIBUNAL_TRUST_NETWORK";
+export interface TribunalConfig {
+    readonly port: number;
+    readonly host: string;
+    /** Absolute, so the startup line names the file rather than a guess. */
+    readonly database: string;
+    /** Absolute, for the same reason. */
+    readonly storage: string;
+    readonly project: string;
+    readonly ingestToken: string;
+    readonly reviewToken: string;
+    readonly retentionDays?: number;
+    readonly reviewer: string;
+    /**
+     * Whether the socket is reachable only from this machine.
+     *
+     * Derived rather than configured: it is a fact about the bind address, and a
+     * setting that could disagree with the address would be a setting that lies.
+     */
+    readonly loopback: boolean;
+}
+/**
+ * Read the configuration, or explain exactly which variable is wrong.
+ *
+ * Pure and exported, so every refusal below is testable without binding a port.
+ * A rule that can only be exercised by starting a process is a rule that gets
+ * tested once, by hand, before it is weakened.
+ */
+export declare function readConfig(env: Readonly<Record<string, string | undefined>>): TribunalConfig;
+/**
+ * The one piece of policy this file owns: who is allowed what.
+ *
+ * `createTribunalRoutes` requires an `authorize` and gives it no default, on the
+ * grounds that returning `'review'` for every request would publish an approve
+ * button. This is a host writing that function in its own file, where the next
+ * person can read it — which is exactly what that refusal asks for.
+ *
+ * Three rules, in order:
+ *
+ * 1. **A caller holding a token gets what the token is for.** CI posts with the
+ *    ingest token from wherever CI runs. The mount replaces the header before the
+ *    Worker sees it, so this is the only place the caller's own bearer is read.
+ * 2. **On a loopback bind, a caller with no token reviews.** The socket is the
+ *    gate: only this machine can reach it, and the person at this machine is the
+ *    reviewer. This is what lets the served page work with no credential in it.
+ * 3. **On a network bind, no token is no capability** — and the surface is not
+ *    served at all, so there is no page to be tricked into carrying one.
+ */
+export declare function authorizeFor(config: TribunalConfig): (request: Request) => 'ingest' | 'review' | null;
+export interface RunningTribunal extends TribunalService {
+    readonly database: TribunalDatabase;
+}
+/**
+ * Open the file, make the directory, bind the port, and say what was done.
+ *
+ * The startup line names the absolute database path, the absolute object
+ * directory, the project, the schema version and the bind address, and names
+ * neither token. Everything an operator needs to confirm they configured the
+ * right thing, and nothing that turns a shipped log into a credential.
+ */
+export declare function start(env: Readonly<Record<string, string | undefined>>, write?: (line: string) => void): Promise<RunningTribunal>;
+/**
+ * A flag is not a way to configure this, and saying so is the whole point.
+ *
+ * `process.argv` was read by nothing here, which is defensible — configuration
+ * is an environment, for the reason on the module — and silently accepting the
+ * arguments of the configuration this *is not* is not. `--database ./x.db` on a
+ * process that only reads {@link DATABASE_VARIABLE} starts a service against a
+ * fresh empty file in the working directory, reports success, and prints a
+ * startup line that reads as confirmation because it is honestly reporting what
+ * the process did. The operator's next move is to ask why their builds are
+ * gone.
+ *
+ * So: refuse, and name the variable the flag was reaching for. Returning the
+ * usage text rather than writing it keeps this pure — the refusals above are
+ * testable without binding a port and this one is no different.
+ */
+export declare function readArguments(argv: readonly string[]): string | null;
+//# sourceMappingURL=bin.d.ts.map