Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
#!/usr/bin/env python3
"""Hold the Alembic migration graph to the shape its releases already shipped.
A released migration graph is a shipped surface. Databases in the field were built by it,
they record only the revision they reached, and Alembic walks them forward from there and
never back. So editing a released revision's parentage does not change what those
databases have already done -- it changes what they will do next, silently, with no error
at the moment of the edit and no error at the moment of the upgrade.
Eight properties, one primitive: the graph as a released tag actually shipped it, read
straight out of git. Nothing here is an allowlist of known-bad cases that outlives its
reason, and nothing needs an old Python environment -- ``env.py`` reads
``target_metadata`` only during autogenerate, so today's runtime can drive an older
``version_locations``.
fresh_install_tables() HEAD_TABLES is what a fresh install actually has, so
the property below derives from something measured
new_slot_collisions() a change introduces no new duplicated slot number
rechained_revisions() a released revision keeps its identity and every edge
Alembic orders the graph by
edited_released_bodies() a released revision still does what the release ran,
or DECLARED_BODY_EDITS pins the body replacing it
spent_body_edit no declaration outlives the edit it was written for,
_declarations() so that list holds only unreleased edits
unrepairable_releases() a database built by a released graph, carrying rows,
still comes out ready when the upgrade users run
upgrades it
releases_with_state_but_no every release that wrote a database is inside the
_graph() window the property above walks
migration_safety_problems() each post-latest-release revision has one finite, explicit
migration-safety attestation
Readiness is not this module's opinion. ``unrepairable_releases`` drives
``run_migrations`` and asks ``background_tables_ready``, so it covers the repair and
stamping that run before Alembic does, and it means by "ready" exactly what production
means -- required columns included, not merely a full set of table names. It seeds the
released schema first, because an empty database is the one case no user is in and is
the case under which adding a NOT NULL column, tightening a nullable one, and building
a unique index all succeed unconditionally.
Coverage is reported as failure, never as a note. A table the seeder could not fill and
a release that fell outside the window are both counted with the violations, because a
property proved over less than its subject is a different, weaker property, and the one
thing it must not do is read like the stronger one.
A release here is any installable tag, ``gh-vX.Y.ZrcN`` prereleases included, because a
database in the field can have been built by one. The first three properties are metadata
only; the fourth builds a database per *distinct shipped graph*, which is what makes that
wider window affordable -- many tags ship byte-identical migrations.
Run it directly, or through the ``migration-release-guard`` workflow, which is the job
that supplies the full tag history this needs.
"""
from __future__ import annotations
import argparse
import ast
import hashlib
import itertools
import json
import re
import sqlite3
import string
import subprocess
import sys
import tempfile
from collections import defaultdict, deque
from collections.abc import Iterable
from dataclasses import dataclass
from decimal import Decimal
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
if str(REPO_ROOT) not in sys.path:
sys.path.insert(0, str(REPO_ROOT))
from alembic import command
from alembic.config import Config
from alembic.script.base import _only_source_rev_file
from alembic.util import to_tuple
from packaging.version import InvalidVersion, Version
from scripts.release_package_version import package_version_from_release_tag
from storage.migrations import (
HEAD_ONLY_REQUIRED_COLUMNS,
HEAD_REQUIRED_COLUMNS,
HEAD_TABLES,
alembic_dir,
background_tables_ready,
run_migrations,
set_literal_main_option,
)
VERSIONS_PATH = "storage/alembic/versions"
# The package that owns SQLite state. A release without it wrote no database to migrate.
STATE_PACKAGE_PATH = "storage"
# ``20260806_0047_remove_session_queue_hold.py`` -> slot ``0047``. Two branches choosing
# the same slot is how the graph forked: the filenames differ, so git merges both without
# a conflict and the duplicate number is the only trace left.
SLOT_PATTERN = re.compile(r"^\d{8}_(\d{4})_.*\.py$")
# Alembic's own bookkeeping. It is the one table a database has that no migration
# declares, so it is the one exclusion when comparing a real database to HEAD_TABLES.
ALEMBIC_BOOKKEEPING_TABLE = "alembic_version"
class MigrationGuardError(RuntimeError):
"""Raised when the guard cannot reach the release history it exists to compare against."""
def is_migration_source(name: str) -> bool:
"""Whether Alembic will load ``name`` as a migration, decided by Alembic's own rule.
Borrowed rather than restated, for the same reason ``GRAPH_FIELDS`` is measured off
``Revision.__init__``: a file Alembic imports is a file this guard must account for,
so the two cannot be permitted to disagree about which files those are. Alembic
rejects a matching file that declares no ``revision`` outright, so nothing this admits
is optional for it either -- which makes it the right denominator for coverage.
"""
return _only_source_rev_file.match(name) is not None
def _git(*args: str) -> str:
result = subprocess.run(["git", *args], capture_output=True, text=True, check=False, cwd=REPO_ROOT)
if result.returncode != 0:
raise MigrationGuardError(f"git {' '.join(args)} failed: {result.stderr.strip()}")
return result.stdout
def release_version(tag: str) -> Version | None:
"""``tag``'s package version, or ``None`` if it is not a release tag.
Borrowed rather than restated, the same way ``is_migration_source`` is. The publish
workflow turns a tag into a wheel by asking ``package_version_from_release_tag``, so a
tag it accepts is a tag that shipped -- and a rule stated separately here could only
ever come to disagree with the one that actually decides. Disagreeing in the direction
that drops tags is the expensive one: a release the filter does not recognise is
absent from every property below, so a migration first shipped in it can be rechained
or edited afterwards with nothing to compare against.
``gh-vX.Y.ZrcN`` prereleases are installable -- AGENTS.md §9 requires a wheel and an
sdist in their release assets -- so a database in the field can have been built by
one, and PEP 440 already orders them before the release they lead to.
"""
try:
return Version(package_version_from_release_tag(tag))
except (ValueError, InvalidVersion):
return None
def version_key(tag: str) -> tuple[Version, str]:
"""Sort key ordering release tags by PEP 440, with the tag itself breaking ties.
``vX.Y.Z`` and ``gh-vX.Y.Z`` carry one version between them, so something has to make
the order total; the tag string does it, and puts ``v`` last, which is what makes the
newest baseline the real release rather than its prerelease.
"""
version = release_version(tag)
if version is None:
raise MigrationGuardError(f"{tag!r} is not a release tag")
return (version, tag)
def tree_at(tag: str, path: str) -> str | None:
"""The git object id of ``path`` as ``tag`` shipped it, or ``None`` if it shipped none."""
result = subprocess.run(
["git", "rev-parse", "--verify", "--quiet", f"{tag}^{{}}:{path}"],
capture_output=True,
check=False,
text=True,
cwd=REPO_ROOT,
)
return result.stdout.strip() or None
def versions_tree(tag: str) -> str | None:
"""The git object id of ``tag``'s versions directory, or ``None`` if it shipped none.
Identity of a shipped graph, straight from git: two tags with the same object id
shipped byte-identical migrations and therefore put the same database in the field.
"""
return tree_at(tag, VERSIONS_PATH)
def releases_with_state_but_no_graph() -> list[str]:
"""Release tags that shipped the SQLite state package without a migration graph.
``released_tags`` reads "no versions directory" as "no migrated database in the
field", and that is an equation rather than a definition -- so this is the thing that
keeps it true instead of assumed. Every release before ``storage/`` existed wrote its
state as JSON, which is why ``storage/importer.py`` still carries an importer rather
than a migration for it; every release that has ``storage/`` shipped a graph with it.
A release shipping one without the other would leave a database in the field that the
upgrade property never builds, and it would do so by falling out of the window rather
than by failing, which is the failure mode with no symptom. Reported instead.
"""
return [tag for tag in release_tag_names() if tree_at(tag, STATE_PACKAGE_PATH) and not versions_tree(tag)]
def release_tag_names() -> list[str]:
"""Every release tag the publisher can build, oldest first, whether or not it shipped a graph."""
names = _git("tag", "-l", "v*", "-l", "gh-v*").split()
return sorted((tag for tag in names if release_version(tag)), key=version_key)
def released_tags() -> list[str]:
"""Every release tag that shipped a migrations directory, oldest first.
The window is derived, not chosen. A tag without ``storage/alembic/versions`` never
put a migrated database in the field; every tag with one did. A "last N releases"
cutoff would instead stop covering a release on a schedule unrelated to whether
anyone is still running it.
"""
tags = [tag for tag in release_tag_names() if versions_tree(tag)]
if not tags:
# A guard that reads "no baseline" as "nothing to compare, therefore fine" passes
# forever while proving nothing. Refuse instead, and name the cause: a shallow
# checkout is the way this happens in practice.
raise MigrationGuardError(
f"no release tag carries {VERSIONS_PATH}, so there is no shipped graph to compare "
"against; a shallow checkout without tags produces exactly this (CI needs "
"actions/checkout with fetch-depth: 0)"
)
return tags
def latest_released_tag() -> str:
"""The baseline for the metadata properties: the newest release carrying migrations.
Comparing against the newest release rather than against all of them is what keeps
the guard honest about the past. A splice that has already shipped cannot be
un-shipped -- reverting it would break the databases that did apply it -- so demanding
that history be clean would leave the guard permanently red and therefore ignored.
Each release is instead checked against its predecessor while it is still unreleased,
and the invariant chains forward without relitigating anything.
"""
return released_tags()[-1]
def released_graphs() -> list[str]:
"""One tag per distinct shipped graph, oldest first: the first release that shipped it.
The unit is a graph, not a tag. What puts a database in the field is a versions
directory, so the many prerelease tags that ship a byte-identical one all put the same
database there and building it once is building it for all of them. That is what makes
covering every installable tag affordable: one ``git rev-parse`` per tag instead of one
database per tag, with no release left unexercised.
"""
graphs: dict[str, str] = {}
for tag in released_tags():
graphs.setdefault(str(versions_tree(tag)), tag)
return sorted(graphs.values(), key=version_key)
def released_sources(tag: str) -> dict[str, str]:
"""``{filename: source}`` for the migration files exactly as ``tag`` shipped them."""
names = _git("ls-tree", "--name-only", f"{tag}:{VERSIONS_PATH}").split()
return {name: _git("show", f"{tag}:{VERSIONS_PATH}/{name}") for name in names if name.endswith(".py")}
def working_tree_sources() -> dict[str, str]:
"""``{filename: source}`` for the migration files as they are right now."""
return {path.name: path.read_text(encoding="utf-8") for path in (REPO_ROOT / VERSIONS_PATH).glob("*.py")}
def extract_released_versions(tag: str, destination: Path) -> Path:
"""Materialise ``tag``'s versions directory under ``destination`` for Alembic to walk."""
destination.mkdir(parents=True, exist_ok=True)
archive = subprocess.run(
["git", "archive", tag, VERSIONS_PATH],
capture_output=True,
check=True,
cwd=REPO_ROOT,
).stdout
subprocess.run(["tar", "-x", "-C", str(destination)], input=archive, check=True)
return destination / VERSIONS_PATH
def slot_collisions(filenames: Iterable[str]) -> dict[str, set[str]]:
"""``{slot: filenames}`` for every slot number claimed by more than one file."""
slots: dict[str, set[str]] = defaultdict(set)
for name in filenames:
match = SLOT_PATTERN.match(name)
if match:
slots[match.group(1)].add(name)
return {slot: names for slot, names in slots.items() if len(names) > 1}
def new_slot_collisions(baseline: str | None = None) -> dict[str, set[str]]:
"""Slots with a claimant the baseline release did not already ship.
The collisions history already contains are in the baseline itself, so they need no
allowlist -- and cannot decay into one that outlives the reason it was written. What
the baseline excuses is those exact filenames, though, not the slot number: excusing
the number would let a third claimant join an already-duplicated slot unreported,
which is the same fork the guard exists to catch.
"""
baseline = baseline or latest_released_tag()
shipped = slot_collisions(released_sources(baseline))
return {
slot: names
for slot, names in slot_collisions(working_tree_sources()).items()
if names - shipped.get(slot, set())
}
class _ComputedMetadata:
"""A ``revision`` or ``down_revision`` the guard could not read as a literal.
Never equal to anything, including another instance of itself. Two computed
expressions are not evidence that a graph is unchanged, they are the absence of
evidence, and a sentinel that compared equal would turn "cannot verify" into
"verified unchanged" -- silently, and precisely for the revisions least able to
afford it.
"""
__slots__ = ()
__hash__ = object.__hash__
def __repr__(self) -> str:
return "<computed>"
def __eq__(self, other: object) -> bool:
return False
COMPUTED = _ComputedMetadata()
# The module-level names Alembic itself reads out of a migration, mapped to the
# ``Revision`` constructor arguments they become. Comparing fewer than all of them
# compares a graph the guard invented rather than the one Alembic builds, and the
# difference is a hole of exactly the outage's shape: the ordering changes while every
# comparison here still matches. The mapping is held to that signature by a test, so a
# field added upstream fails loudly instead of going unwatched.
GRAPH_FIELDS = {
"revision": "revision",
"down_revision": "down_revision",
"depends_on": "dependencies",
"branch_labels": "branch_labels",
}
GRAPH_EDGES = tuple(field for field in GRAPH_FIELDS if field != "revision")
# The guard deliberately does not infer a data-safety obligation from Python or SQL. Every
# new migration owns one explicit attestation, and only this finite vocabulary is accepted.
MIGRATION_SAFETY_FIELD = "MIGRATION_SAFETY"
MIGRATION_SAFETY_KINDS = frozenset({"additive", "deduplicate", "backfill", "copy"})
def declared_graph_fields(source: str) -> dict[str, object]:
"""The graph declarations a migration module makes, in either form Python allows.
``revision: str = "..."`` is an ``AnnAssign``, and reading only ``Assign`` does not
merely lose the annotation -- it drops the migration out of the graph entirely, so it
is compared against nothing and any rechain of it passes.
Edge values are normalized with Alembic's own ``to_tuple``, exactly as ``Script``
does, so the guard's notion of "the same parent" is Alembic's notion and re-spelling
a value it already treats as equal is not reported as drift.
"""
declared: dict[str, object] = {}
for node in ast.parse(source).body:
if isinstance(node, ast.Assign) and len(node.targets) == 1:
target, value = node.targets[0], node.value
elif isinstance(node, ast.AnnAssign) and node.value is not None:
target, value = node.target, node.value
else:
continue
if not isinstance(target, ast.Name) or target.id not in GRAPH_FIELDS:
continue
try:
literal = ast.literal_eval(value)
except ValueError:
declared[target.id] = COMPUTED
continue
declared[target.id] = literal if target.id == "revision" else to_tuple(literal, default=())
return declared
def declared_migration_safety(source: str) -> str | _ComputedMetadata | None:
"""Read exactly one top-level string literal without evaluating migration code."""
values: list[object] = []
try:
nodes = ast.parse(source).body
except SyntaxError:
return COMPUTED
for node in nodes:
if isinstance(node, ast.Assign) and len(node.targets) == 1:
target, value = node.targets[0], node.value
elif isinstance(node, ast.AnnAssign) and node.value is not None:
target, value = node.target, node.value
else:
continue
if isinstance(target, ast.Name) and target.id == MIGRATION_SAFETY_FIELD:
try:
values.append(ast.literal_eval(value))
except (ValueError, TypeError, SyntaxError):
return COMPUTED
if not values:
return None
if len(values) != 1:
return COMPUTED
literal = values[0]
return literal if isinstance(literal, str) else COMPUTED
def revision_claims(sources: dict[str, str]) -> dict[str, list[tuple[str, dict[str, object]]]]:
"""Every claim on every revision identifier, contested ones included.
Parsing keeps this free of import side effects and lets it read a revision from a
release whose modules would no longer import against today's code. A computed value
becomes ``COMPUTED``, which compares unequal to everything; a computed *revision*
additionally cannot identify its file, so it is keyed by filename and can never be
mistaken for a literal revision that happens to render the same way. An edge a module
never declares is ``()``, which is what Alembic defaults it to.
The identifier is the guard's only handle on "the same migration across two releases",
and two modules can declare it at once. Keeping the claimants as a list is what lets a
caller report that rather than overwrite one of them: the survivor would otherwise
answer for a migration whose body Alembic will skip on any database stamped with the
shared identifier.
"""
claims: dict[str, list[tuple[str, dict[str, object]]]] = {}
for name, source in sorted(sources.items()):
declared = declared_graph_fields(source)
if "revision" not in declared:
continue
revision = declared["revision"]
key = f"<computed:{name}>" if revision is COMPUTED else str(revision)
edges = {field: declared.get(field, ()) for field in GRAPH_EDGES}
claims.setdefault(key, []).append((name, edges))
return claims
def revision_graph(sources: dict[str, str]) -> dict[str, tuple[str, dict[str, object]]]:
"""``{revision: (filename, {edge_field: value})}`` for identifiers naming one migration.
Only a contested identifier is absent, because it cannot be keyed to one migration at
all; ``ungraphable_sources`` reports it instead. Metadata that merely cannot be read
stays, carrying ``COMPUTED`` values that are unequal to everything -- a comparison
involving one reports drift rather than agreement, which is the honest answer where
nothing can be read. Dropping it here instead would be silently destructive on a
released tree, whose files are the only surviving record of what that release declared.
"""
return {
revision: claims[0] for revision, claims in revision_claims(sources).items() if len(claims) == 1
}
def ungraphable_sources(sources: dict[str, str]) -> dict[str, str]:
"""``{filename: why the guard cannot hold that file to a released graph}``.
One defect wearing three faces: a key the guard invents has stopped naming exactly one
migration. Metadata it cannot read as a literal names nothing, an identifier two
modules declare names two things, and a file declaring no revision at all is never
keyed and so was never named by anything. Either way the honest answer is "cannot
verify", and the one answer that must stay unreachable is "verified unchanged".
That third face is why the denominator below is Alembic's file rule and not this
module's parse of those files. Asking the parser which files there were to read is
self-confirming -- a file it cannot see is absent from its own account of what it saw
-- and each earlier version of this function asked exactly that, which is why the same
defect kept arriving wearing a new face.
Every caller reading a source tree owes this its output: a tree is compared only
alongside the reasons parts of it cannot be, or refused outright.
"""
reasons: dict[str, str] = {}
claims = revision_claims(sources)
for revision, claimants in claims.items():
names = [name for name, _ in claimants]
for name, edges in claimants:
if revision.startswith("<computed:") or any(value is COMPUTED for value in edges.values()):
reasons[name] = "computes its migration metadata"
elif len(claimants) > 1:
others = ", ".join(other for other in names if other != name)
reasons[name] = f"declares revision {revision!r}, which {others} also declares"
keyed = {name for claimants in claims.values() for name, _ in claimants}
for name in sources:
if name not in keyed and is_migration_source(name):
reasons[name] = "declares no module-level revision"
return reasons
def shipped_head_revisions(sources: dict[str, str]) -> set[str]:
"""The revisions nothing in ``sources`` descends from: where a full upgrade of them ends.
``depends_on`` is an ordering constraint rather than a parent link, so only
``down_revision`` decides what is still a head -- the same rule Alembic applies.
Unreadable metadata is refused rather than worked around, because a head is one answer
and there is no partial version of it. A parent nobody can resolve leaves the real
ancestor looking like a head, so an upgrade that stopped early there would satisfy the
assertion this exists to make.
"""
unreadable = ungraphable_sources(sources)
if unreadable:
raise MigrationGuardError(
"cannot locate the head of a graph whose metadata is unreadable: "
+ "; ".join(f"{name} {reason}" for name, reason in sorted(unreadable.items()))
)
graph = revision_graph(sources)
parents = {parent for _, edges in graph.values() for parent in edges["down_revision"]}
return set(graph) - parents
def rechained_revisions(baseline: str | None = None) -> list[str]:
"""Released revisions whose identity or graph edges have changed since the baseline.
This is the property the outage broke. Inserting an ancestor behind a revision the
field has already passed is invisible to Alembic, which only walks forward, and
invisible to a single-head assertion, which a merge revision satisfies. It is visible
here because the shipped parent is read from the release rather than inferred from
the graph that replaced it.
"""
baseline = baseline or latest_released_tag()
working_tree = working_tree_sources()
shipped_tree = released_sources(baseline)
claimed = revision_claims(working_tree)
current = revision_graph(working_tree)
# Both trees, because a comparison is only as trustworthy as its less readable side.
# A released declaration nobody can read is not one to pass over quietly: those files
# are the only surviving record of what the release shipped, so losing one loses the
# thing every later revision would have been held to.
unreadable_now = ungraphable_sources(working_tree)
unreadable_then = ungraphable_sources(shipped_tree)
problems = [
f"{name} {reason}, so the guard cannot hold it to {baseline}"
for name, reason in sorted(unreadable_now.items())
]
problems += [
f"{baseline} shipped {name}, which {reason}, so nothing can be held to what it declared"
for name, reason in sorted(unreadable_then.items())
if name not in unreadable_now
]
for revision, (name, shipped) in sorted(revision_graph(shipped_tree).items()):
if name in unreadable_then:
# The baseline's own declaration is what cannot be read, so there is nothing
# to compare against and the reason above is the whole report.
continue
if revision not in current:
if revision in claimed:
# Still claimed, just not readably: every claimant is named once in the
# reasons above, and repeating it here describes one defect as two.
continue
problems.append(f"{revision} ({name}) shipped in {baseline} and is no longer in the graph")
continue
if current[revision][0] in unreadable_now:
continue
edges = current[revision][1]
drift = "; ".join(
f"{field} {value!r} -> {edges[field]!r}" for field, value in shipped.items() if edges[field] != value
)
if drift:
problems.append(f"{revision} ({name}) no longer matches what {baseline} shipped: {drift}")
return problems
def released_bodies(sources: dict[str, str]) -> dict[str, tuple[str, str]]:
"""``{revision: (filename, source)}`` -- what each migration in ``sources`` runs.
Keyed by revision because that is the key Alembic uses. A filename is not a migration's
identity: databases record the revision, ``version_locations`` is scanned rather than
enumerated, and renaming a file changes nothing Alembic can observe. Keying bodies by
filename would therefore let a rename carry an edit across a release boundary
untouched, which is the same mistake as inventing a key for anything else here.
"""
return {
revision: (name, sources[name])
for revision, (name, _) in revision_graph(sources).items()
if is_migration_source(name)
}
def body_fingerprint(source: str) -> str:
"""The sha256 a declaration pins a replacement body by."""
return hashlib.sha256(source.encode("utf-8")).hexdigest()
@dataclass(frozen=True)
class DeclaredBodyEdit:
"""One released revision whose body was deliberately changed, and the body it became.
``body`` is what makes this a declaration rather than an exemption. It authorises one
specific replacement, so a second edit to the same revision changes the fingerprint
and is reported like any undeclared one -- the entry cannot decay into a standing
permission for whatever that file says next.
"""
revision: str
body: str
reason: str
DECLARED_BODY_EDITS: tuple[DeclaredBodyEdit, ...] = ()
def _declared_body_edits() -> dict[str, DeclaredBodyEdit]:
return {declared.revision: declared for declared in DECLARED_BODY_EDITS}
def spent_body_edit_declarations(baseline: str | None = None) -> list[str]:
"""Declarations that no longer describe an edit, which is how the list stays short.
A declaration is spent the moment a release ships the body it pinned: the baseline
moves to that release, shipped and current agree, and ``edited_released_bodies`` has
nothing left to accept. Reporting that keeps ``DECLARED_BODY_EDITS`` holding only
edits made since the last release, so it never becomes the standing allowlist the
rest of this module refuses to keep -- and an entry written for an edit that was
never made, or reverted before shipping, fails here rather than sitting ready to
excuse a future one.
"""
baseline = baseline or latest_released_tag()
current = released_bodies(working_tree_sources())
shipped = released_bodies(released_sources(baseline))
problems = []
for revision, declared in sorted(_declared_body_edits().items()):
if revision in shipped and revision in current and shipped[revision][1] != current[revision][1]:
continue
problems.append(
f"DECLARED_BODY_EDITS names {revision}, which is not an edit against {baseline}; "
"a declaration is spent once the release ships the body it pinned and must be "
"removed rather than left standing"
)
return problems
def edited_released_bodies(baseline: str | None = None) -> list[str]:
"""Released revisions whose migration no longer does what the baseline ran.
The properties above watch what a migration *declares*; this watches what it *does*.
They are one contract seen from two sides -- a released migration is a shipped surface
-- and this repository has produced one defect of each shape: the v3.0.11 outage moved
a ``down_revision``, and ``20260501_0001`` had its ``upgrade()`` body edited after
release. Editing the body is the quieter half. A database stamped at that revision
never reruns it, a fresh install runs only the new version, and nothing raises at
either moment.
The upgrade property notices such an edit only when the divergence reaches readiness.
An added index, constraint, or backfill leaves both databases ready and permanently
different, so it cannot be relied on to notice in general -- and concluding otherwise
from the one edit it did catch is how this gap survived a whole design pass.
A released revision missing from the working tree is passed over here because
``rechained_revisions`` is what reports it, and from the same two calls: either its
file is unreadable or contested, or the revision is gone from the graph outright.
Restating it would describe one defect as two. The pair is what must be exhaustive,
not either half, and ``collect_problems`` runs both.
An edit passes only through ``DECLARED_BODY_EDITS``, which is a declaration and not an
exemption: it names the revision, pins the sha256 of the body replacing it, and
records why the divergence is bounded. Pinning is what stops the entry unguarding the
revision, and ``spent_body_edit_declarations`` is what stops the list accumulating, so
what a declaration buys is one reviewed edit rather than a standing permission.
This docstring used to claim no exemption was needed, because restoring the file and
carrying the change in a new revision is always available. That is true of a change a
later revision can apply and false of the one shape that reached here first: removing
work an earlier revision did, on databases that have already done it. A rule whose
stated alternative does not exist gets suspended in the moment rather than amended, so
the narrow declared form is the safer one to hold.
"""
baseline = baseline or latest_released_tag()
declared = _declared_body_edits()
current = released_bodies(working_tree_sources())
problems = []
for revision, (shipped_name, source) in sorted(released_bodies(released_sources(baseline)).items()):
if revision not in current or current[revision][1] == source:
continue
name, body = current[revision]
permitted = declared.get(revision)
if permitted is not None and permitted.body == body_fingerprint(body):
continue
where = shipped_name if name == shipped_name else f"{shipped_name}, now {name}"
detail = (
f"DECLARED_BODY_EDITS pins {permitted.body} for it, not {body_fingerprint(body)}"
if permitted is not None
else "a released migration's body is fixed once a database has run it"
)
problems.append(f"{revision} ({where}) is no longer what {baseline} shipped; {detail}")
return problems
def _alembic_config(db_path: Path, versions: Path | None = None) -> Config:
config = Config()
set_literal_main_option(config, "script_location", str(alembic_dir()))
if versions is not None:
# Without this Alembic splits version_locations on spaces and commas, so a
# temporary directory containing either would silently resolve to no location at
# all -- and an empty graph upgrades to head without applying anything.
set_literal_main_option(config, "path_separator", "os")
set_literal_main_option(config, "version_locations", str(versions))
set_literal_main_option(config, "sqlalchemy.url", f"sqlite:///{db_path}")
return config
def table_names(db_path: Path) -> set[str]:
connection = sqlite3.connect(db_path)
try:
return {str(row[0]) for row in connection.execute("select name from sqlite_master where type = 'table'")}
finally:
connection.close()
def _migration_safety_declaration_error(
revision: str, declaration: str | _ComputedMetadata | None
) -> str | None:
if declaration is None:
return f"{revision} has no MIGRATION_SAFETY declaration"
if declaration is COMPUTED:
return f"{revision} MIGRATION_SAFETY is computed or malformed; only one literal string is supported"
if not isinstance(declaration, str):
return f"{revision} MIGRATION_SAFETY is malformed; only one literal string is supported"
if declaration not in MIGRATION_SAFETY_KINDS:
return f"{revision} MIGRATION_SAFETY contains unsupported kind: {declaration}"
return None
def migration_safety_problems() -> list[str]:
"""Require one explicit attestation for every revision after the latest release.
This is deliberately a metadata-only gate. ``unrepairable_releases`` owns real upgrade
execution and readiness evidence; duplicating that executor here would make the
attestation boundary both slow and a second source of migration behavior.
"""
latest_release = latest_released_tag()
baseline_graph = revision_graph(released_sources(latest_release))
current_sources = working_tree_sources()
current_graph = revision_graph(current_sources)
new_revisions = set(current_graph) - set(baseline_graph)
if not new_revisions:
return []
problems = [
error
for revision in sorted(new_revisions)
if (error := _migration_safety_declaration_error(
revision,
declared_migration_safety(current_sources[current_graph[revision][0]]),
))
]
return problems
def fresh_install_tables() -> set[str]:
"""The tables a fresh install actually has, built the way production builds one."""
with tempfile.TemporaryDirectory() as workspace:
db_path = Path(workspace) / "vibe.sqlite"
run_migrations(db_path)
return table_names(db_path) - {ALEMBIC_BOOKKEEPING_TABLE}
def stamped_revision(db_path: Path) -> str | None:
connection = sqlite3.connect(db_path)
try:
rows = connection.execute(f"select version_num from {ALEMBIC_BOOKKEEPING_TABLE}").fetchall()
except sqlite3.OperationalError:
return None
finally:
connection.close()
return str(rows[0][0]) if len(rows) == 1 else None
def describe_schema_gap(db_path: Path) -> str:
"""Why ``background_tables_ready`` rejected this database, in one line.
The verdict is production's; this only reads the same tables and columns back to say
what is missing, because "not ready" alone does not tell anyone what to fix.
"""
tables = table_names(db_path)
missing_tables = HEAD_TABLES - tables
missing_columns = []
connection = sqlite3.connect(db_path)
try:
for table, required in sorted((HEAD_REQUIRED_COLUMNS | HEAD_ONLY_REQUIRED_COLUMNS).items()):
if table in missing_tables or table not in tables:
continue
present = {str(row[1]) for row in connection.execute(f'pragma table_info("{table}")')}
missing_columns.extend(f"{table}.{column}" for column in sorted(required - present))
finally:
connection.close()
parts = []
if missing_tables:
parts.append(f"{len(missing_tables)} table(s) missing: {', '.join(sorted(missing_tables))}")
if missing_columns:
parts.append(f"{len(missing_columns)} column(s) missing: {', '.join(missing_columns)}")
return "; ".join(parts) or "the schema is incomplete in a way HEAD_TABLES and the required columns do not name"
# SQLite names the one constraint an insert tripped, which is what makes the repair below
# a guided search rather than a guess: the database says what it objected to, and the
# objection itself carries the values it would have accepted.
CHECK_FAILURE = re.compile(r"CHECK constraint failed: (\w+)")
# Enough attempts to satisfy every constraint a row trips one at a time, and few enough
# that a table whose constraints cannot be satisfied this way is given up on rather than
# searched for. Reached only on the tables that refuse the first row at all.
SEED_ATTEMPTS = 60
# Shape proposals are witnesses, not an invitation to allocate arbitrary declared widths.
SEED_TEXT_LIMIT = 4096
SEED_GLOB_STATES = 16384
SQLITE_INT_MIN = -(2**63)
SQLITE_INT_MAX = 2**63 - 1
# Where `varied` records a row's step inside a JSON document. Nothing reads it back; it is
# there so the document differs while staying a document, and it is namespaced so it cannot
# collide with a path some CHECK constrains.
JSON_VARIED_MEMBER = "__seed_step__"
# A CHECK can also require a shape rather than a value. `json_extract(col,'$.p') = 1` and
# `json_type(col,'$.p') = 'array'` both name the column, the path, and what belongs at it,
# which is the same three things the plain literal form carries -- so both are read the
# same way rather than treated as unseedable.
JSON_REQUIREMENT = re.compile(
r"json_(extract|type)\s*\(\s*\"?(\w+)\"?\s*,\s*'([^']*)'\s*\)\s*(?:==|=|is)\s*"
r"('[^']*'|-?[0-9]+(?:\.[0-9]+)?)",
re.IGNORECASE,
)
SUBSTRING_REQUIREMENT = re.compile(
r'\bsubstr\s*\(\s*"?(\w+)"?\s*,\s*(\d+)\s*,\s*(\d+)\s*\)\s*=\s*"?(\w+)"?',
re.IGNORECASE,
)
# Every name SQLite's `json_type` can return, against the emptiest document member of that
# type. A `json_type` clause states the type where the `json_extract` form states the
# value, so this is the one table that turns the former into the latter; SQLite decides
# whether the result is admissible either way.
JSON_TYPE_MEMBERS: dict[str, object] = {
"null": None,
"true": 1,
"false": 0,
"integer": 0,
"real": 0.0,
"text": "",
"array": "[]",
"object": "{}",
}
# The floor, not the target. One row proves nothing about uniqueness, and rows that differ
# everywhere prove just as little: a migration adding `UNIQUE(platform)` cannot fail against
# a fixture whose platform was never allowed to repeat. How many rows a table actually gets
# is the database's answer -- one per column it accepts a repeat of -- so this is only what a
# table it refuses every repeat of must still carry.
SEED_ROWS = 2
# The step a restored duplicate moves its other columns by. Past every step the seeding used,
# so a row offered after the references settle cannot land on one offered before them.
RESTORE_STEP = SEED_ATTEMPTS
def representative_value(column: str, declared_type: str) -> object:
"""A value of ``declared_type`` that SQLite will store in ``column``.
Typed off the declaration rather than off the column's meaning, because meaning is
what no generic seeder can have and what a per-release fixture would have to restate
once per shipped graph. The name is consulted only where the declared type leaves the
choice open -- every TEXT column would otherwise get the same opaque string -- so a
migration that parses a timestamp, an address, or a JSON document gets something
parseable rather than ``'x'``.
"""
kind = declared_type.upper()
if any(marker in kind for marker in ("INT", "REAL", "NUM", "DOUB", "FLOA", "BOOL")):
return 0
if "BLOB" in kind:
return b""
if column.endswith(("_at", "_time")):
return "1970-01-01T00:00:00+00:00"
if column.endswith("_json"):
return "{}"
if "email" in column:
return "[email protected]"
return "x"
def check_expression(ddl: str, name: str) -> str:
"""Constraint ``name``'s expression as ``ddl`` declares it, or ``''`` if it has none."""
# SQLite stores the DDL as it was written, so the keywords are whatever case the
# migration that created the table happened to use.
marker = re.search(rf'CONSTRAINT\s+"?{re.escape(name)}"?\s+CHECK\s*\(', ddl, re.IGNORECASE)
if marker is None:
return ""
depth = 1
index = marker.end()
for offset in range(index, len(ddl)):
if ddl[offset] == "(":
depth += 1
elif ddl[offset] == ")":
depth -= 1
if depth == 0:
return ddl[index:offset]
return ""
def identifier_key(value: str) -> str:
"""SQLite folds ASCII identifier case, not Unicode or JSON member names."""
return value.translate(str.maketrans(string.ascii_uppercase, string.ascii_lowercase))
def bounded_integer(literal: str, lower: int, upper: int) -> int | None:
"""Reject oversized decimal tokens before Python parsing or SQLite binding."""
digits = literal.lstrip("-").lstrip("0") or "0"
if len(digits) > len(str(max(abs(lower), abs(upper)))):
return None
value = int(digits) * (-1 if literal.startswith("-") else 1)
return value if lower <= value <= upper else None
def check_proposals(expression: str, columns: Iterable[str]) -> list[tuple[str, str]]:
"""``(column, value)`` pairs ``expression`` itself suggests, for the columns it names.
A check the row tripped is a check that says what it wants: ``state in ('waiting',
...)`` carries both the column to change and the values it would have accepted. Only
columns the expression names are proposed for, because a literal from one constraint
written into a column that constraint never mentions is not a repair.
Reading the expression is a heuristic and is allowed to be wrong. SQLite decides
whether the resulting row is admissible, so a bad proposal costs an attempt rather
than producing a row the schema would have refused.
"""
literals = re.findall(r"'([^']*)'", expression)
folded = identifier_key(expression)
named = [column for column in columns if re.search(rf"\b{re.escape(identifier_key(column))}\b", folded)]
return [(column, literal) for column in named for literal in literals]
def json_proposals(
connection: sqlite3.Connection, expression: str, columns: Iterable[str]
) -> list[tuple[str, str]]:
"""``(column, document)`` pairs satisfying every JSON-path clause ``expression`` states.
The document is built by SQLite's own ``json_set`` rather than assembled here, so the
path syntax is whatever SQLite accepts and not a second reading of it. All clauses for
one column are folded into a single document, because a constraint requiring two paths
is not satisfied by a document carrying either one.
"""
wanted = {identifier_key(column): column for column in columns}
required: dict[str, list[tuple[str, str, object]]] = {}
for function, column, path, literal in JSON_REQUIREMENT.findall(expression):
column = wanted.get(identifier_key(column))
if column is None:
continue
if function.lower() == "type":
named = literal.strip("'").lower()
if named not in JSON_TYPE_MEMBERS:
continue
member = JSON_TYPE_MEMBERS[named]
# A composite has to be spliced in as a document; anything else is a scalar and
# would be stored as one whatever `json_set` is handed.
term = "json(?)" if named in {"array", "object"} else "?"
required.setdefault(column, []).append((path, term, member))
elif literal.startswith("'"):
required.setdefault(column, []).append((path, "?", literal[1:-1]))
else:
required.setdefault(column, []).append((path, "json(?)", str(Decimal(literal))))
proposals = []
for column, clauses in required.items():
document = "'{}'"
parameters: list[object] = []
for path, term, value in clauses:
document = f"json_set({document}, ?, {term})"
parameters.extend([path, value])
proposals.append((column, str(connection.execute(f"select {document}", parameters).fetchone()[0])))
return proposals
def glob_witness(
connection: sqlite3.Connection,
patterns: tuple[str, ...],
*,
width: int | None = None,
alphabet: str = string.printable,
) -> str | None:
"""Search the intersection of finite GLOB automata, with SQLite as the oracle.
A state retains every possible token position after the current prefix. Stars
both consume characters and admit an empty transition to the next token.
"""
if (width is not None and not 0 <= width <= SEED_TEXT_LIMIT) or sum(map(len, patterns)) > SEED_TEXT_LIMIT:
return None
machines: list[list[str]] = []
for pattern in patterns:
tokens = []
index = 0
while index < len(pattern):
end = index + 1
if pattern[index] == "[":
if pattern[end:end + 1] == "^":
end += 1
# SQLite admits ']' as the first member, including after '^'.
if pattern[end:end + 1] == "]":
end += 1
closing = pattern.find("]", end)
if closing < 0:
return None
end = closing + 1
tokens.append(pattern[index:end])
index = end
machines.append(tokens)
alphabet = "".join(dict.fromkeys(alphabet.replace("\x00", "")))
members = {
token: frozenset(
char for char in alphabet
if connection.execute("select ? glob ?", (char, token)).fetchone()[0]
)
for token in sorted({token for tokens in machines for token in tokens if token != "*"})
}
# Equivalent characters have identical transitions in every pattern.
representatives: dict[tuple[bool, ...], str] = {}
for char in alphabet:
representatives.setdefault(tuple(char in accepted for accepted in members.values()), char)
def closure(tokens: list[str], positions: Iterable[int]) -> frozenset[int]:
result = set(positions)
for position in tuple(result):
while position < len(tokens) and tokens[position] == "*":
position += 1
if position in result:
break
result.add(position)
return frozenset(result)
initial = tuple(closure(tokens, [0]) for tokens in machines)
start = (initial, 0)
parents = {start: None}
queue = deque([(start, 0)])
while queue:
key, depth = queue.popleft()
states, _ = key
if (width is None or depth == width) and all(
len(tokens) in state for tokens, state in zip(machines, states)
):
parts = []
cursor = key
while parents[cursor] is not None:
cursor, char = parents[cursor]
parts.append(char)
witness = "".join(reversed(parts))
if all(connection.execute("select ? glob ?", (witness, pattern)).fetchone()[0] for pattern in patterns):
return witness
if depth >= (SEED_TEXT_LIMIT if width is None else width):
continue
for char in representatives.values():
next_states = tuple(
closure(tokens, (
position if tokens[position] == "*" else position + 1
for position in state if position < len(tokens)
and (tokens[position] == "*" or char in members[tokens[position]])
))
for tokens, state in zip(machines, states)
)
if not all(next_states):
continue
next_key = (next_states, depth + 1 if width is not None else 0)
if next_key in parents:
continue
if len(parents) >= SEED_GLOB_STATES:
return None
parents[next_key] = (key, char)
queue.append((next_key, depth + 1))
return None
def shape_proposals(
connection: sqlite3.Connection,
expression: str,
required: list[tuple[str, str]],
values: dict[str, object],
*,
text_constraints: str | None = None,
omitted: Iterable[tuple[str, str, str | None]] = (),
unavailable: Iterable[str] = (),
) -> list[tuple[str, object]]:
"""Derive bounded text-shape and numeric candidates from the rejected CHECK.
This extends the literal/JSON proposals, not the seeder's coverage claim. Unsupported
expressions still fail visibly; every proposed value must survive a real insert.
"""
names = {identifier_key(name): name for name in values}
text = {name: value for name, value in values.items() if isinstance(value, str)}
widths = {}
shapes = text_constraints if text_constraints is not None else expression
for name, width in re.findall(r'\blength\s*\(\s*"?(\w+)"?\s*\)\s*=\s*(\d+)', shapes, re.IGNORECASE):
name = names.get(identifier_key(name), name)
size = bounded_integer(width, 0, SEED_TEXT_LIMIT)
if name in text and size is not None:
widths[name] = size
text[name] = text[name][:size].ljust(size, "0")
globs = re.findall(
r"\b\"?(\w+)\"?\s+(not\s+)?glob\s*'((?:[^']|'')*)'",
shapes,
re.IGNORECASE,
)
positive: dict[str, list[str]] = defaultdict(list)
alphabets = {name: string.printable for name in text}
for name, negated, quoted in globs:
name = names.get(identifier_key(name), name)
if name in text:
pattern = quoted.replace("''", "'")
alphabets[name] += pattern
if not negated:
positive[name].append(pattern)
alphabets = {name: "".join(dict.fromkeys(alphabet)) for name, alphabet in alphabets.items()}
# Restrict the alphabet before generating a witness so later CHECK order cannot
# erase a required width or introduce characters forbidden by another CHECK.
for name, negated, quoted in globs:
name = names.get(identifier_key(name), name)
if name not in text:
continue
pattern = quoted.replace("''", "'")
if negated and pattern.startswith("*[^") and pattern.endswith("]*"):
allowed = "".join(
char
for char in alphabets[name]
if not connection.execute("select ? glob ?", (char, pattern)).fetchone()[0]
)
alphabets[name] = allowed
if allowed:
text[name] = "".join(char if char in allowed else allowed[0] for char in text[name])
for name, patterns in positive.items():
if all(connection.execute("select ? glob ?", (text[name], pattern)).fetchone()[0] for pattern in patterns):
continue
witness = glob_witness(connection, tuple(patterns), width=widths.get(name), alphabet=alphabets[name])
if witness is not None:
text[name] = witness
for name, start, width, other in SUBSTRING_REQUIREMENT.findall(shapes):
name, other = names.get(identifier_key(name), name), names.get(identifier_key(other), other)
position = bounded_integer(start, 1, SEED_TEXT_LIMIT)
size = bounded_integer(width, 0, SEED_TEXT_LIMIT)
if name in text and isinstance(values.get(other), str) and position is not None and size is not None:
offset = position - 1
source = text.get(other, str(values[other]))
if len(source) == size:
text[name] = text[name][:offset].ljust(offset, "0") + source + text[name][offset + size :]
proposals: list[tuple[str, object]] = [(name, value) for name, value in text.items() if value != values[name]]
bounds = {
bound
for token in re.findall(r"(?<![\w.])-?[0-9]+(?![\w.])", expression)
if (bound := bounded_integer(token, SQLITE_INT_MIN, SQLITE_INT_MAX)) is not None
}
projection = ", ".join(
f'cast(? as {declared}) as "{name}"' if declared else f'? as "{name}"'
for name, declared in required
)
for name, declared, default in omitted:
term = f"({default})" if default is not None else "NULL"
if declared:
term = f"cast({term} as {declared})"
projection += f', {term} as "{name}"'
numeric = [
name for name, declared in required
if "INT" in declared.upper() and re.search(rf"\b{re.escape(identifier_key(name))}\b", identifier_key(expression))
]
candidates = list(dict.fromkeys(
value for bound in sorted(bounds) for value in (bound, bound + 1, bound - 1)
if SQLITE_INT_MIN <= value <= SQLITE_INT_MAX
))
fallback = [(name, candidate) for candidate in candidates for name in numeric if candidate != values[name]]
if any(re.search(rf"\b{re.escape(identifier_key(name))}\b", identifier_key(expression)) for name in unavailable):
return [*proposals, *fallback]
# Reserve half the budget for whole-row boundary assignments before a large
# single-column search or Cartesian prefix can starve coordinated moves.
domains = [list(dict.fromkeys([values[name], *candidates])) for name in numeric]
single_changes = (
tuple(candidate if name == changed else values[name] for name in numeric)
for changed in numeric for candidate in candidates if candidate != values[changed]
)
assignments = itertools.chain(
itertools.islice(single_changes, SEED_ATTEMPTS // 2),
(tuple(candidate for _ in numeric) for candidate in candidates),
single_changes,
itertools.product(*domains),
) if numeric else ()
for assignment in itertools.islice(assignments, SEED_ATTEMPTS):
changes = dict(zip(numeric, assignment))
parameters = [changes.get(column, values[column]) for column, _ in required]
try:
accepted = connection.execute(
f"select coalesce(cast(({expression}) as numeric), 1) != 0 from (select {projection})", parameters
).fetchone()[0]
except sqlite3.OperationalError:
# Generated columns or unsupported context cannot reject a candidate.
# Offer the bounded values to the real INSERT, which supplies that context.
proposals.extend(fallback)
break
if accepted:
proposals.extend((name, value) for name, value in changes.items() if value != values[name])
break
return proposals
def moved_row(base: dict[str, object], step: int, *, held: str | None) -> dict[str, object]:
"""``base`` with every column moved to its ``step`` variant, except ``held``.
``held`` is the one column a repeat probe exists to repeat.
"""
return {
name: value if name == held else varied(value, step) for name, value in base.items()
}
def resolve_references(connection: sqlite3.Connection, table: str) -> None:
"""Point ``table``'s references at values its parents actually hold.
A reference is the one kind of column a fixture may not simply invent a value for. Every
other fabricated value is merely arbitrary, but a fabricated reference is a dangling one,
and a dangling reference is a state no release can be in: ``20260806_0047`` rebuilds
tables and then runs ``pragma foreign_key_check``, aborting the upgrade if anything
dangles. A fixture that manufactures one turns a correct migration red, which is worse
than a missed defect because it is indistinguishable from a real catch. That is not
hypothetical -- it is what a hundred and two of them did here, and the reason this pass
exists rather than a rule about which columns to leave alone.
Which columns those are is read from the database rather than from the DDL, because the
DDL spells a foreign key four different ways and SQLite has already parsed all of them.
Run after every table is seeded rather than while seeding, which is what makes it
ordering-free. A reference needs its parent's row to exist, and the reference graph has
cycles -- ``session_turns`` and ``message_deliveries`` each point at the other -- so no
seeding order satisfies every reference. Afterwards every parent has rows and the only
question left is which of their values to copy. Nothing is asserted here: seeding runs
with SQLite's default ``foreign_keys=OFF``, so the rows land regardless and
``dangling_references`` is what reads the result back.
Copying is necessary because a parent's value is not predictable from its column. The
repair in ``insert_seed_row`` moves values until a CHECK is satisfied, so a parent whose
key is held to a list of literals ends up holding one of those rather than what
``representative_value`` proposed, and a child that assumed the latter dangles.
Whether every row may share one parent is the database's answer, not this function's
guess: one value for the whole table is offered first, and only if that is refused does
each row get its own. Refusal means a unique index covers the column, which is a table
like ``scope_settings`` whose primary key *is* its reference -- there, sharing would
collapse the fixture to a single row, and one row is the shape five review rounds went
into getting away from. Where sharing is accepted it is also preferred, because a
reference held still across rows is what the repeat probes proved and what
``seeded_rows_prove_repetition`` reads back.
"""
groups: dict[int, list[tuple[str, str, str | None]]] = {}
for row in connection.execute(f'pragma foreign_key_list("{table}")'):
groups.setdefault(int(row[0]), []).append((str(row[2]), str(row[3]), row[4] and str(row[4])))
for members in groups.values():
parent = members[0][0]
# An omitted parent column means the parent's primary key, in its declared order.
keys = [name for _, _, name in members]
if None in keys:
keys = [
str(column[1])
for column in sorted(
(row for row in connection.execute(f'pragma table_info("{parent}")') if row[5]),
key=lambda row: row[5],
)
]
selected = ", ".join('"{}"'.format(key) for key in keys)
held = connection.execute(f'select distinct {selected} from "{parent}"').fetchall()
if not held:
continue
assignments = ", ".join(f'"{name}" = ?' for _, name, _ in members)
try:
connection.execute(f'update "{table}" set {assignments}', list(held[0]))
continue
except sqlite3.Error:
pass
nullable = {
str(row[1]): not (row[3] or row[5])
for row in connection.execute(f'pragma table_info("{table}")')
}
blanked = ", ".join(f'"{name}" = null' for _, name, _ in members)
rows = [row[0] for row in connection.execute(f'select rowid from "{table}"')]
for index, rowid in enumerate(rows):
# Offsets so two rows start from different parents; the whole rotation because a
# row already holding a later parent's value is in the way of the earlier one.
for offset in range(len(held)):
try:
connection.execute(
f'update "{table}" set {assignments} where rowid = ?',
[*held[(index + offset) % len(held)], rowid],
)
break
except sqlite3.Error:
continue
else:
# Every parent is taken, which happens when a unique reference has more rows
# to point than the parent has rows to point at. A release is in the same
# position and answers it the same two ways: the reference is empty where the
# column allows it, and the row does not exist where it does not.
remove = not all(nullable[name] for _, name, _ in members)
if not remove:
try:
connection.execute(f'update "{table}" set {blanked} where rowid = ?', [rowid])
except sqlite3.Error:
remove = True
if remove:
connection.execute(f'delete from "{table}" where rowid = ?', [rowid])
def dangling_references(connection: sqlite3.Connection) -> str:
"""Which of the seeded rows point at a parent that is not there, or ``''``.
The seeding's own check on itself. Every referencing column keeps the value its parent
was seeded with, so the references resolve by construction -- but "by construction" is a
claim about this code, and ``pragma foreign_key_check`` is the database's answer. They
coincided by accident once already: both sides of a reference happened to be handed the
same representative value, so nothing dangled while nothing was making sure of it.
"""
violations = connection.execute("pragma foreign_key_check").fetchall()
if not violations:
return ""
tables = sorted({str(row[0]) for row in violations})
return f"{len(violations)} row(s) reference a parent that was never seeded, in {', '.join(tables)}"
def seeded_rows_prove_repetition(
connection: sqlite3.Connection, table: str, repeated: Iterable[str]
) -> str:
"""Why ``table``'s stored rows do not repeat every column in ``repeated``, or ``''``.
Read back out of the database rather than inferred from the code that wrote it, because
``insert_seed_row``'s repair rewrites values: a CHECK spanning two columns can reject a
row whose other columns moved, and the repair is free to answer by moving the one column
that row existed to hold still. The insert is then accepted having proved nothing, and
reading the column back is the only way to notice.
The duplicate is counted the way a unique index counts one, which is not the way
``count(distinct c)`` does: SQLite drops NULLs from the latter, so a column NULL in
every row but one reads as perfectly distinct and a column NULL in every row reads as
empty. Both are rows a unique index would accept and this would have called a repeat.
"""
for column in repeated:
shared = connection.execute(
f'select count(*) from (select "{column}" from "{table}" '
f'where "{column}" is not null group by "{column}" having count(*) > 1)'
).fetchone()[0]
if not shared:
return f"no two rows share a {column}, though a row repeating it was accepted"
return ""
def varied(value: object, step: int) -> object:
"""``value`` changed into something of the same kind that differs from it and from other steps.
Indexed by the row rather than merely different, because every row but the base one moves
most of its columns, and two rows carrying the same replacement would collide on the
constraint the variation exists to respect.
Same *kind*, not merely same type, and a JSON document is the case that separates the two.
``representative_value`` seeds a ``_json`` column with a document because that is what the
application writes there, and appending to the text would leave a string that is still a
string and no longer JSON. A migration reading it with ``json_extract`` then fails over
data no release ever held -- which is a false alarm, and worse than a missed one, because
it is indistinguishable from the failure this guard exists to catch. So a document varies
by carrying one more member than it did, and a JSON scalar by its own kind of variation
re-encoded, which keeps every branch valid JSON without a list of the shapes it can take.
"""
if isinstance(value, bool):
return not value
if isinstance(value, int):
return (value + step - SQLITE_INT_MIN) % (SQLITE_INT_MAX - SQLITE_INT_MIN + 1) + SQLITE_INT_MIN
if isinstance(value, float):
return value + float(step)
if isinstance(value, bytes):
return value + str(step).encode()
try:
document = json.loads(value) if isinstance(value, str) else None
except ValueError:
return f"{value}-{step}"
if isinstance(document, dict):
return json.dumps({**document, JSON_VARIED_MEMBER: step})
if isinstance(document, list):
return json.dumps([*document, step])
if document is not None:
return json.dumps(varied(document, step))
return f"{value}-{step}"
def restore_repeat(
connection: sqlite3.Connection,
table: str,
ddl: str,
offered: list[tuple[str, str]],
column: str,
references: set[str],
) -> tuple[str, bool]:
"""Offer ``table`` one more row repeating ``column``, copied off a row that is still there.
Reference resolution removes a row when a unique reference has no parent left for it to
point at, and the row it removes was carrying some column's only duplicate. The duplicate
is not optional: it is what a migration adding a unique index has to meet, and asserting
it without it being there is the defect an earlier review round found. So it is offered
again here, after the references are settled rather than before, which is what makes the
offer survivable.
The references come from a surviving row instead of being invented, for the reason
``resolve_references`` exists at all, and they are the columns held rather than moved --
together with ``column`` itself, which is the point of the row. Everything else moves, so
a composite unique index covering the repeated column has something left to separate the
two rows by.
A reference that is itself uniquely indexed cannot be copied, since the row copied from
still holds it. Which references those are is not asked but tried: the copy is offered
first, and only what the database refuses is offered again with its optional references
empty -- a shape released rows already have, so the second offer is a row a release can be
in rather than a concession to make the fixture fit. A reference the table demands keeps the
copy either way, because the alternative to a shared parent there is no row at all, and
then the refusal stands and is reported. ``session_turns`` is that case:
``uq_session_turns_message_written_attempt`` keeps ``initial_delivery_id`` unique among
non-terminal turns and the column is NOT NULL, so the table cannot hold more such rows than
there are deliveries to point at, and eleven of its columns lose the duplicate they were
granted in isolation.
"""
names = [name for name, _ in offered]
selected = ", ".join(f'"{name}"' for name in names)
survivor = connection.execute(f'select {selected} from "{table}" limit 1').fetchone()
if survivor is None:
return "no row is left to copy a reference from", True
row = {
name: value if value is None or name == column or name in references else varied(value, RESTORE_STEP)
for name, value in zip(names, survivor)
}
objection, settled = insert_seed_row(connection, table, ddl, offered, row)
if not objection or column in references:
return objection, settled
optional = {
str(info[1])
for info in connection.execute(f'pragma table_info("{table}")')
if not (info[3] or info[5]) and str(info[1]) in references
}
emptied = {name: None if name in optional else value for name, value in row.items()}
return insert_seed_row(connection, table, ddl, offered, emptied)
def insert_seed_row(
connection: sqlite3.Connection,
table: str,
ddl: str,
required: list[tuple[str, str]],
values: dict[str, object],
) -> tuple[str, bool]:
"""Insert ``values`` into ``table``, repairing what the schema objects to.
Returns ``(objection, settled)``. ``objection`` is ``""`` when the row landed, and
otherwise the schema's own last words. ``settled`` says whose answer that is, and it is
the distinction the caller cannot do without: the database refusing a row is a fact
about the schema, while this function running out of attempts with proposals still
untried is a fact about this function. Reported as one, a limit in the seeder reads as a
property of the release -- which is the failure mode the guard exists to prevent, aimed
at itself.
Where a CHECK rejects the row, SQLite names the constraint and the constraint states
what it wants -- accepted literals, or a JSON shape -- so the repair proposes that and
asks again. SQLite is the judge throughout: the row is admissible only if the schema
accepted it, and a refusal is settled once nothing remains to offer.
"""
if not required:
try:
connection.execute(f'insert into "{table}" default values')
except sqlite3.Error as exc:
return str(exc), True
return "", True
columns = ", ".join(f'"{column}"' for column, _ in required)
placeholders = ", ".join("?" for _ in required)
statement = f'insert into "{table}" ({columns}) values ({placeholders})'
names = [column for column, _ in required]
# Related columns may be constrained by a later CHECK. Derive their text shapes
# together so declaration order does not decide whether a prefix can be offered.
constraints = [
check_expression(ddl, name)
for name in re.findall(r'\bconstraint\s+"?(\w+)"?\s+check\s*\(', ddl, re.IGNORECASE)
]
text_constraints = "\n".join(constraints)
omitted = []
unavailable = []
for info in connection.execute(f'pragma table_xinfo("{table}")'):
if str(info[1]) in values:
continue
if info[6] or (info[5] and str(info[2]).upper() == "INTEGER" and info[4] is None):
# Generated columns and implicit primary keys depend on the INSERT.
# In particular, a missing double-quoted name may silently become text.
unavailable.append(str(info[1]))
else:
omitted.append((str(info[1]), str(info[2]), info[4]))
prefix_sources = {identifier_key(other) for _, _, _, other in SUBSTRING_REQUIREMENT.findall(text_constraints)}
proposed: set[tuple[str, object]] = set()
objection = ""
for _ in range(SEED_ATTEMPTS):
try:
connection.execute(statement, [values[column] for column in names])
except sqlite3.Error as exc:
objection = str(exc)
# However else SQLite refuses the row, the table is one this cannot seed. Only
# a named CHECK carries a repair, so anything else ends here -- settled, because
# the refusal is the schema's and there is no next thing to try.
failure = CHECK_FAILURE.search(objection)
if failure is None:
return objection, True
expression = check_expression(ddl, failure.group(1))
untried = [
pair
for pair in [
*shape_proposals(
connection, expression, required, values,
text_constraints=text_constraints, omitted=omitted, unavailable=unavailable,
),
*check_proposals(expression, names),
*json_proposals(connection, expression, names),
]
if pair not in proposed and values[pair[0]] != pair[1]
]
if not untried:
# Follow only prefix-source dependencies into other CHECKs. Unrelated
# literals must not overwrite columns that already satisfy their checks.
untried = [
pair
for related in constraints
for pair in [*check_proposals(related, names), *json_proposals(connection, related, names)]
if identifier_key(pair[0]) in prefix_sources and pair not in proposed and values[pair[0]] != pair[1]
]
if not untried:
return objection, True
column, literal = untried[0]
proposed.add((column, literal))
values[column] = literal
else:
return "", True
return f"{SEED_ATTEMPTS} attempts did not produce a row the schema accepts; last was {objection}", False
def seed_representative_rows(db_path: Path) -> tuple[dict[str, str], dict[str, str]]:
"""Fill every table of the schema ``db_path`` holds.
A migration is only as safe as the data it runs over. On an empty database, adding a
NOT NULL column with no default, tightening a nullable one, backfilling from a column
being dropped, and building a unique index all succeed unconditionally -- so an
upgrade proved on an empty database is proved against the one case no user is in.
Seeding first is what makes the property below about the databases users carry.
The rows are derived from the schema, because the schema is what differs in every
release and ``pragma table_info`` already knows it; a fixture written per release
would cover the graphs that existed when it was written and quietly stop at the next
one.
Returns ``(short, refused)``, and the split is the whole design. ``short`` is what this
seeder failed to do and is a guard failure. ``refused`` is what the database declined and
is data: each offer it turned down, mapped to SQLite's own words. Five review rounds went
into the difference. Each round named a shape the fixture did not hold -- one row, then
unioned distinct groups, then one member per group, then overlapping groups, then columns
never made non-NULL -- and each fix widened the fixture and asserted the widening was now
complete. It never was, and the reason is structural rather than a missing case: the rows
a released database can hold are the schema's satisfiable states, and enumerating those is
constraint solving. ``message_deliveries`` settles it by construction -- four CHECKs key
twelve columns off ``state``, each state requiring some of them NULL, so **no row of that
table has every column non-NULL** and no fixture can be asked for one.
So the claim stops where the evidence does. What is proved is bounded by the offers this
makes, which it controls, not by the value space, which it does not:
**every column is offered, and every column the database accepts a repeat of is repeated
by two rows that were read back to confirm it.**
Three offers per table. The maximal row, holding a value in every column, because a
nullable column left NULL is a column no migration touching it is tested against. The
mandatory row, holding only what NOT NULL and the primary key demand, because the NULL
branch is what a released database mostly carries and what a disjunctive CHECK admits.
Then one row per column that holds that column still and moves every other one -- moving
the rest is not a preference but the likeliest-accepted shape that still repeats the
column, since a differing column can only help a uniqueness constraint and the one thing
that undoes a difference (a CHECK pinning a column to a literal list, whose repair
restores an accepted literal) does so however the row is built.
Then the references are pointed at parents that exist, which is a separate pass because
every table has to be seeded before any reference can resolve, and it is what stops the
fixture from being a database no release could be in: ``20260806_0047`` aborts the upgrade
on a dangling reference, so inventing one turns a correct migration red. Resolution can
take rows away -- a demanded, uniquely indexed reference bounds a table by its parent's
size -- so the counting and the reading back happen after it, over the fixture the
migrations will actually run against, and any duplicate it cost is offered again.
A refusal means what it says and nothing more: the schema rejected *this* row. Sometimes
that is also the schema forbidding the repeat outright, and sometimes it is a partial
unique index whose permitted side needs a multi-column state another CHECK dictates.
Telling those apart is the constraint solving this is not, so both are reported the same
way and neither is read as proof. What that leaves is measured rather than asserted: over
every released schema the guard runs, the ledger holds fifty-two entries. One is the
maximal row ``message_deliveries`` refuses by construction, above. Of the fifty-one repeat
refusals, thirty-six come from a primary key or a total unique index and three from a
``where <column> is not null`` index that a non-NULL repeat check treats as total anyway.
The remaining twelve are all one genuinely conditional index,
``uq_session_turns_message_written_attempt``, unique on ``initial_delivery_id`` where the
turn is not terminal: one is that column's own repeat, and eleven are other columns of
``session_turns`` whose repeat the table accepted alone and lost once the rest of the
fixture was there, because the same index bounds the table at the number of deliveries its
rows may point at. Those eleven are the one refusal that is about the whole database rather
than one table, and the reason the claim is over what this fixture can hold.
What this proves is that the upgrade runs over rows whose references resolve, not over
meaningful ones -- each table is seeded on its own with foreign keys off, which is
SQLite's default, so the rows are individually well-formed and collectively arbitrary.
"""
short: dict[str, str] = {}
refused: dict[str, str] = {}
accepted: dict[str, tuple[list[str], str, str, list[tuple[str, str]]]] = {}
with sqlite3.connect(db_path) as connection:
schema = [
(str(name), str(ddl))
for name, ddl in connection.execute(
"select name, sql from sqlite_master where type = 'table' and name not like 'sqlite_%'"
)
if name != ALEMBIC_BOOKKEEPING_TABLE
]
for table, ddl in schema:
info = [
(str(row[1]), str(row[2]), bool(row[3] or row[5]))
for row in connection.execute(f'pragma table_info("{table}")')
]
every = [(column, declared) for column, declared, _ in info]
mandatory = [(column, declared) for column, declared, required in info if required]
# The first row is where the repairs happen, so every later row moves the values
# the schema has already accepted rather than the ones it rejected. Offer every
# column first and fall back to what the table demands, because a table whose
# CHECKs make some columns mutually exclusive refuses the maximal row by
# construction and still has to be seeded.
base = {column: representative_value(column, declared) for column, declared in every}
objection, settled = insert_seed_row(connection, table, ddl, every, dict(base))
offered = every
if objection:
refused[f"{table}, every column at once"] = objection
offered = mandatory
base = {column: base[column] for column, _ in mandatory}
objection, settled = insert_seed_row(connection, table, ddl, mandatory, base)
unsettled = {} if settled else {table: objection}
repeated: list[str] = []
# One row per column, holding that column still and moving every other one. The
# step is the row's, so two of these rows differ from each other wherever they
# differ from the base row.
steps = 0
for steps, column in enumerate(() if objection else base, start=1):
refusal, decided = insert_seed_row(
connection, table, ddl, offered, moved_row(base, steps, held=column)
)
if not refusal:
repeated.append(column)
elif decided:
refused[f"{table}.{column}"] = refusal
else:
unsettled[f"{table}.{column}"] = refusal
# Nothing this table holds may repeat, so one more row that differs everywhere --
# less than the table was asked for, and all a unique index needs to be buildable
# against.
if not objection and not repeated:
insert_seed_row(
connection, table, ddl, offered, moved_row(base, 1, held=None)
)
# The shape the maximal row cannot also be. Offered last and one step past the
# rows above, so it cannot collide with them on a column they hold still.
if not objection and set(offered) != set(mandatory):
mandatory_only = {column: base[column] for column, _ in mandatory}
refusal, _ = insert_seed_row(
connection,
table,
ddl,
mandatory,
moved_row(mandatory_only, steps + 1, held=None),
)
if refusal:
refused[f"{table}, nothing but its mandatory columns"] = refusal
short.update(unsettled)
accepted[table] = (repeated, objection, ddl, offered)
# Reference resolution comes between the seeding and the reading back, because it
# rewrites the columns both of them are about: a row counted before it may afterwards
# be gone from a unique reference's rotation, and a repeat proved before it may
# afterwards have been split apart. What the checks below measure is the fixture the
# migrations will actually run against.
for _ in range(len(schema)):
for table, _ in schema:
resolve_references(connection, table)
if not connection.execute("pragma foreign_key_check").fetchall():
break
for table, (repeated, objection, ddl, offered) in accepted.items():
# A reference is dropped from the repeat claim rather than proved, because whether
# two rows may share one is not this fixture's answer to give: the value belongs to
# the parent, and the resolution above hands out as many distinct ones as the
# child's unique indexes turn out to require. Composite indexes are why that is not
# knowable in advance -- ``resource_access_groups`` is unique on its two reference
# columns together with a third, so sharing both at once is refused while sharing
# either alone is fine. What the fixture claims for a reference is that it resolves,
# and ``dangling_references`` is where that claim is read back.
references = {str(row[3]) for row in connection.execute(f'pragma foreign_key_list("{table}")')}
claimed = []
for column in [name for name in repeated if name not in references]:
if not seeded_rows_prove_repetition(connection, table, [column]):
claimed.append(column)
continue
refusal, _ = restore_repeat(connection, table, ddl, offered, column, references)
if refusal:
# Accepted when the table stood alone and refused now that the rest of the
# fixture is around it, which is the database answering about the whole
# database rather than about one table -- ``session_turns`` may not hold more
# rows than ``message_deliveries`` does, because its reference to one is
# both demanded and unique. So it goes to the ledger with every other
# refusal, and out of the claim, rather than failing the guard: the claim is
# over what this fixture can hold, and this is where that ends.
refused[f"{table}.{column}, once the rest of the fixture is there"] = refusal
else:
claimed.append(column)
repeated = claimed
rows = connection.execute(f'select count(*) from "{table}"').fetchone()[0]
if rows < SEED_ROWS:
short[table] = f"{rows} of {SEED_ROWS} rows; {objection or 'the schema accepted no more'}"
continue
unproven = seeded_rows_prove_repetition(connection, table, repeated)
if unproven:
short[table] = unproven
dangling = dangling_references(connection)
if dangling:
short["the seeded database"] = dangling
connection.commit()
return short, refused
def schema_gap_after_upgrade(tag: str) -> tuple[str | None, dict[str, str], dict[str, str]]:
"""``(gap, short, refused)`` -- how a database built by ``tag``'s graph came through the upgrade.
``gap`` is ``None`` when the database comes out ready. ``short`` is where the seeding
fell short of what it set out to do; both are failures, because a property proved over
less than its subject is not the property. ``refused`` is what the schema itself declined
to hold and is carried for the report rather than the verdict -- see
``seed_representative_rows`` for why those two cannot be the same list.
What the rows are *for* is the run, not the tally afterwards. Adding a NOT NULL column,
tightening a nullable one, backfilling from a column being dropped, and building a
unique index each fail loudly over data and succeed unconditionally over an empty
database, and every one of those failures arrives here as an exception or a schema that
came out short. Counting the rows again on the far side would assert something else --
that the graph never removes any -- and that is not a property this repository has:
``20260601_0011`` deduplicates sessions to one row per (scope, anchor) by design, and
``20260703_0026`` discards legacy scope-shaped vault grants the new model cannot
express. Which removals are intended is a question about one migration's purpose, so it
belongs to that migration's own test, where the purpose is known; asking it here would
make the guard carry a list of known-good deletions -- the hand-maintained list of cases
it exists not to have.
The second stage runs ``storage.migrations.run_migrations`` rather than Alembic
directly, and the verdict comes from ``background_tables_ready``. Both are deliberate:
the property is about the databases users actually carry through the upgrade users
actually run, so a regression in the pre-Alembic repair or stamping path has to fail
here too, and readiness has to mean what production means by it -- required columns
included, not merely a full set of table names.
Readiness is necessary and not sufficient, so the stamp is checked against today's head
as well. ``background_tables_ready`` asks whether the tables the product needs are
present, which a database can satisfy while stopping short of the graph's end -- a
migration that bails out after the last table-creating revision leaves exactly that,
and the tail it skipped is where index and constraint changes live. Today's head is read
from the working tree's own sources by the same function that reads the released one, so
the two stages are held to the same kind of statement about where the chain ends.
Whatever the upgrade raises when it aborts propagates: a crash and a silently
incomplete schema are the same failure of the same property.
"""
with tempfile.TemporaryDirectory() as workspace:
root = Path(workspace)
db_path = root / "vibe.sqlite"
released = extract_released_versions(tag, root / "released")
# Read from the tag's own files, before Alembic is involved at all. Asking the
# resolved graph for its head instead would make this self-confirming: an
# extraction or ``version_locations`` that silently resolved to a prefix produces a
# smaller graph whose head the run then trivially reaches, and it is exactly that
# database -- one the release never put in the field, and one today's graph can
# legitimately repair -- whose clean upgrade would be read as evidence.
shipped_heads = shipped_head_revisions(released_sources(tag))
command.upgrade(_alembic_config(db_path, released), "head")
stamp = stamped_revision(db_path)
if stamp is None or stamp not in shipped_heads:
raise MigrationGuardError(
f"upgrading with {tag}'s graph left the database stamped {stamp!r} rather than at "
f"its head {sorted(shipped_heads)!r}; the released graph was not applied in full"
)
short, refused = seed_representative_rows(db_path)
run_migrations(db_path)
current_heads = shipped_head_revisions(working_tree_sources())
landed = stamped_revision(db_path)
if landed is None or landed not in current_heads:
raise MigrationGuardError(
f"upgrading {tag}'s database with today's graph left it stamped {landed!r} rather "
f"than at the current head {sorted(current_heads)!r}; the upgrade stopped early"
)
gap = None if background_tables_ready(db_path) else describe_schema_gap(db_path)
return gap, short, refused
def unrepairable_releases() -> tuple[dict[str, list[str]], dict[str, str]]:
"""``({tag: reasons}, refused)`` for every release today's graph runs over real rows.
A limit in the seeding is one of the reasons, not a footnote beside them. The property is
that a populated released database survives the upgrade, so anything the run left short is
a piece of that property it did not test, and reporting it as less than a failure would
let the guard read as stronger than its evidence.
What the schema itself declined to hold is the other half and is returned separately, to
be printed rather than counted. It is the honest boundary of the fixture -- the columns no
two rows share and SQLite's reason for each -- and calling it a failure would leave the
guard permanently red over primary keys, which is the same as not having one.
"""
failures: dict[str, list[str]] = {}
refused: dict[str, str] = {}
for tag in released_graphs():
try:
gap, short, declined = schema_gap_after_upgrade(tag)
except Exception as exc: # noqa: BLE001 - however the upgrade fails, the verdict is the same
failures[tag] = [f"upgrade aborted with {type(exc).__name__}: {str(exc).splitlines()[0]}"]
else:
refused.update(declined)
reasons = [] if gap is None else [f"upgrade left the database not ready: {gap}"]
reasons += [f"could not seed {table}: {objection}" for table, objection in sorted(short.items())]
if reasons:
failures[tag] = reasons
return failures, refused
def collect_problems(
baseline: str | None = None, *, include_upgrade: bool = True
) -> tuple[str, list[str], dict[str, str]]:
"""``(baseline, problems, refused)`` -- every property checked, every violation reported at once.
Reporting all of them together rather than stopping at the first is deliberate: a
graph defect usually shows up in more than one property, and seeing which ones fire
is most of the diagnosis.
A limit on what the run could cover is a problem here too, not a note beside them.
Anything this guard cannot exercise is something it passes without having checked, and
the two are indistinguishable to whoever reads the exit code.
``refused`` is not a problem and is not silence either. It is what the schema declined to
hold, printed on every run including a passing one, because the alternative to reporting a
boundary is asserting there isn't one.
"""
baseline = baseline or latest_released_tag()
problems: list[str] = []
refused: dict[str, str] = {}
for tag in releases_with_state_but_no_graph():
problems.append(
f"{tag} shipped {STATE_PACKAGE_PATH} without {VERSIONS_PATH}, so the database it wrote "
"falls outside every upgrade property here"
)
disagreement = fresh_install_tables() ^ HEAD_TABLES
if disagreement:
problems.append(
"storage.migrations.HEAD_TABLES disagrees with a fresh install on: "
f"{', '.join(sorted(disagreement))}"
)
for slot, names in sorted(new_slot_collisions(baseline).items()):
problems.append(f"slot {slot} did not collide in {baseline} and now does: {', '.join(sorted(names))}")
problems.extend(rechained_revisions(baseline))
problems.extend(edited_released_bodies(baseline))
problems.extend(spent_body_edit_declarations(baseline))
problems.extend(migration_safety_problems())
if include_upgrade:
failures, refused = unrepairable_releases()
for tag, reasons in sorted(failures.items(), key=lambda item: version_key(item[0])):
problems.extend(f"{tag}: {reason}" for reason in reasons)
return baseline, problems, refused
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description="Hold the migration graph to the shape its releases shipped.")
parser.add_argument(
"--baseline",
help="release tag to compare metadata against (default: the newest release carrying migrations)",
)
parser.add_argument(
"--skip-upgrade",
action="store_true",
help="skip per-release upgrade evidence while retaining metadata and attestation checks",
)
return parser
def main(argv: list[str] | None = None) -> int:
args = _build_parser().parse_args(argv)
try:
baseline, problems, refused = collect_problems(args.baseline, include_upgrade=not args.skip_upgrade)
except MigrationGuardError as exc:
print(f"migration release guard could not run: {exc}", file=sys.stderr)
return 2
# Printed on the way out whatever the verdict is: the columns the fixture holds no repeat
# of are the edge of what a pass covers, and a pass that does not say where its edge is
# invites being read as covering everything.
if refused:
print(f"the schema refused a repeat of {len(refused)} column(s), which the upgrade was not proved over:")
for target, objection in sorted(refused.items()):
print(f" - {target}: {objection}")
if problems:
print(f"migration release guard failed (baseline {baseline}):", file=sys.stderr)
for problem in problems:
print(f" - {problem}", file=sys.stderr)
return 1
print(f"migration release guard passed (baseline {baseline})")
return 0
if __name__ == "__main__":
raise SystemExit(main())