@variance-authority/tribunal 0.1.0

package/dist/migration-steps.js

@@ -0,0 +1,303 @@
+/**
+ * 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 const MIGRATIONS = [
+    // 3 → 4: why a baseline in this database is what it is.
+    [
+        // Why a baseline in this database is what it is. One row per **approval**, and
+        // the columns are copies rather than a join on purpose: `builds` and
+        // `build_subjects` expire under `sweep`, and the explanation of a baseline has
+        // to last exactly as long as the baseline, which is forever. A view over those
+        // tables would answer correctly right up until the retention window passed and
+        // then answer "nothing was ever explained" — the one failure this whole
+        // subsystem exists to refuse. It is the same trade the git-LFS half makes by
+        // writing the explanation into the commit message instead of a sidecar.
+        `CREATE TABLE changelog (
+       seq            INTEGER PRIMARY KEY AUTOINCREMENT,
+       project        TEXT NOT NULL,
+       build          TEXT NOT NULL,
+       subject        TEXT NOT NULL,
+       "commit"       TEXT NOT NULL,
+       intent         TEXT,
+       decided_by     TEXT NOT NULL,
+       note           TEXT,
+       -- The region list the build reported, frozen. Shapes are grouped when
+       -- somebody reads: approval here is per subject, so there is no batch at
+       -- write time to cluster, and a shape approved across three sessions should
+       -- still read as one change.
+       regions        TEXT NOT NULL,
+       at             TEXT NOT NULL,
+       at_ms          INTEGER NOT NULL
+     ) STRICT`,
+        `CREATE INDEX changelog_recent ON changelog (project, at_ms DESC)`,
+        `CREATE INDEX changelog_subject ON changelog (project, subject, at_ms DESC)`,
+        `CREATE TRIGGER changelog_is_append_only BEFORE UPDATE ON changelog BEGIN
+       SELECT RAISE(ABORT, 'the changelog is append-only: an edited explanation is an explanation of a baseline that was promoted for a different reason');
+     END`,
+        `CREATE TRIGGER changelog_is_permanent BEFORE DELETE ON changelog BEGIN
+       SELECT RAISE(ABORT, 'the changelog is append-only: a deleted entry leaves a baseline nobody can account for, which is the state this table exists to end');
+     END`,
+        `UPDATE schema_version SET version = 4`,
+    ],
+    // 4 → 5: browser accessibility evidence is verdict-bearing baseline state.
+    [
+        `ALTER TABLE baselines ADD COLUMN accessibility TEXT`,
+        `ALTER TABLE build_subjects ADD COLUMN signals TEXT`,
+        `ALTER TABLE build_subjects ADD COLUMN candidate_accessibility TEXT`,
+        `UPDATE schema_version SET version = 5`,
+    ],
+    // 5 → 6: what a run read about its own subjects, with no baseline in it.
+    [
+        // A table rather than columns on `build_subjects`, because a variation is
+        // about a *pair*: the row belongs to the subject, but what it says is how
+        // that subject stands against another subject in the same run. A subject can
+        // also be a variation while having no observation at all — a story added
+        // behind a flag is `new`, and the flag's effect is exactly what this row
+        // carries — so the two are not the same set.
+        //
+        // Every optional field is nullable and none of them is defaulted. `identical`
+        // has three states and they are three different claims: `1` the pair renders
+        // to one hash, `0` it does not, `NULL` nothing compared them, because the
+        // parent the declaration named is not in this run. Writing `0` for the third
+        // would report a broken link as a measured difference.
+        `CREATE TABLE build_variations (
+       project    TEXT NOT NULL,
+       build      TEXT NOT NULL,
+       subject    TEXT NOT NULL,
+       parent     TEXT,
+       identical  INTEGER,
+       bands      TEXT,
+       unobserved TEXT,
+       components TEXT,
+       digest     TEXT,
+       how        TEXT,
+       because    TEXT NOT NULL,
+       PRIMARY KEY (project, build, subject)
+     ) STRICT`,
+        `UPDATE schema_version SET version = 6`,
+    ],
+    // 6 → 7: what the commit reaches, which is the only thing here that names a
+    // file somebody edited.
+    [
+        // Two tables rather than one, and the split is the whole point of the shape.
+        //
+        // The build row exists whenever a run had a diff to read, *including* when
+        // the walk refused to attribute it — a changed file the graph does not hold,
+        // a diff entirely outside the graph, a diff reaching no component. In that
+        // case `whole` carries the reason and there are no subject rows.
+        //
+        // So zero subject rows has two meanings and `whole` is what separates them:
+        // with a reason, nothing could be attributed and every subject must be read
+        // as possibly reached; without one, the commit was understood and simply
+        // reached none of the subjects whose baselines said what they were made of.
+        // Those support opposite decisions, and one table could not hold both.
+        `CREATE TABLE build_reach (
+       project     TEXT NOT NULL,
+       build       TEXT NOT NULL,
+       against_ref TEXT NOT NULL,
+       changed     TEXT NOT NULL,
+       components  TEXT NOT NULL,
+       whole       TEXT,
+       unscanned   TEXT,
+       opaque      TEXT,
+       PRIMARY KEY (project, build)
+     ) STRICT`,
+        // `through` and `trail` are nullable together with `reached = 0`: a subject
+        // this diff does not reach has no chain to print, and an empty array stored
+        // where a chain belongs would render as a trail of no hops rather than as no
+        // trail. A subject whose baseline recorded no component list is not a row at
+        // all — the run cannot say what it is made of, and `reached = 0` would be an
+        // assertion nobody made.
+        `CREATE TABLE build_reach_subjects (
+       project TEXT NOT NULL,
+       build   TEXT NOT NULL,
+       subject TEXT NOT NULL,
+       reached INTEGER NOT NULL,
+       through TEXT,
+       trail   TEXT,
+       because TEXT NOT NULL,
+       PRIMARY KEY (project, build, subject)
+     ) STRICT`,
+        `UPDATE schema_version SET version = 7`,
+    ],
+    // 7 → 8: how large the baseline was, which is sometimes the change itself.
+    [
+        // Nullable, and left null on every row written before this step. A number
+        // backfilled from `candidate_width` would be an invention that reads exactly
+        // like a measurement, and the whole point of the column is to be able to say
+        // the two differ.
+        `ALTER TABLE build_subjects ADD COLUMN baseline_width INTEGER`,
+        `ALTER TABLE build_subjects ADD COLUMN baseline_height INTEGER`,
+        `UPDATE schema_version SET version = 8`,
+    ],
+    // 8 → 9: what the config declared, and what each declaration did.
+    [
+        // The audit that makes an ignore safe to have, kept where it outlives the run.
+        // A mask grows over a real regression silently, and the only thing that catches
+        // it is a rule absorbing nothing *again* — a comparison a CI log cannot answer.
+        //
+        // Two columns rather than a row per rule: the ledger is small, is always read
+        // with its build, and a table here would be a second vocabulary for one fact.
+        //
+        // Null is *the writer said nothing*, which on this format is also what a
+        // config with no rules produces — one absence, and the store invents no
+        // second. What it must not become is a ledger of zero rules: an unaudited
+        // build, reported as an audited one that found nothing.
+        `ALTER TABLE builds ADD COLUMN ignores TEXT`,
+        `ALTER TABLE builds ADD COLUMN sensitivities TEXT`,
+        `UPDATE schema_version SET version = 9`,
+    ],
+    // 9 → 10: which declaration decided each green subject.
+    [
+        // The ledger added at step 9 says what each rule absorbed *across the run*.
+        // It cannot say which rule absorbed *this subject*, and that is the sentence
+        // the report prints beside every green-by-declaration name. Without these
+        // two columns a service reading its own store had to answer `the run did not
+        // record which rule absorbed it` about a run that recorded it — the store's
+        // own omission, rendered as the observer's.
+        //
+        // Null keeps meaning the writer said nothing: `ignored: {pixels: 0, boxes: 2}`
+        // is a rule that caught nothing here, which is not the same fact and is the
+        // one that turns a mask into a blind spot.
+        `ALTER TABLE build_subjects ADD COLUMN ignored TEXT`,
+        `ALTER TABLE build_subjects ADD COLUMN relaxed TEXT`,
+        `UPDATE schema_version SET version = 10`,
+    ],
+    // 10 → 11: which component moved, and in which band.
+    [
+        // `regions` is the raster tier's answer, and it loses the name exactly where
+        // a reviewer needs it: a difference that reflows its neighbours merges into
+        // one blob, the blob fits no component, and the region resolves to the
+        // document root. The semantic tier never lost it — it compares digests, not
+        // pixels — but the store had no column for it, so the service could report
+        // only what the picture happened to be able to say.
+        //
+        // Null keeps meaning the run wrote nothing — here, a baseline with no
+        // component hashes. `'[]'` is both sides read and every digest matched.
+        `ALTER TABLE build_subjects ADD COLUMN moved TEXT`,
+        `UPDATE schema_version SET version = 11`,
+    ],
+    // 11 → 12: what draws what, which is the only record that can answer *why did
+    // this move* for a component no file in the diff declares.
+    [
+        // The import graph climbs. `build_reach` walks from a changed file through
+        // its importers, so it names what an edit *could* have reached and can never
+        // name anything a changed file draws: `ProductCard` renders `Card`, `Card`
+        // renders `CardFooter`, and a walk that only goes upward arrives at none of
+        // them. The page was left saying "no rung above holds them" — true, and not
+        // a reason.
+        //
+        // The run already wrote the other direction. `composition.components`
+        // carries `within` and `renders` per component, folded over every subject,
+        // and the store dropped it at the door.
+        //
+        // One row per component, not a JSON blob on `builds`: the page asks *who
+        // draws this one*, and a census of four hundred components read whole to
+        // answer it is the shape that makes a reviewer wait.
+        //
+        // Every column NOT NULL, including the empty lists. A census that named a
+        // component knows all three, and the one ambiguity in them — an empty
+        // `created_by` is *this was a production build*, not *nothing mounted it* —
+        // belongs to the report that wrote it. A store that answered it with NULL
+        // would be inventing a distinction upstream declined to make.
+        `CREATE TABLE build_composition (
+       project    TEXT NOT NULL,
+       build      TEXT NOT NULL,
+       component  TEXT NOT NULL,
+       subjects   TEXT NOT NULL,
+       within     TEXT NOT NULL,
+       created_by TEXT NOT NULL,
+       renders    TEXT NOT NULL,
+       PRIMARY KEY (project, build, component)
+     ) STRICT`,
+        `UPDATE schema_version SET version = 12`,
+    ],
+    // 12 → 13: the attribution itself. The census above says who draws what; this
+    // says what the run concluded from it about each thing that moved.
+    [
+        // The store kept the graph and dropped the answer. A run walks the diff,
+        // finds the file that declares each moved component, climbs to an edited
+        // ancestor when nothing declares it, and writes one sentence per movement
+        // into `composition.movements` — and every one of them stopped at the ingest
+        // door. The review page then rebuilt a worse version of the same walk out of
+        // the census, with no access to the props digests or the control group the
+        // run had used, and printed *no rung above holds them* about components the
+        // run had already attributed to an edited parent.
+        //
+        // One row per movement, keyed by the pair it is about. A component moves for
+        // its own reason in each subject it moved in — the same `Button` can be
+        // `edited` on one page and `upstream` on another — so a table keyed by
+        // component alone would keep whichever row was written last and call it the
+        // cause everywhere.
+        //
+        // `also_in` is not a column. It is the subjects of the sibling rows for the
+        // same component, and a stored copy is a second answer that can disagree
+        // with the first.
+        //
+        // Nullable is *the rung does not apply*: `file` on anything but `edited`,
+        // `upstream` and `through` on anything but `upstream`, `standing` on
+        // anything explained. `bands` and `held` are NOT NULL and can be `'[]'`,
+        // which in both cases means what the report means by it — for `bands`, that
+        // the comparison was name-only and no band is known; for `held`, that the
+        // suite offered no control.
+        `CREATE TABLE build_movements (
+       project   TEXT NOT NULL,
+       build     TEXT NOT NULL,
+       subject   TEXT NOT NULL,
+       component TEXT NOT NULL,
+       cause     TEXT NOT NULL,
+       because   TEXT NOT NULL,
+       bands     TEXT NOT NULL,
+       held      TEXT NOT NULL,
+       file      TEXT,
+       tokens    TEXT,
+       upstream  TEXT,
+       through   TEXT,
+       standing  TEXT,
+       PRIMARY KEY (project, build, subject, component)
+     ) STRICT`,
+        `UPDATE schema_version SET version = 13`,
+    ],
+    // 13 → 14: the denominator the control group is a numerator of.
+    [
+        // `held` alone is two opposite findings under one shape. Empty because the
+        // component renders nowhere else with these inputs is a suite with nothing to
+        // say; empty because it renders in four other places and moved in all four is
+        // the suite saying the loudest thing it can — the change reached everything
+        // this component draws. The page had to guess, and on any run where the edit
+        // landed everywhere it guessed the weak one.
+        //
+        // Nullable, and null is *the run never said*: reports written before this
+        // carry no answer, and `0` is an answer.
+        `ALTER TABLE build_movements ADD COLUMN compared INTEGER`,
+        `UPDATE schema_version SET version = 14`,
+    ],
+];
+//# sourceMappingURL=migration-steps.js.map

package/dist/migration-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-steps.js","sourceRoot":"","sources":["../src/migration-steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every shape this database has taken since it shipped, one entry per version.\n *\n * Apart from [`migrations.ts`](./migrations.js), which holds the frozen initial\n * set, because the two are edited under opposite rules: that file must never\n * change again, and this one only ever grows. Keeping them in one module meant\n * every new table was appended a screen below a block carrying a comment saying\n * it was frozen.\n *\n * The reading of both — which version they land on, and the batch that applies\n * them — is in [`schema.ts`](./schema.js).\n */\n\n\n/**\n * One entry per version after `INITIAL_VERSION`, in order.\n *\n * A database that is already deployed cannot be given a new table by editing the\n * statements that created it — `wrangler d1 migrations apply` tracks which files\n * it has run, and a rewritten `0001` is a file it will never run again. So the\n * initial set is frozen at the version it shipped at and every later shape is a\n * step, generated into its own `.sql` beside it.\n *\n * Each step ends by writing its own version, so a database is never at a version\n * whose shape it does not have — and a fresh database applying the initial set\n * and every step in order arrives at exactly the same place as one that was\n * deployed three versions ago.\n *\n * Additive only. A step that dropped or rewrote a column would be asking an\n * append-only store to forget something, which is the one thing every trigger in\n * this file exists to refuse.\n */\nexport const MIGRATIONS: readonly (readonly string[])[] = [\n  // 3 → 4: why a baseline in this database is what it is.\n  [\n    // Why a baseline in this database is what it is. One row per **approval**, and\n    // the columns are copies rather than a join on purpose: `builds` and\n    // `build_subjects` expire under `sweep`, and the explanation of a baseline has\n    // to last exactly as long as the baseline, which is forever. A view over those\n    // tables would answer correctly right up until the retention window passed and\n    // then answer \"nothing was ever explained\" — the one failure this whole\n    // subsystem exists to refuse. It is the same trade the git-LFS half makes by\n    // writing the explanation into the commit message instead of a sidecar.\n    `CREATE TABLE changelog (\n       seq            INTEGER PRIMARY KEY AUTOINCREMENT,\n       project        TEXT NOT NULL,\n       build          TEXT NOT NULL,\n       subject        TEXT NOT NULL,\n       \"commit\"       TEXT NOT NULL,\n       intent         TEXT,\n       decided_by     TEXT NOT NULL,\n       note           TEXT,\n       -- The region list the build reported, frozen. Shapes are grouped when\n       -- somebody reads: approval here is per subject, so there is no batch at\n       -- write time to cluster, and a shape approved across three sessions should\n       -- still read as one change.\n       regions        TEXT NOT NULL,\n       at             TEXT NOT NULL,\n       at_ms          INTEGER NOT NULL\n     ) STRICT`,\n    `CREATE INDEX changelog_recent ON changelog (project, at_ms DESC)`,\n    `CREATE INDEX changelog_subject ON changelog (project, subject, at_ms DESC)`,\n\n    `CREATE TRIGGER changelog_is_append_only BEFORE UPDATE ON changelog BEGIN\n       SELECT RAISE(ABORT, 'the changelog is append-only: an edited explanation is an explanation of a baseline that was promoted for a different reason');\n     END`,\n    `CREATE TRIGGER changelog_is_permanent BEFORE DELETE ON changelog BEGIN\n       SELECT RAISE(ABORT, 'the changelog is append-only: a deleted entry leaves a baseline nobody can account for, which is the state this table exists to end');\n     END`,\n    `UPDATE schema_version SET version = 4`,\n  ],\n  // 4 → 5: browser accessibility evidence is verdict-bearing baseline state.\n  [\n    `ALTER TABLE baselines ADD COLUMN accessibility TEXT`,\n    `ALTER TABLE build_subjects ADD COLUMN signals TEXT`,\n    `ALTER TABLE build_subjects ADD COLUMN candidate_accessibility TEXT`,\n    `UPDATE schema_version SET version = 5`,\n  ],\n  // 5 → 6: what a run read about its own subjects, with no baseline in it.\n  [\n    // A table rather than columns on `build_subjects`, because a variation is\n    // about a *pair*: the row belongs to the subject, but what it says is how\n    // that subject stands against another subject in the same run. A subject can\n    // also be a variation while having no observation at all — a story added\n    // behind a flag is `new`, and the flag's effect is exactly what this row\n    // carries — so the two are not the same set.\n    //\n    // Every optional field is nullable and none of them is defaulted. `identical`\n    // has three states and they are three different claims: `1` the pair renders\n    // to one hash, `0` it does not, `NULL` nothing compared them, because the\n    // parent the declaration named is not in this run. Writing `0` for the third\n    // would report a broken link as a measured difference.\n    `CREATE TABLE build_variations (\n       project    TEXT NOT NULL,\n       build      TEXT NOT NULL,\n       subject    TEXT NOT NULL,\n       parent     TEXT,\n       identical  INTEGER,\n       bands      TEXT,\n       unobserved TEXT,\n       components TEXT,\n       digest     TEXT,\n       how        TEXT,\n       because    TEXT NOT NULL,\n       PRIMARY KEY (project, build, subject)\n     ) STRICT`,\n    `UPDATE schema_version SET version = 6`,\n  ],\n  // 6 → 7: what the commit reaches, which is the only thing here that names a\n  // file somebody edited.\n  [\n    // Two tables rather than one, and the split is the whole point of the shape.\n    //\n    // The build row exists whenever a run had a diff to read, *including* when\n    // the walk refused to attribute it — a changed file the graph does not hold,\n    // a diff entirely outside the graph, a diff reaching no component. In that\n    // case `whole` carries the reason and there are no subject rows.\n    //\n    // So zero subject rows has two meanings and `whole` is what separates them:\n    // with a reason, nothing could be attributed and every subject must be read\n    // as possibly reached; without one, the commit was understood and simply\n    // reached none of the subjects whose baselines said what they were made of.\n    // Those support opposite decisions, and one table could not hold both.\n    `CREATE TABLE build_reach (\n       project     TEXT NOT NULL,\n       build       TEXT NOT NULL,\n       against_ref TEXT NOT NULL,\n       changed     TEXT NOT NULL,\n       components  TEXT NOT NULL,\n       whole       TEXT,\n       unscanned   TEXT,\n       opaque      TEXT,\n       PRIMARY KEY (project, build)\n     ) STRICT`,\n    // `through` and `trail` are nullable together with `reached = 0`: a subject\n    // this diff does not reach has no chain to print, and an empty array stored\n    // where a chain belongs would render as a trail of no hops rather than as no\n    // trail. A subject whose baseline recorded no component list is not a row at\n    // all — the run cannot say what it is made of, and `reached = 0` would be an\n    // assertion nobody made.\n    `CREATE TABLE build_reach_subjects (\n       project TEXT NOT NULL,\n       build   TEXT NOT NULL,\n       subject TEXT NOT NULL,\n       reached INTEGER NOT NULL,\n       through TEXT,\n       trail   TEXT,\n       because TEXT NOT NULL,\n       PRIMARY KEY (project, build, subject)\n     ) STRICT`,\n    `UPDATE schema_version SET version = 7`,\n  ],\n  // 7 → 8: how large the baseline was, which is sometimes the change itself.\n  [\n    // Nullable, and left null on every row written before this step. A number\n    // backfilled from `candidate_width` would be an invention that reads exactly\n    // like a measurement, and the whole point of the column is to be able to say\n    // the two differ.\n    `ALTER TABLE build_subjects ADD COLUMN baseline_width INTEGER`,\n    `ALTER TABLE build_subjects ADD COLUMN baseline_height INTEGER`,\n    `UPDATE schema_version SET version = 8`,\n  ],\n  // 8 → 9: what the config declared, and what each declaration did.\n  [\n    // The audit that makes an ignore safe to have, kept where it outlives the run.\n    // A mask grows over a real regression silently, and the only thing that catches\n    // it is a rule absorbing nothing *again* — a comparison a CI log cannot answer.\n    //\n    // Two columns rather than a row per rule: the ledger is small, is always read\n    // with its build, and a table here would be a second vocabulary for one fact.\n    //\n    // Null is *the writer said nothing*, which on this format is also what a\n    // config with no rules produces — one absence, and the store invents no\n    // second. What it must not become is a ledger of zero rules: an unaudited\n    // build, reported as an audited one that found nothing.\n    `ALTER TABLE builds ADD COLUMN ignores TEXT`,\n    `ALTER TABLE builds ADD COLUMN sensitivities TEXT`,\n    `UPDATE schema_version SET version = 9`,\n  ],\n  // 9 → 10: which declaration decided each green subject.\n  [\n    // The ledger added at step 9 says what each rule absorbed *across the run*.\n    // It cannot say which rule absorbed *this subject*, and that is the sentence\n    // the report prints beside every green-by-declaration name. Without these\n    // two columns a service reading its own store had to answer `the run did not\n    // record which rule absorbed it` about a run that recorded it — the store's\n    // own omission, rendered as the observer's.\n    //\n    // Null keeps meaning the writer said nothing: `ignored: {pixels: 0, boxes: 2}`\n    // is a rule that caught nothing here, which is not the same fact and is the\n    // one that turns a mask into a blind spot.\n    `ALTER TABLE build_subjects ADD COLUMN ignored TEXT`,\n    `ALTER TABLE build_subjects ADD COLUMN relaxed TEXT`,\n    `UPDATE schema_version SET version = 10`,\n  ],\n  // 10 → 11: which component moved, and in which band.\n  [\n    // `regions` is the raster tier's answer, and it loses the name exactly where\n    // a reviewer needs it: a difference that reflows its neighbours merges into\n    // one blob, the blob fits no component, and the region resolves to the\n    // document root. The semantic tier never lost it — it compares digests, not\n    // pixels — but the store had no column for it, so the service could report\n    // only what the picture happened to be able to say.\n    //\n    // Null keeps meaning the run wrote nothing — here, a baseline with no\n    // component hashes. `'[]'` is both sides read and every digest matched.\n    `ALTER TABLE build_subjects ADD COLUMN moved TEXT`,\n    `UPDATE schema_version SET version = 11`,\n  ],\n  // 11 → 12: what draws what, which is the only record that can answer *why did\n  // this move* for a component no file in the diff declares.\n  [\n    // The import graph climbs. `build_reach` walks from a changed file through\n    // its importers, so it names what an edit *could* have reached and can never\n    // name anything a changed file draws: `ProductCard` renders `Card`, `Card`\n    // renders `CardFooter`, and a walk that only goes upward arrives at none of\n    // them. The page was left saying \"no rung above holds them\" — true, and not\n    // a reason.\n    //\n    // The run already wrote the other direction. `composition.components`\n    // carries `within` and `renders` per component, folded over every subject,\n    // and the store dropped it at the door.\n    //\n    // One row per component, not a JSON blob on `builds`: the page asks *who\n    // draws this one*, and a census of four hundred components read whole to\n    // answer it is the shape that makes a reviewer wait.\n    //\n    // Every column NOT NULL, including the empty lists. A census that named a\n    // component knows all three, and the one ambiguity in them — an empty\n    // `created_by` is *this was a production build*, not *nothing mounted it* —\n    // belongs to the report that wrote it. A store that answered it with NULL\n    // would be inventing a distinction upstream declined to make.\n    `CREATE TABLE build_composition (\n       project    TEXT NOT NULL,\n       build      TEXT NOT NULL,\n       component  TEXT NOT NULL,\n       subjects   TEXT NOT NULL,\n       within     TEXT NOT NULL,\n       created_by TEXT NOT NULL,\n       renders    TEXT NOT NULL,\n       PRIMARY KEY (project, build, component)\n     ) STRICT`,\n    `UPDATE schema_version SET version = 12`,\n  ],\n  // 12 → 13: the attribution itself. The census above says who draws what; this\n  // says what the run concluded from it about each thing that moved.\n  [\n    // The store kept the graph and dropped the answer. A run walks the diff,\n    // finds the file that declares each moved component, climbs to an edited\n    // ancestor when nothing declares it, and writes one sentence per movement\n    // into `composition.movements` — and every one of them stopped at the ingest\n    // door. The review page then rebuilt a worse version of the same walk out of\n    // the census, with no access to the props digests or the control group the\n    // run had used, and printed *no rung above holds them* about components the\n    // run had already attributed to an edited parent.\n    //\n    // One row per movement, keyed by the pair it is about. A component moves for\n    // its own reason in each subject it moved in — the same `Button` can be\n    // `edited` on one page and `upstream` on another — so a table keyed by\n    // component alone would keep whichever row was written last and call it the\n    // cause everywhere.\n    //\n    // `also_in` is not a column. It is the subjects of the sibling rows for the\n    // same component, and a stored copy is a second answer that can disagree\n    // with the first.\n    //\n    // Nullable is *the rung does not apply*: `file` on anything but `edited`,\n    // `upstream` and `through` on anything but `upstream`, `standing` on\n    // anything explained. `bands` and `held` are NOT NULL and can be `'[]'`,\n    // which in both cases means what the report means by it — for `bands`, that\n    // the comparison was name-only and no band is known; for `held`, that the\n    // suite offered no control.\n    `CREATE TABLE build_movements (\n       project   TEXT NOT NULL,\n       build     TEXT NOT NULL,\n       subject   TEXT NOT NULL,\n       component TEXT NOT NULL,\n       cause     TEXT NOT NULL,\n       because   TEXT NOT NULL,\n       bands     TEXT NOT NULL,\n       held      TEXT NOT NULL,\n       file      TEXT,\n       tokens    TEXT,\n       upstream  TEXT,\n       through   TEXT,\n       standing  TEXT,\n       PRIMARY KEY (project, build, subject, component)\n     ) STRICT`,\n    `UPDATE schema_version SET version = 13`,\n  ],\n  // 13 → 14: the denominator the control group is a numerator of.\n  [\n    // `held` alone is two opposite findings under one shape. Empty because the\n    // component renders nowhere else with these inputs is a suite with nothing to\n    // say; empty because it renders in four other places and moved in all four is\n    // the suite saying the loudest thing it can — the change reached everything\n    // this component draws. The page had to guess, and on any run where the edit\n    // landed everywhere it guessed the weak one.\n    //\n    // Nullable, and null is *the run never said*: reports written before this\n    // carry no answer, and `0` is an answer.\n    `ALTER TABLE build_movements ADD COLUMN compared INTEGER`,\n    `UPDATE schema_version SET version = 14`,\n  ],\n];\n"]}

package/dist/migrations.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare 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 declare const INITIAL: readonly string[];
+//# sourceMappingURL=migrations.d.ts.map