dirigent-core 0.18.0__tar.gz → 0.18.2__tar.gz

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirigent-core
-Version: 0.18.0
+Version: 0.18.2
 Summary: Dirigent engine core: schema, configuration, and plugin host.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -12,9 +12,9 @@ Requires-Dist: argon2-cffi>=25.1.0
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cronsim>=2.7
 Requires-Dist: cryptography>=46.0.5
-Requires-Dist: dirigent-client==0.18.0
-Requires-Dist: dirigent-common==0.18.0
-Requires-Dist: dirigent-plugin==0.18.0
+Requires-Dist: dirigent-client==0.18.2
+Requires-Dist: dirigent-common==0.18.2
+Requires-Dist: dirigent-plugin==0.18.2
 Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: opentelemetry-api>=1.44.0
 Requires-Dist: pydantic-settings>=2.15.0

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-core"
-version = "0.18.0"
+version = "0.18.2"
 description = "Dirigent engine core: schema, configuration, and plugin host."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -17,9 +17,9 @@ dependencies = [
     "asyncpg>=0.31.0",
     "cronsim>=2.7",
     "cryptography>=46.0.5",
-    "dirigent-client==0.18.0",
-    "dirigent-common==0.18.0",
-    "dirigent-plugin==0.18.0",
+    "dirigent-client==0.18.2",
+    "dirigent-common==0.18.2",
+    "dirigent-plugin==0.18.2",
     "jsonschema>=4.26.0",
     "opentelemetry-api>=1.44.0",
     "pydantic-settings>=2.15.0",

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-core"
-version = "0.18.0"
+version = "0.18.2"
 description = "Dirigent engine core: schema, configuration, and plugin host."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -17,9 +17,9 @@ dependencies = [
     "asyncpg>=0.31.0",
     "cronsim>=2.7",
     "cryptography>=46.0.5",
-    "dirigent-client==0.18.0",
-    "dirigent-common==0.18.0",
-    "dirigent-plugin==0.18.0",
+    "dirigent-client==0.18.2",
+    "dirigent-common==0.18.2",
+    "dirigent-plugin==0.18.2",
     "jsonschema>=4.26.0",
     "opentelemetry-api>=1.44.0",
     "pydantic-settings>=2.15.0",

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/alembic/env.py

@@ -1,14 +1,12 @@
 """Alembic environment: one migration history that runs on both PostgreSQL and SQLite."""
 
 import asyncio
-from typing import Any
 
 from alembic import context
 from sqlalchemy import Connection
-from sqlalchemy.ext.asyncio import async_engine_from_config
-from sqlalchemy.pool import NullPool
 
 from dirigent_core.config import get_settings
+from dirigent_core.database import create_engine
 from dirigent_core.models import Base
 
 config = context.config
@@ -47,13 +45,17 @@ def do_run_migrations(connection: Connection) -> None:
 
 
 async def run_async_migrations() -> None:
-    """Open the async engine and drive the migrations through it."""
-    section: dict[str, Any] = dict(config.get_section(config.config_ini_section) or {})
-    section["sqlalchemy.url"] = database_url()
-    engine = async_engine_from_config(section, prefix="sqlalchemy.", poolclass=NullPool)
-    async with engine.connect() as connection:
-        await connection.run_sync(do_run_migrations)
-    await engine.dispose()
+    """Open the engine on the URL to migrate and drive the migrations through it.
+
+    The engine is the instance's own, so this path opens SQLite with the pragmas every other
+    connection in the process is configured with.
+    """
+    engine = create_engine(get_settings().model_copy(update={"database_url": database_url()}))
+    try:
+        async with engine.connect() as connection:
+            await connection.run_sync(do_run_migrations)
+    finally:
+        await engine.dispose()
 
 
 def run_migrations_online() -> None:

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/alembic/versions/0001_baseline_schema.py

@@ -96,6 +96,12 @@ def upgrade() -> None:
         sa.Column("name", sa.String(length=200), nullable=True),
         sa.Column("description", sa.Text(), nullable=True),
         sa.Column("tags", sa.JSON().with_variant(postgresql.JSONB(astext_type=Text()), "postgresql"), nullable=False),
+        sa.Column(
+            "importance",
+            sa.Enum("routine", "normal", "critical", name="importance", native_enum=False, length=32),
+            server_default="normal",
+            nullable=False,
+        ),
         sa.Column("active", sa.Boolean(), server_default=sa.true(), nullable=False),
         sa.Column("current_version", sa.Integer(), nullable=True),
         sa.Column(
@@ -208,6 +214,11 @@ def upgrade() -> None:
             "scope", sa.Enum("global", "pipeline", name="alert_scope", native_enum=False, length=32), nullable=False
         ),
         sa.Column("pipeline_id", sa.Uuid(), nullable=True),
+        sa.Column(
+            "importance",
+            sa.Enum("routine", "normal", "critical", name="importance", native_enum=False, length=32),
+            nullable=True,
+        ),
         sa.Column("notifier", sa.String(length=100), nullable=False),
         sa.Column("connection_id", sa.Uuid(), nullable=True),
         sa.Column("template", sa.Text(), nullable=True),

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/alerting.py

@@ -17,7 +17,16 @@ from pydantic import BaseModel, ConfigDict, Field, JsonValue
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
-from dirigent_client.enums import AlertEvent, AlertScope, LogLevel, NotificationStatus, RunStatus
+from dirigent_client.enums import (
+    IMPORTANCE_RANK,
+    AlertEvent,
+    AlertScope,
+    Importance,
+    LogLevel,
+    NotificationStatus,
+    RunStatus,
+)
+from dirigent_client.schemas.alerts import LOG_NOTIFIER
 from dirigent_common import (
     EntityName,
     JsonMap,
@@ -42,7 +51,7 @@ from dirigent_core.messages import (
     NOTIFICATION_IN_FLIGHT,
     NOTIFIER_NOT_ON_WORKER,
     SCOPE_NEEDS_PIPELINE,
-    UNKNOWN_NOTIFIER,
+    TARGET_HAS_NO_NOTIFIER,
 )
 from dirigent_core.models import (
     AlertRule,
@@ -101,10 +110,11 @@ class AlertRuleRequest(BaseModel):
     name: str | None = None
     description: str | None = None
     event: AlertEvent
-    notifier: str
     scope: AlertScope = AlertScope.GLOBAL
     pipeline: str | None = None
+    importance: Importance | None = None
     connection: str | None = None
+    """The connection this rule delivers through, whose kind names the sender; none is the log."""
     template: str | None = None
     body: str | None = None
     throttle: timedelta = timedelta(0)
@@ -173,15 +183,12 @@ async def list_rules(
 
 
 async def create_rule(session: AsyncSession, services: EngineServices, request: AlertRuleRequest) -> AlertRule:
-    """Declare an alert rule, refusing a notifier or a scope this instance cannot honour."""
-    if request.notifier not in services.host.notifiers:
-        installed = ", ".join(sorted(services.host.notifiers)) or "none are installed"
-        raise AlertError(UNKNOWN_NOTIFIER, notifier=repr(request.notifier), installed=installed)
+    """Declare an alert rule, refusing a target or a scope this instance cannot honour."""
     if await find_rule(session, request.code) is not None:
         raise AlertError(DUPLICATE_RULE, code=repr(request.code))
     check_templates(template=request.template, body=request.body)
     pipeline_id = await _scope_pipeline(session, request)
-    connection_id = await _connection_id(session, request.connection) if request.connection else None
+    notifier, connection_id = await _target(session, services, request.connection)
     rule = AlertRule(
         code=request.code,
         name=request.name,
@@ -189,7 +196,8 @@ async def create_rule(session: AsyncSession, services: EngineServices, request:
         event=request.event,
         scope=request.scope,
         pipeline_id=pipeline_id,
-        notifier=request.notifier,
+        importance=request.importance,
+        notifier=notifier,
         connection_id=connection_id,
         template=request.template,
         body=request.body,
@@ -225,13 +233,31 @@ async def _scope_pipeline(session: AsyncSession, request: AlertRuleRequest) -> U
     return pipeline.id
 
 
-async def _connection_id(session: AsyncSession, code: str) -> UUID:
-    """Resolve the connection a notifier delivers through, refusing an unknown code."""
+async def _connection(session: AsyncSession, code: str) -> Connection:
+    """Read one connection by code, refusing a code this instance does not hold."""
     found = await session.execute(sa.select(Connection).where(Connection.code == code))
     connection = found.scalar_one_or_none()
     if connection is None:
         raise AlertError(ALERT_UNKNOWN_CONNECTION, code=repr(code))
-    return connection.id
+    return connection
+
+
+async def _target(session: AsyncSession, services: EngineServices, code: str | None) -> tuple[str, UUID | None]:
+    """Resolve the one target named into the sender that delivers it and what it opens.
+
+    A target is a connection, and the notifier is that connection's kind; naming nothing is
+    the process log. A kind no installed notifier answers to is refused here rather than
+    stored, because the row would otherwise hold a sender no worker can dispatch on.
+    """
+    if code is None:
+        return LOG_NOTIFIER, None
+    connection = await _connection(session, code)
+    if connection.kind not in services.host.notifiers:
+        installed = ", ".join(sorted(services.host.notifiers)) or "none are installed"
+        raise AlertError(
+            TARGET_HAS_NO_NOTIFIER, code=repr(connection.code), kind=repr(connection.kind), installed=installed
+        )
+    return connection.kind, connection.id
 
 
 async def delete_rule(session: AsyncSession, rule: AlertRule) -> None:
@@ -242,11 +268,23 @@ async def delete_rule(session: AsyncSession, rule: AlertRule) -> None:
     _logger.info("alert rule deleted", rule=code)
 
 
-async def matching_rules(session: AsyncSession, event: AlertEvent, pipeline_id: UUID) -> list[AlertRule]:
+def _satisfied_levels(importance: Importance) -> list[Importance]:
+    """The floors a pipeline of this importance clears: its own and every lesser one."""
+    reached = IMPORTANCE_RANK[importance]
+    return [level for level, rank in IMPORTANCE_RANK.items() if rank <= reached]
+
+
+async def matching_rules(
+    session: AsyncSession, event: AlertEvent, pipeline_id: UUID, importance: Importance
+) -> list[AlertRule]:
     """Find the live rules that want to hear about one event, throttled or not.
 
     A paused rule matches nothing. Pausing is instance state an operator sets on the row, so
     it is read here rather than folded into ``active``, which is what the rule itself declares.
+
+    A rule that names an importance wants only the pipelines that carry at least that much;
+    one that names none wants every pipeline, so a rule that pages the critical failures and
+    a rule that logs everything both raise on the same run.
     """
     rows = await session.execute(
         sa.select(AlertRule).where(
@@ -254,6 +292,7 @@ async def matching_rules(session: AsyncSession, event: AlertEvent, pipeline_id:
             AlertRule.active.is_(True),
             AlertRule.paused.is_(False),
             sa.or_(AlertRule.scope == AlertScope.GLOBAL, AlertRule.pipeline_id == pipeline_id),
+            sa.or_(AlertRule.importance.is_(None), AlertRule.importance.in_(_satisfied_levels(importance))),
         )
     )
     return list(rows.scalars())
@@ -268,14 +307,17 @@ async def set_paused(session: AsyncSession, rule: AlertRule, *, paused: bool) ->
 
 
 #: What a PATCH may write on a rule, and nothing else on the row.
-UPDATABLE: Final = ("paused", "template", "body")
+UPDATABLE: Final = ("paused", "template", "body", "importance", "connection")
 
 
-async def update_rule(session: AsyncSession, rule: AlertRule, changes: Mapping[str, object]) -> AlertRule:
+async def update_rule(
+    session: AsyncSession, services: EngineServices, rule: AlertRule, changes: Mapping[str, object]
+) -> AlertRule:
     """Write the fields a PATCH named on a rule, leaving every field it did not name.
 
-    A subject or a body is compiled here as it is at creation, so a rule on the row always
-    holds a template that renders.
+    A subject or a body is compiled here as it is at creation, and a target is resolved here as
+    it is at creation, so a rule on the row always holds a template that renders and a sender a
+    worker can dispatch on.
     """
     named = {name: value for name, value in changes.items() if name in UPDATABLE}
     if "template" in named or "body" in named:
@@ -287,6 +329,16 @@ async def update_rule(session: AsyncSession, rule: AlertRule, changes: Mapping[s
         rule.body = cast("str | None", named.get("body", rule.body))
         await session.flush()
         _logger.info("alert rule retemplated", rule=rule.code)
+    if "importance" in named:
+        floor = cast("Importance | None", named["importance"])
+        rule.importance = floor
+        await session.flush()
+        _logger.info("alert rule reweighted", rule=rule.code, importance=floor.value if floor else None)
+    if "connection" in named:
+        code = cast("str | None", named["connection"])
+        rule.notifier, rule.connection_id = await _target(session, services, code)
+        await session.flush()
+        _logger.info("alert rule retargeted", rule=rule.code, notifier=rule.notifier, connection=code)
     if "paused" in named:
         await set_paused(session, rule, paused=bool(named["paused"]))
     return rule
@@ -386,7 +438,7 @@ async def _queue_for_run(
     pipeline = await session.get(Pipeline, run.pipeline_id)
     if pipeline is None:  # pragma: no cover - the foreign key makes this unreachable
         return []
-    rules = await matching_rules(session, event, run.pipeline_id)
+    rules = await matching_rules(session, event, run.pipeline_id, pipeline.importance)
     if not rules:
         return []
     report_url = report_url_for(services.settings.alert_base_url, report_artifact_id)
@@ -633,26 +685,24 @@ async def queue_test_message(
     session: AsyncSession,
     services: EngineServices,
     *,
-    notifier: str,
     connection: str | None = None,
     subject: str = "dirigent test alert",
     body: str = "This is a test message sent through the notifier surface.",
 ) -> Notification:
     """Queue one unattached message, which is what ``dg alerts test`` sends.
 
-    The subject and the body are rendered as a rule's are, over a stand-in context, so a
-    template can be tried out before it is written onto a rule.
+    The message names one target the way a rule does, and the sender follows from that
+    connection's kind. The subject and the body are rendered as a rule's are, over a stand-in
+    context, so a template can be tried out before it is written onto a rule.
     """
-    if notifier not in services.host.notifiers:
-        installed = ", ".join(sorted(services.host.notifiers)) or "none are installed"
-        raise AlertError(UNKNOWN_NOTIFIER, notifier=repr(notifier), installed=installed)
+    notifier, connection_id = await _target(session, services, connection)
     context: JsonMap = {"run": {"pipeline": "(test)", "status": "succeeded"}, "report": None}
     notification = Notification(
         alert_rule_id=None,
         run_id=None,
         event=AlertEvent.RUN_SUCCEEDED,
         notifier=notifier,
-        connection_id=await _connection_id(session, connection) if connection else None,
+        connection_id=connection_id,
         subject=_one_line(_or_literal(subject, context, max_bytes=SUBJECT_RENDER_CAP)),
         body=_or_literal(body, context, max_bytes=int(services.settings.report_max_size)),
         context=context,

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/engine/definition.py

@@ -9,7 +9,7 @@ from jsonschema import Draft202012Validator, FormatChecker
 from jsonschema import ValidationError as SchemaValidationError
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator
 
-from dirigent_client.enums import RunPriority
+from dirigent_client.enums import Importance, RunPriority
 from dirigent_client.schemas import Requirements
 from dirigent_common import TEMPLATE_MEDIA_TYPE, EntityName, JsonMap, StepName, TemplateError, compile_template
 from dirigent_common.durations import Duration
@@ -314,6 +314,11 @@ class PipelineDefinition(BaseModel):
 
     A trigger may override it for what it fires, and an ad hoc run may override it again."""
 
+    importance: Importance = Importance.NORMAL
+    """How much this pipeline matters, which is not when its work is claimed; priority says that.
+
+    An alert rule may name the least importance a pipeline must have before it fires."""
+
     params: JsonMap = Field(default_factory=lambda: dict(EMPTY_PARAMS_SCHEMA))
     steps: dict[StepName, StepDefinition] = Field(min_length=1)
     triggers: TriggerSpecs = Field(default_factory=TriggerSpecs)

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/engine/runs.py

@@ -166,6 +166,7 @@ async def _save_pipeline_once(
             name=definition.name,
             description=description or definition.description,
             tags=list(definition.tags),
+            importance=definition.importance,
         )
         session.add(pipeline)
         await session.flush()
@@ -176,6 +177,7 @@ async def _save_pipeline_once(
         pipeline.name = definition.name
         pipeline.description = description or definition.description
         pipeline.tags = list(definition.tags)
+        pipeline.importance = definition.importance
     recorded = provenance or Provenance()
     next_version = (pipeline.current_version or 0) + 1
     version = PipelineVersion(

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/messages.py

@@ -6,6 +6,16 @@ renders are what another language, a log reader and a test all hold on to.
 
 from dirigent_common import Catalogue, Message
 
+DATABASE = Catalogue("database")
+
+SCHEMA_STALE = DATABASE.define(
+    "schema_stale",
+    "the database at {where} was written by a different dirigent: {differences} difference(s), "
+    "first {first}; before 1.0 the schema is not migrated, so start from an empty state "
+    "(`dg dev --wipe-state`, or delete the state directory) or point at a database this version created",
+)
+
+
 AUTH = Catalogue("auth")
 
 WEAK_PASSWORD = AUTH.define("weak_password", "a password must be at least {minimum} characters")
@@ -488,8 +498,6 @@ REQUIRED_UNMAPPED = WEBHOOK.define(
 
 ALERT = Catalogue("alert")
 
-UNKNOWN_NOTIFIER = ALERT.define("unknown_notifier", "no notifier {notifier} is installed ({installed})")
-
 DUPLICATE_RULE = ALERT.define("duplicate_rule", "an alert rule coded {code} already exists")
 
 BAD_ALERT_TEMPLATE = ALERT.define("bad_template", "{field} is not a Jinja template: {detail}")
@@ -502,6 +510,11 @@ ALERT_UNKNOWN_PIPELINE = ALERT.define("unknown_pipeline", "no pipeline coded {co
 
 ALERT_UNKNOWN_CONNECTION = ALERT.define("unknown_connection", "no connection coded {code}")
 
+TARGET_HAS_NO_NOTIFIER = ALERT.define(
+    "target_has_no_notifier",
+    "connection {code} is of kind {kind}, which no installed notifier delivers through ({installed})",
+)
+
 ALERT_VERSION_GONE = ALERT.define("version_gone", "run {run} pins a pipeline version that is gone")
 
 NOTIFIER_NOT_ON_WORKER = ALERT.define("notifier_not_on_worker", "notifier {notifier} is not installed on this worker")

dirigent_core-0.18.2/src/dirigent_core/migrations.py

@@ -0,0 +1,203 @@
+"""Programmatic Alembic access, so the CLI, the server, and the tests drive one migration history."""
+
+import asyncio
+import io
+from collections.abc import Iterable, Iterator
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Final
+
+import sqlalchemy as sa
+from alembic import command
+from alembic.autogenerate import compare_metadata
+from alembic.config import Config
+from alembic.runtime.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import Connection
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from dirigent_core.config import Settings, get_settings
+from dirigent_core.database import create_engine
+from dirigent_core.models import Base
+
+#: The migration scripts ship inside the package, so no working directory is assumed.
+ALEMBIC_DIRECTORY = Path(__file__).resolve().parent / "alembic"
+
+
+def alembic_config(settings: Settings | None = None) -> Config:
+    """Build an Alembic config pointing at the packaged migrations and the configured database."""
+    resolved = settings or get_settings()
+    config = Config()
+    config.set_main_option("script_location", str(ALEMBIC_DIRECTORY))
+    config.set_main_option("sqlalchemy.url", resolved.database_url)
+    config.set_main_option("timezone", "UTC")
+    return config
+
+
+def _run_command(connection: Connection, name: str, revision: str, settings: Settings | None) -> None:
+    """Run one Alembic command on an established synchronous connection."""
+    config = alembic_config(settings)
+    config.attributes["connection"] = connection
+    getattr(command, name)(config, revision)
+
+
+async def _with_connection(name: str, revision: str, settings: Settings | None) -> None:
+    """Open the async engine and hand a synchronous connection to Alembic."""
+    engine = create_engine(settings or get_settings())
+    try:
+        async with engine.begin() as connection:
+            await connection.run_sync(_run_command, name, revision, settings)
+    finally:
+        await engine.dispose()
+
+
+async def upgrade_async(revision: str = "head", settings: Settings | None = None) -> None:
+    """Bring the database up to a revision, creating the schema on an empty database."""
+    await _with_connection("upgrade", revision, settings)
+
+
+async def downgrade_async(revision: str, settings: Settings | None = None) -> None:
+    """Take the database back to a revision."""
+    await _with_connection("downgrade", revision, settings)
+
+
+def _read_revision(connection: Connection) -> str | None:
+    """Read the alembic_version stamp from an established connection."""
+    return MigrationContext.configure(connection).get_current_revision()
+
+
+async def current_revision_async(settings: Settings | None = None) -> str | None:
+    """Read the revision the database is stamped with, or None when it has never been migrated."""
+    engine = create_engine(settings or get_settings())
+    try:
+        async with engine.connect() as connection:
+            return await connection.run_sync(_read_revision)
+    finally:
+        await engine.dispose()
+
+
+def upgrade(revision: str = "head", settings: Settings | None = None) -> None:
+    """Run an upgrade from synchronous code, such as the CLI."""
+    asyncio.run(upgrade_async(revision, settings))
+
+
+def downgrade(revision: str, settings: Settings | None = None) -> None:
+    """Run a downgrade from synchronous code, such as the CLI."""
+    asyncio.run(downgrade_async(revision, settings))
+
+
+def current_revision(settings: Settings | None = None) -> str | None:
+    """Read the current revision from synchronous code, such as the CLI."""
+    return asyncio.run(current_revision_async(settings))
+
+
+def head_revision(settings: Settings | None = None) -> str | None:
+    """Read the newest revision the packaged migrations define."""
+    return ScriptDirectory.from_config(alembic_config(settings)).get_current_head()
+
+
+def history(settings: Settings | None = None) -> str:
+    """Render the migration history as Alembic prints it, without touching the database."""
+    config = alembic_config(settings)
+    buffer = io.StringIO()
+    config.stdout = buffer
+    command.history(config, verbose=False)
+    return buffer.getvalue()
+
+
+class DifferenceKind(StrEnum):
+    """What one difference between a live database and the models is."""
+
+    MISSING_TABLE = "missing_table"
+    """The models declare a table the database has not got."""
+
+    MISSING_COLUMN = "missing_column"
+    """A declared table is there, without a column the models give it."""
+
+    EXTRA_COLUMN = "extra_column"
+    """A declared table carries a column the models do not declare."""
+
+    CHANGED = "changed"
+    """A declared table differs some other way: a column's type, an index, a constraint."""
+
+
+#: How each kind reads after the table or column it is about.
+_WORDING: Final[dict[DifferenceKind, str]] = {
+    DifferenceKind.MISSING_TABLE: "missing",
+    DifferenceKind.MISSING_COLUMN: "missing",
+    DifferenceKind.EXTRA_COLUMN: "unexpected",
+    DifferenceKind.CHANGED: "changed",
+}
+
+
+class SchemaDifference(BaseModel):
+    """One way a live database differs from the models, named where it is."""
+
+    model_config = ConfigDict(frozen=True)
+
+    kind: DifferenceKind
+    """What the difference is."""
+
+    table: str
+    """The table it is in."""
+
+    column: str | None = None
+    """The column it is in, when the difference is about one."""
+
+    def __str__(self) -> str:
+        """Render the difference as the phrase a refusal names it by."""
+        where = f"{self.table}.{self.column}" if self.column else f"table {self.table}"
+        return f"{where} {_WORDING[self.kind]}"
+
+
+def _flattened(differences: Iterable[Any]) -> Iterator[tuple[Any, ...]]:
+    """Walk Alembic's diff list, which groups several changes to one column in a nested list."""
+    for entry in differences:
+        if isinstance(entry, list):
+            yield from entry
+        else:
+            yield entry
+
+
+def _named(difference: tuple[Any, ...]) -> SchemaDifference | None:
+    """Name the table and column one Alembic difference is about.
+
+    A table the models do not declare is not a difference: the database may be shared, and
+    nothing dirigent runs reads it.
+    """
+    what = difference[0]
+    if what == "add_table":
+        return SchemaDifference(kind=DifferenceKind.MISSING_TABLE, table=difference[1].name)
+    if what == "remove_table":
+        return None
+    if what == "add_column":
+        return SchemaDifference(kind=DifferenceKind.MISSING_COLUMN, table=difference[2], column=difference[3].name)
+    if what == "remove_column":
+        return SchemaDifference(kind=DifferenceKind.EXTRA_COLUMN, table=difference[2], column=difference[3].name)
+    if what.startswith("modify_"):
+        return SchemaDifference(kind=DifferenceKind.CHANGED, table=difference[2], column=difference[3])
+    element = difference[1]
+    table = element if isinstance(element, sa.Table) else getattr(element, "table", None)
+    return None if table is None else SchemaDifference(kind=DifferenceKind.CHANGED, table=table.name)
+
+
+def _compare(connection: Connection) -> list[SchemaDifference]:
+    """Diff one live connection's schema against the ORM metadata."""
+    context = MigrationContext.configure(connection, opts={"compare_type": True, "include_schemas": False})
+    found = [_named(difference) for difference in _flattened(compare_metadata(context, Base.metadata))]
+    differences = [one for one in found if one is not None]
+    absent = {one.table for one in differences if one.kind is DifferenceKind.MISSING_TABLE}
+    # Every index and constraint of a table that is not there restates the missing table.
+    return [one for one in differences if one.kind is DifferenceKind.MISSING_TABLE or one.table not in absent]
+
+
+async def schema_differences(engine: AsyncEngine) -> list[SchemaDifference]:
+    """Say how the live database differs from the models, in one reflection.
+
+    Empty means the database holds the schema this code was built against. Before 1.0 the
+    baseline migration is edited in place, so a database an older dirigent wrote is stamped
+    at the same revision and the stamp cannot answer this; reflection can.
+    """
+    async with engine.connect() as connection:
+        return await connection.run_sync(_compare)

{dirigent_core-0.18.0 → dirigent_core-0.18.2}/src/dirigent_core/models.py

@@ -13,6 +13,7 @@ from dirigent_client.enums import (
     AttemptKind,
     AttemptStatus,
     FiringOutcome,
+    Importance,
     LogLevel,
     NotificationStatus,
     ProvenanceSource,
@@ -91,6 +92,17 @@ class Pipeline(Entity):
     tags: Mapped[JsonList] = mapped_column(JsonDocument, nullable=False, default=list)
     """What the current document says this pipeline is for; an apply replaces the whole list."""
 
+    importance: Mapped[Importance] = mapped_column(
+        string_enum(Importance, "importance"),
+        nullable=False,
+        default=Importance.NORMAL,
+        server_default=Importance.NORMAL.value,
+    )
+    """How much the current document says this pipeline matters.
+
+    On the row rather than read from the version document, so an alert rule matches without
+    loading one."""
+
     active: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=True, server_default=sa.true())
     current_version: Mapped[int | None] = mapped_column(sa.Integer)
 
@@ -485,6 +497,9 @@ class AlertRule(Entity):
         string_enum(AlertScope, "alert_scope"), nullable=False, default=AlertScope.GLOBAL
     )
     pipeline_id: Mapped[UUID | None] = mapped_column(sa.ForeignKey("pipelines.id", ondelete="CASCADE"), index=True)
+    importance: Mapped[Importance | None] = mapped_column(string_enum(Importance, "importance"))
+    """The least importance a pipeline must carry before this rule fires; null fires for every one."""
+
     notifier: Mapped[str] = mapped_column(sa.String(100), nullable=False)
     connection_id: Mapped[UUID | None] = mapped_column(sa.ForeignKey("connections.id", ondelete="RESTRICT"))
     template: Mapped[str | None] = mapped_column(sa.Text)

dirigent_core-0.18.0/src/dirigent_core/migrations.py

@@ -1,98 +0,0 @@
-"""Programmatic Alembic access, so the CLI, the server, and the tests drive one migration history."""
-
-import asyncio
-import io
-from pathlib import Path
-
-from alembic import command
-from alembic.config import Config
-from alembic.runtime.migration import MigrationContext
-from alembic.script import ScriptDirectory
-from sqlalchemy import Connection
-
-from dirigent_core.config import Settings, get_settings
-from dirigent_core.database import create_engine
-
-#: The migration scripts ship inside the package, so no working directory is assumed.
-ALEMBIC_DIRECTORY = Path(__file__).resolve().parent / "alembic"
-
-
-def alembic_config(settings: Settings | None = None) -> Config:
-    """Build an Alembic config pointing at the packaged migrations and the configured database."""
-    resolved = settings or get_settings()
-    config = Config()
-    config.set_main_option("script_location", str(ALEMBIC_DIRECTORY))
-    config.set_main_option("sqlalchemy.url", resolved.database_url)
-    config.set_main_option("timezone", "UTC")
-    return config
-
-
-def _run_command(connection: Connection, name: str, revision: str, settings: Settings | None) -> None:
-    """Run one Alembic command on an established synchronous connection."""
-    config = alembic_config(settings)
-    config.attributes["connection"] = connection
-    getattr(command, name)(config, revision)
-
-
-async def _with_connection(name: str, revision: str, settings: Settings | None) -> None:
-    """Open the async engine and hand a synchronous connection to Alembic."""
-    engine = create_engine(settings or get_settings())
-    try:
-        async with engine.begin() as connection:
-            await connection.run_sync(_run_command, name, revision, settings)
-    finally:
-        await engine.dispose()
-
-
-async def upgrade_async(revision: str = "head", settings: Settings | None = None) -> None:
-    """Bring the database up to a revision, creating the schema on an empty database."""
-    await _with_connection("upgrade", revision, settings)
-
-
-async def downgrade_async(revision: str, settings: Settings | None = None) -> None:
-    """Take the database back to a revision."""
-    await _with_connection("downgrade", revision, settings)
-
-
-def _read_revision(connection: Connection) -> str | None:
-    """Read the alembic_version stamp from an established connection."""
-    return MigrationContext.configure(connection).get_current_revision()
-
-
-async def current_revision_async(settings: Settings | None = None) -> str | None:
-    """Read the revision the database is stamped with, or None when it has never been migrated."""
-    engine = create_engine(settings or get_settings())
-    try:
-        async with engine.connect() as connection:
-            return await connection.run_sync(_read_revision)
-    finally:
-        await engine.dispose()
-
-
-def upgrade(revision: str = "head", settings: Settings | None = None) -> None:
-    """Run an upgrade from synchronous code, such as the CLI."""
-    asyncio.run(upgrade_async(revision, settings))
-
-
-def downgrade(revision: str, settings: Settings | None = None) -> None:
-    """Run a downgrade from synchronous code, such as the CLI."""
-    asyncio.run(downgrade_async(revision, settings))
-
-
-def current_revision(settings: Settings | None = None) -> str | None:
-    """Read the current revision from synchronous code, such as the CLI."""
-    return asyncio.run(current_revision_async(settings))
-
-
-def head_revision(settings: Settings | None = None) -> str | None:
-    """Read the newest revision the packaged migrations define."""
-    return ScriptDirectory.from_config(alembic_config(settings)).get_current_head()
-
-
-def history(settings: Settings | None = None) -> str:
-    """Render the migration history as Alembic prints it, without touching the database."""
-    config = alembic_config(settings)
-    buffer = io.StringIO()
-    config.stdout = buffer
-    command.history(config, verbose=False)
-    return buffer.getvalue()