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

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

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: dirigent-cli
-Version: 0.18.0
+Version: 0.18.2
 Summary: The dirigent command line interface (dirigent / dg).
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-block-execute==0.18.0
-Requires-Dist: dirigent-blocks==0.18.0
-Requires-Dist: dirigent-client==0.18.0
-Requires-Dist: dirigent-common==0.18.0
-Requires-Dist: dirigent-core==0.18.0
-Requires-Dist: dirigent-examples==0.18.0
-Requires-Dist: dirigent-plugin==0.18.0
-Requires-Dist: dirigent-server==0.18.0
+Requires-Dist: dirigent-block-execute==0.18.2
+Requires-Dist: dirigent-blocks==0.18.2
+Requires-Dist: dirigent-client==0.18.2
+Requires-Dist: dirigent-common==0.18.2
+Requires-Dist: dirigent-core==0.18.2
+Requires-Dist: dirigent-examples==0.18.2
+Requires-Dist: dirigent-plugin==0.18.2
+Requires-Dist: dirigent-server==0.18.2
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: pyyaml>=6.0.3

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

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.18.0"
+version = "0.18.2"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,14 +11,14 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-block-execute==0.18.0",
-    "dirigent-blocks==0.18.0",
-    "dirigent-client==0.18.0",
-    "dirigent-common==0.18.0",
-    "dirigent-core==0.18.0",
-    "dirigent-examples==0.18.0",
-    "dirigent-plugin==0.18.0",
-    "dirigent-server==0.18.0",
+    "dirigent-block-execute==0.18.2",
+    "dirigent-blocks==0.18.2",
+    "dirigent-client==0.18.2",
+    "dirigent-common==0.18.2",
+    "dirigent-core==0.18.2",
+    "dirigent-examples==0.18.2",
+    "dirigent-plugin==0.18.2",
+    "dirigent-server==0.18.2",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

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

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.18.0"
+version = "0.18.2"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,14 +11,14 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-block-execute==0.18.0",
-    "dirigent-blocks==0.18.0",
-    "dirigent-client==0.18.0",
-    "dirigent-common==0.18.0",
-    "dirigent-core==0.18.0",
-    "dirigent-examples==0.18.0",
-    "dirigent-plugin==0.18.0",
-    "dirigent-server==0.18.0",
+    "dirigent-block-execute==0.18.2",
+    "dirigent-blocks==0.18.2",
+    "dirigent-client==0.18.2",
+    "dirigent-common==0.18.2",
+    "dirigent-core==0.18.2",
+    "dirigent-examples==0.18.2",
+    "dirigent-plugin==0.18.2",
+    "dirigent-server==0.18.2",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/commands.py

@@ -15,6 +15,7 @@ from rich.markup import escape
 
 from dirigent_cli import schemas, starters
 from dirigent_cli.context import CliState, Session, client_for, state_of
+from dirigent_cli.explain import explain as document_shape
 from dirigent_cli.graph import GraphStep, render_graph, steps_of_document
 from dirigent_cli.local import (
     ConnectionSpec,
@@ -61,6 +62,7 @@ from dirigent_cli.messages import (
     NOT_A_RUN_STATUS,
     NOT_A_STARTER,
     NOT_A_WINDOW,
+    NOT_AN_IMPORTANCE,
     NOT_AUTHENTICATED,
     OR_A_PROFILE_TOKEN,
     OR_DG_AUTH_LOGIN,
@@ -104,6 +106,7 @@ from dirigent_cli.output import (
     prioritised,
     refuse,
     render_bool,
+    render_check,
     stream_line,
     styled,
     table,
@@ -140,6 +143,7 @@ from dirigent_client import (
     DocumentKind,
     ExampleDetail,
     ExampleOut,
+    Importance,
     ItemOut,
     LogEntryOut,
     LogLevel,
@@ -467,11 +471,18 @@ def validate_command(
     server: Annotated[
         bool, typer.Option("--server", help="Also check it against a server's catalog and requirements.")
     ] = False,
+    explain: Annotated[
+        bool, typer.Option("--explain", help="Also say what the work will cost: how wide, how many tries, how long.")
+    ] = False,
 ) -> None:
     """Check a document offline, or against a server's catalog too with --server.
 
     Offline, a triggers document is checked at the schema level: its clocks and its codes.
     `--server` adds the pipeline it names and the parameters its schedules pin.
+
+    `--explain` adds the shape of the work ahead for every pipeline document that is valid:
+    the fan-out widths, the retry budgets and the waits. With `--server` too, a sensor that
+    declares neither cadence nor deadline takes the block's own.
     """
     state = state_of(ctx)
     documents = _documents_to_apply(reference, None)
@@ -524,16 +535,26 @@ def validate_command(
             )
             failures += 1
             continue
+        checked = "document and catalog" if catalog is not None else "document, offline"
         emit_fact(
             "validation",
             message="valid",
             code=definition.code,
             document=label,
-            checked="document and catalog" if catalog is not None else "document, offline",
+            checked=checked,
             steps=[step._asdict() for step in graph_steps(definition)]
             if isinstance(definition, PipelineDefinition)
             else None,
         )
+        if explain and isinstance(definition, PipelineDefinition):
+            emit_fact(
+                "validation.shape",
+                message="shape",
+                code=definition.code,
+                document=label,
+                checked=checked,
+                **document_shape(definition, catalog).model_dump(mode="json"),
+            )
     emit_fact(
         "validated",
         level="error" if failures else "info",
@@ -831,6 +852,7 @@ def pipeline_show(
             "name": row.name or "-",
             "description": row.description or "-",
             "tags": " ".join(row.tags) or "-",
+            "importance": row.importance.value,
             "active": "yes" if row.active else "no",
             "current version": row.current_version,
             "runs in flight": row.active_runs,
@@ -1049,6 +1071,20 @@ def parse_priority(value: str | None) -> RunPriority | None:
         )
 
 
+def parse_importance(value: str | None) -> Importance | None:
+    """Read the importance a rule was given, naming the vocabulary when it is not one."""
+    if value is None:
+        return None
+    try:
+        return Importance(value.lower())
+    except ValueError:
+        fail(
+            NOT_AN_IMPORTANCE,
+            value=repr(value),
+            allowed=", ".join(importance.value for importance in Importance),
+        )
+
+
 def run_command(
     ctx: typer.Context,
     target: Annotated[str, typer.Argument(help="A pipeline code, or a document file, URL, or -.")],
@@ -2285,7 +2321,7 @@ def connection_list(
                 row.name or "-",
                 row.kind,
                 moment(row.last_check_at),
-                render_bool(row.last_check_healthy),
+                render_check(row.last_check_at, row.last_check_healthy),
                 row.description or "-",
             ]
             for row in rows
@@ -2389,18 +2425,21 @@ def connection_show(
 
 @connection_app.command("check")
 def connection_check(ctx: typer.Context, code: Annotated[str, typer.Argument()]) -> None:
-    """Ask a connection's own kind whether its external system answers."""
+    """Ask a connection's own kind whether its external system answers.
+
+    A check that ran and could not decide is not a failure, so only a refused one exits 1.
+    """
     with client_for(state_of(ctx)) as dg:
         report = dg.call(dg.connections.check(code))
     emit_fact(
         "connection.checked",
-        message="healthy" if report.healthy else "unhealthy",
+        message="not verified" if report.healthy is None else "healthy" if report.healthy else "unhealthy",
         code=code,
         healthy=report.healthy,
         detail=report.detail,
         version=report.version,
     )
-    if not report.healthy:
+    if report.healthy is False:
         raise typer.Exit(code=1)
 
 
@@ -2541,7 +2580,7 @@ def system_info(
                     row.name or "-",
                     row.kind,
                     moment(row.last_check_at),
-                    render_bool(row.last_check_healthy),
+                    render_check(row.last_check_at, row.last_check_healthy),
                     row.last_check_detail or "-",
                 ]
                 for row in info.connections

dirigent_cli-0.18.2/src/dirigent_cli/explain.py

@@ -0,0 +1,237 @@
+"""What a document will cost before it runs: how wide, how many tries, how long it may wait.
+
+Everything here is read off the document, and off the catalog where a server hands one over.
+Nothing executes, so the numbers are the ones the engine fixes when it creates a run: a
+fan-out's cardinality, the attempts a retry policy allows, and the waits a step may spend
+under a deadline. What only the run can decide -- a parameter supplied at the command line,
+a window's bounds -- is reported as unknown rather than guessed at, and a total that counted
+one of those says so.
+
+The cardinality rules are :func:`dirigent_core.engine.runs.resolve_fan_out`'s: a literal list
+is its own length, ``${steps.<name>.items}`` adopts another fan-out's grid, a reference that
+resolves to a list is that list, and anything else is only the run's to answer.
+"""
+
+from collections.abc import Mapping, Sequence
+from datetime import timedelta
+from typing import Final
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dirigent_cli.schemas import ShapeWarning, StepShape
+from dirigent_client.schemas import BlockEntry, BlockKind, Catalog
+from dirigent_common import Duration, JsonMap, base_format_checker, format_duration
+from dirigent_core.engine.definition import ParameterError, PipelineDefinition, RetryPolicy, StepDefinition
+from dirigent_core.engine.failure import backoff_delay
+from dirigent_core.engine.references import ReferenceScope, UnknownReference, resolve
+
+#: What a cardinality says when the document alone cannot fix it.
+UNKNOWN: Final = "unknown"
+
+#: How a cardinality names the fan-out whose grid a step maps over instead of its own.
+ADOPTS: Final = "adopts {step}"
+
+
+class DocumentShape(BaseModel):
+    """What a whole document will cost: the steps, the totals over them, and the warnings."""
+
+    model_config = ConfigDict(frozen=True)
+
+    attempts_max: int = 0
+    """Every attempt the document allows: each step's tries times the items it maps over."""
+
+    attempts_at_least: bool = False
+    """Whether that total is a floor, a cardinality only the run can fix having counted once."""
+
+    deadline_longest: Duration | None = None
+    """The longest chain of deadlines through the DAG, which is the wait the document allows."""
+
+    steps: list[StepShape] = Field(default_factory=list[StepShape])
+    warnings: list[ShapeWarning] = Field(default_factory=list[ShapeWarning])
+
+
+def explain(definition: PipelineDefinition, catalog: Catalog | None = None) -> DocumentShape:
+    """Read a document as the work it will become, in the order the steps will run.
+
+    ``catalog`` is a server's, where one was asked for: a sensor that declares no cadence and
+    no deadline of its own takes the block's, and the row says which of the two came from
+    there. With no catalog the document's own values are all there is.
+    """
+    params = _param_defaults(definition)
+    order = definition.topological_order()
+    shapes: dict[str, StepShape] = {}
+    for name in order:
+        shapes[name] = _step_shape(name, definition.steps[name], params, shapes, catalog)
+    rows = [shapes[name] for name in order]
+    return DocumentShape(
+        attempts_max=sum(row.max_attempts * (1 if row.elements is None else row.elements) for row in rows),
+        attempts_at_least=any(row.elements is None for row in rows),
+        deadline_longest=_deadline_longest(definition, shapes, order),
+        steps=rows,
+        warnings=_warnings(rows, catalog),
+    )
+
+
+def _param_defaults(definition: PipelineDefinition) -> JsonMap:
+    """Fill the parameters a run would be given with the defaults the document declares.
+
+    A parameter with no default is one only the run supplies, and every cardinality that
+    reads one is unknown here rather than wrong.
+    """
+    try:
+        return definition.validate_params({}, base_format_checker())
+    except ParameterError:
+        return {}
+
+
+def _step_shape(
+    name: str,
+    step: StepDefinition,
+    params: JsonMap,
+    done: Mapping[str, StepShape],
+    catalog: Catalog | None,
+) -> StepShape:
+    """Read one step as the work it will become, against the steps already read."""
+    cardinality, elements = _cardinality(step, params, done)
+    poll, deadline, from_block = _waits(step, _entry(step, catalog))
+    return StepShape(
+        name=name,
+        block=step.block,
+        depends_on=list(step.depends_on),
+        cardinality=cardinality,
+        elements=elements,
+        reference=step.for_each if isinstance(step.for_each, str) else None,
+        items=step.items.value,
+        max_attempts=step.retry.max_attempts,
+        retry_wait=_retry_wait(step.retry),
+        timeout=step.timeout,
+        poll=poll,
+        deadline=deadline,
+        on_timeout=step.on_timeout.value,
+        from_block=from_block,
+    )
+
+
+def _cardinality(step: StepDefinition, params: JsonMap, done: Mapping[str, StepShape]) -> tuple[int | str, int | None]:
+    """Say how many run items a step becomes, and the count behind that where there is one."""
+    expression = step.for_each
+    if expression is None:
+        return 1, 1
+    if isinstance(expression, list):
+        return len(expression), len(expression)
+    adopted = step.adopted_grid
+    if adopted is not None:
+        upstream = done[adopted].elements if adopted in done else None
+        return ADOPTS.format(step=adopted), upstream
+    if "steps." in expression:
+        # resolve_fan_out refuses a step's output here, because cardinality is fixed when the
+        # run is created and no step has run by then.
+        return UNKNOWN, None
+    try:
+        resolved = resolve(expression, ReferenceScope(params=params))
+    except UnknownReference:
+        return UNKNOWN, None
+    if not isinstance(resolved, list):
+        return UNKNOWN, None
+    return len(resolved), len(resolved)
+
+
+def _entry(step: StepDefinition, catalog: Catalog | None) -> BlockEntry | None:
+    """Find what the catalog says about this step's block, where there is a catalog."""
+    return None if catalog is None else catalog.block(step.block)
+
+
+def _waits(step: StepDefinition, entry: BlockEntry | None) -> tuple[timedelta | None, timedelta | None, list[str]]:
+    """Take the cadence and the deadline from the document, then from the block's own defaults."""
+    poll, deadline = step.poll, step.deadline
+    from_block: list[str] = []
+    if entry is None:
+        return poll, deadline, from_block
+    if poll is None and entry.default_poll_seconds is not None:
+        poll = timedelta(seconds=entry.default_poll_seconds)
+        from_block.append("poll")
+    if deadline is None and entry.default_deadline_seconds is not None:
+        deadline = timedelta(seconds=entry.default_deadline_seconds)
+        from_block.append("deadline")
+    return poll, deadline, from_block
+
+
+def _retry_wait(policy: RetryPolicy) -> timedelta | None:
+    """Add up every backoff the policy allows, at the top of the jitter it spreads them over.
+
+    ``max_attempts`` tries have one delay fewer between them, and each delay is the engine's
+    own: exponential, clamped at ``max_backoff``, and then spread by the jitter.
+    """
+    if policy.max_attempts <= 1:
+        return None
+    steady = policy.model_copy(update={"jitter": 0.0})
+    total = sum((backoff_delay(steady, attempt) for attempt in range(1, policy.max_attempts)), timedelta(0))
+    return total * (1 + policy.jitter)
+
+
+def _deadline_longest(
+    definition: PipelineDefinition, shapes: Mapping[str, StepShape], order: Sequence[str]
+) -> timedelta | None:
+    """Add the deadlines along each path through the DAG and take the longest of them.
+
+    A step cannot start before its dependencies settled, so the chain is what the document
+    allows end to end; a step with no deadline lengthens no chain.
+    """
+    chains: dict[str, timedelta] = {}
+    for name in order:
+        upstream = max((chains[one] for one in definition.steps[name].depends_on), default=timedelta(0))
+        chains[name] = upstream + (shapes[name].deadline or timedelta(0))
+    longest = max(chains.values(), default=timedelta(0))
+    return longest or None
+
+
+def _warnings(rows: Sequence[StepShape], catalog: Catalog | None) -> list[ShapeWarning]:
+    """Name what the document leaves unbounded or unresolved, one sentence each."""
+    found: list[ShapeWarning] = []
+    for row in rows:
+        # The step that named the reference is warned about; one that adopts its grid has the
+        # same unknown width and no second cause.
+        if row.cardinality == UNKNOWN:
+            found.append(
+                ShapeWarning(
+                    step=row.name,
+                    cause="unknown-cardinality",
+                    message=(
+                        f"{row.name} fans out over {row.reference}, which only the run can resolve, "
+                        f"so it is counted as one item here."
+                    ),
+                )
+            )
+        if row.retry_wait is not None and row.deadline is not None and row.retry_wait > row.deadline:
+            found.append(
+                ShapeWarning(
+                    step=row.name,
+                    cause="retry-outlasts-deadline",
+                    message=(
+                        f"{row.name} may spend {format_duration(row.retry_wait)} in backoff between its "
+                        f"{row.max_attempts} attempts, which is longer than the {format_duration(row.deadline)} "
+                        f"deadline each one waits under."
+                    ),
+                )
+            )
+        if row.deadline is None and _is_sensor(row, catalog):
+            found.append(ShapeWarning(step=row.name, cause="unbounded-sensor", message=_unbounded(row, catalog)))
+    return found
+
+
+def _unbounded(row: StepShape, catalog: Catalog | None) -> str:
+    """Say that nothing bounds a sensor's wait, and where a catalog would still fill one in."""
+    if catalog is None:
+        return f"{row.name} polls with no deadline, so nothing here bounds its wait: --server reads the block's."
+    return f"{row.name} waits on a sensor that neither the document nor {row.block} gives a deadline."
+
+
+def _is_sensor(row: StepShape, catalog: Catalog | None) -> bool:
+    """Report whether a step waits on a sensor, by the catalog where there is one.
+
+    Offline there is nothing to ask, and a cadence is the one thing only a sensor carries.
+    """
+    if catalog is None:
+        return row.poll is not None
+    entry = catalog.block(row.block)
+    return entry is not None and entry.kind is BlockKind.SENSOR

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/main.py

@@ -52,6 +52,7 @@ from dirigent_common import Issue
 from dirigent_core import migrations
 from dirigent_core.config import STATE_DIR, Settings, get_settings, redacted_url, reset_settings_cache
 from dirigent_core.logging import configure_logging, silence_stdout
+from dirigent_core.messages import SCHEMA_STALE
 from dirigent_core.protocol import FORMATS, Format, Record, make
 from dirigent_core.telemetry import configure_telemetry
 
@@ -64,6 +65,7 @@ if TYPE_CHECKING:
     from dirigent_cli.stream import Sink
     from dirigent_common import JsonMap
     from dirigent_core import retention
+    from dirigent_core.migrations import SchemaDifference
     from dirigent_core.worker import Worker
 
 #: Help is capped rather than stretched: a panel the width of a wide terminal is unreadable.
@@ -703,6 +705,7 @@ def server(
             problems=[Issue.of(USE_DG_DEV_STANDALONE), Issue.of(OR_NO_SCHEDULER), Issue.of(OR_POSTGRES)],
         )
         raise typer.Exit(code=commands.GUARD_EXIT)
+    guard_schema(settings)
     uvicorn.run(
         "dirigent_cli.main:build_app",
         factory=True,
@@ -912,6 +915,7 @@ def dev(
         if cleared is not None:
             emit(state_cleared(cleared))
     migrated = _migrate_quietly(settings)
+    guard_schema(settings)
     admin, token = asyncio.run(dev_admin(settings))
     address = host or settings.host
     listening = port or settings.port
@@ -966,6 +970,47 @@ def _migrate_quietly(settings: Settings) -> str | None:
     return head
 
 
+async def _schema_differences(settings: Settings) -> list["SchemaDifference"]:
+    """Read the live schema once, and dispose of the engine that read it."""
+    from dirigent_core.database import create_engine
+
+    engine = create_engine(settings)
+    try:
+        return await migrations.schema_differences(engine)
+    finally:
+        await engine.dispose()
+
+
+def guard_schema(settings: Settings) -> None:
+    """Refuse a database whose schema is not the one this dirigent's models describe.
+
+    Before 1.0 the baseline migration is edited in place, so a state an older dirigent wrote
+    is stamped at the same revision and there is nothing for an upgrade to do. Reflection is
+    what answers instead, and a process given such a file would otherwise start, say ready,
+    and fail every query it ever ran.
+    """
+    import asyncio
+
+    from dirigent_cli.health import where_database
+
+    # A database nothing has ever migrated is a different fault, which this refusal and its
+    # remedies would name wrongly.
+    if migrations.current_revision(settings) is None:
+        return
+    differences = asyncio.run(_schema_differences(settings))
+    if not differences:
+        return
+    refuse(
+        SCHEMA_STALE,
+        status=commands.GUARD_EXIT,
+        title="A state an older dirigent wrote",
+        where=where_database(settings),
+        differences=len(differences),
+        first=str(differences[0]),
+    )
+    raise typer.Exit(code=commands.GUARD_EXIT)
+
+
 def dev_started(
     settings: Settings, *, bound: str, admin: str | None, token: str | None, migrated: str | None
 ) -> Record:
@@ -1212,6 +1257,7 @@ def worker(
             problems=[Issue.of(USE_DG_DEV), Issue.of(OR_POSTGRES)],
         )
         raise typer.Exit(code=commands.GUARD_EXIT)
+    guard_schema(settings)
     asyncio.run(_worker(settings, concurrency, tag, name))
 
 
@@ -1247,6 +1293,7 @@ def scheduler_command(ctx: typer.Context) -> None:
             problems=[Issue.of(USE_DG_DEV), Issue.of(OR_POSTGRES)],
         )
         raise typer.Exit(code=commands.GUARD_EXIT)
+    guard_schema(settings)
     emit(
         make(
             "process",
@@ -1308,7 +1355,7 @@ VALUE_OPTIONS = frozenset(
         "--concurrency",
         "--tag",
         "--event",
-        "--notifier",
+        "--connection",
         "--status",
         "--pipeline",
         "--since",

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

@@ -217,6 +217,8 @@ MAP_TAKES_A_PATH = CLI.define(
 
 NOT_AN_ALERT_EVENT = CLI.define("not_an_alert_event", "{event} is not an alert event ({allowed})")
 
+NOT_AN_IMPORTANCE = CLI.define("not_an_importance", "--importance {value} is not an importance ({allowed})")
+
 ONE_BODY = CLI.define("one_body", "a rule takes one body: --body or --body-file, not both")
 
 SCAFFOLD_REFUSED = CLI.define("scaffold_refused", "{detail}")

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/output.py

@@ -19,7 +19,7 @@ from rich.table import Table
 from rich.text import Text
 
 from dirigent_client.schemas.common import Problem
-from dirigent_common import Issue, Message
+from dirigent_common import DurationError, Issue, Message, format_duration, to_timedelta
 from dirigent_core.protocol import Format, Record, as_json, make
 
 #: Whether the environment asked for no colour. Rich decides colour when a console is built,
@@ -474,6 +474,42 @@ def prioritised(priority: object) -> str:
             return ""
 
 
+def watching(scope: object, importance: object) -> str:
+    """What an alert rule watches, in one cell: its scope, and the floor it fires at.
+
+    Almost every rule names no importance, so a column of its own would mostly be empty.
+    """
+    return f"{scope}, {importance} and above" if importance else str(scope)
+
+
+#: What each alert event is called in a rendering. The wire's word is what a rule is declared
+#: with; these are the words a reader is shown, here and on the web UI's own listing.
+ALERT_EVENTS: Mapping[str, str] = {
+    "run_failed": "Failed",
+    "run_completed_with_errors": "Completed with errors",
+    "run_succeeded": "Succeeded",
+    "run_stuck": "Stuck",
+}
+
+
+def alert_event(event: object) -> str:
+    """Render what a rule watches for, falling back to the wire's word for an unknown event."""
+    return ALERT_EVENTS.get(str(event), str(event))
+
+
+def throttle_note(window: object) -> str:
+    """Render a rule's throttle, and of an unthrottled one that it is not throttled.
+
+    A zero is the absence of a window rather than a very short one, and a column of durations
+    is read as durations. A duration this build cannot read is left as the server spelled it.
+    """
+    try:
+        held = to_timedelta(window)
+    except DurationError:
+        return str(window)
+    return format_duration(held) if held else "none"
+
+
 def status_cell(value: object, width: int = STATUS_WIDTH) -> str:
     """Render a status padded to a fixed width, then coloured.
 
@@ -493,6 +529,19 @@ def render_bool(value: object) -> str:
     return "[green]yes[/]" if value else "[dim]no[/]"
 
 
+def render_check(last_check_at: object, healthy: object) -> str:
+    """Render what a connection's last check said, across the four states a row can be in.
+
+    A check answers yes, no, or that it could not decide; a row nothing has checked answers
+    none of the three.
+    """
+    if not last_check_at:
+        return "-"
+    if healthy is None:
+        return "[dim]not verified[/]"
+    return "[green]yes[/]" if healthy else "[dim]no[/]"
+
+
 def moment(value: object) -> str:
     """Render a timestamp compactly, in the local time an operator is reading it in."""
     if not value:

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/schemas.py

@@ -1,16 +1,16 @@
-"""What the closing ``run`` record of a run's stream carries.
+"""What the rows inside a record carry: a run's steps, a backfill's windows, a document's shape.
 
-A run's stream is written record by record through :mod:`dirigent_core.protocol`; these are
-the shapes of the summaries the last record holds. They are the contract a script filters on,
-and they are also what the end-of-run table and the failure diagnosis are rendered from, so a
-field the rendering needs belongs here rather than in a second query.
+Records are written through :mod:`dirigent_core.protocol`; these are the shapes of the
+collections one carries beneath its line. They are the contract a script filters on, and they
+are also what the table under that line is rendered from, so a field the rendering needs
+belongs here rather than in a second query.
 """
 
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from dirigent_common import JsonMap
+from dirigent_common import Duration, JsonMap
 
 
 class StepSummary(BaseModel):
@@ -53,6 +53,51 @@ class FailureSummary(BaseModel):
     """What the attempt was given, which is half of why it failed."""
 
 
+class StepShape(BaseModel):
+    """What one step of a checked document will become, before anything has run."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    """The step's own map key, which is what every reference to it is written with."""
+
+    block: str
+    depends_on: list[str] = Field(default_factory=list[str])
+
+    cardinality: int | str = 1
+    """How many run items this step becomes: a count, ``adopts <step>``, or ``unknown``."""
+
+    elements: int | None = 1
+    """The count behind the cardinality, which an adoption takes from the grid it adopts."""
+
+    reference: str | None = None
+    """The ``for_each`` this step maps over, where it names one rather than listing it."""
+
+    items: str = "fail_fast"
+    max_attempts: int = 1
+
+    retry_wait: Duration | None = None
+    """The longest this step may spend in backoff, which is every delay its policy allows."""
+
+    timeout: Duration | None = None
+    poll: Duration | None = None
+    deadline: Duration | None = None
+    on_timeout: str = "fail"
+
+    from_block: list[str] = Field(default_factory=list[str])
+    """Which of this row's waits the block's own defaults filled, the document declaring none."""
+
+
+class ShapeWarning(BaseModel):
+    """One thing about a document's shape worth knowing before the run, said as a sentence."""
+
+    model_config = ConfigDict(frozen=True)
+
+    step: str
+    cause: str
+    message: str
+
+
 class BackfillWindow(BaseModel):
     """One window a backfill enumerated, as the closing backfill record carries it."""
 

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/summaries.py

@@ -10,6 +10,7 @@ next week has nothing else to consult either.
 """
 
 from collections.abc import Callable, Mapping, Sequence
+from datetime import timedelta
 from typing import Final, cast
 
 from pydantic import BaseModel
@@ -31,6 +32,7 @@ from dirigent_cli.output import (
     render_output,
     styled,
 )
+from dirigent_common import format_duration, to_timedelta
 from dirigent_core.protocol import Record
 
 #: Fields a record carries for what is drawn beneath its line rather than for the line. A
@@ -39,6 +41,7 @@ BULKY: Final = frozenset(
     {
         "steps",
         "failures",
+        "warnings",
         "windows",
         "packages",
         "settings",
@@ -395,6 +398,78 @@ def _graph_step(one: Mapping[str, object]) -> GraphStep:
     )
 
 
+def _shape(record: Record) -> RenderableType | None:
+    """Render what a document will cost: each step's shape, the totals, and the warnings."""
+    steps: list[schemas.StepShape] = _rows(record, "steps", schemas.StepShape)
+    if not steps:
+        return None
+    parts: list[RenderableType] = [
+        build_table(
+            f"what {record.get('code')} will cost",
+            ["step", "block", "cardinality", "attempts", "retry wait", "timeout", "deadline", "poll"],
+            [
+                [
+                    escape(row.name),
+                    escape(row.block),
+                    _width(row),
+                    str(row.max_attempts),
+                    _wait(row.retry_wait),
+                    _wait(row.timeout),
+                    _deadline(row),
+                    _wait(row.poll, from_block="poll" in row.from_block),
+                ]
+                for row in steps
+            ],
+        ),
+        "",
+        build_fields(
+            "the whole document",
+            {
+                "steps": len(steps),
+                "attempts": _attempts(record),
+                "deadline chain": _wait(_duration(record, "deadline_longest")),
+            },
+        ),
+    ]
+    warned = _rows(record, "warnings", schemas.ShapeWarning)
+    if warned:
+        parts.append("")
+        parts.extend(f"  [yellow]-[/] {escape(one.message)}" for one in warned)
+    return Group(*parts)
+
+
+def _width(row: schemas.StepShape) -> str:
+    """Say how wide a step is, and where one bad item leaves the rest of the batch running."""
+    drawn = escape(str(row.cardinality))
+    return f"{drawn}  {muted('continue')}" if row.items == "continue" else drawn
+
+
+def _deadline(row: schemas.StepShape) -> str:
+    """Say how long a step may wait, and what an expired deadline makes of it."""
+    drawn = _wait(row.deadline, from_block="deadline" in row.from_block)
+    return f"{drawn}  {muted('then skip')}" if row.deadline is not None and row.on_timeout == "skip" else drawn
+
+
+def _wait(value: timedelta | None, *, from_block: bool = False) -> str:
+    """Render one configured wait, saying where the block's own default filled it in."""
+    if value is None:
+        return "-"
+    drawn = format_duration(value)
+    return f"{drawn}  {muted('block')}" if from_block else drawn
+
+
+def _duration(record: Record, field: str) -> timedelta | None:
+    """Read one of the record's own durations back as the timedelta it was written from."""
+    raw = record.get(field)
+    return None if raw is None else to_timedelta(raw)
+
+
+def _attempts(record: Record) -> str:
+    """Say how many attempts the document allows, and where that number is only a floor."""
+    total = record.get("attempts_max")
+    return f"at least {total}" if record.get("attempts_at_least") else f"at most {total}"
+
+
 def _backfill(record: Record) -> RenderableType | None:
     """Render a backfill: the windows it enumerated, and the run each one became."""
     windows: list[schemas.BackfillWindow] = _rows(record, "windows", schemas.BackfillWindow)
@@ -442,6 +517,7 @@ RENDERERS: Final[Mapping[str, Callable[[Record], RenderableType | None]]] = {
     "config": _config,
     "db.history": _db_history,
     "validation": _validation,
+    "validation.shape": _shape,
     "error": _refusal,
     "token.issued": _issued,
     "process": _issued,

{dirigent_cli-0.18.0 → dirigent_cli-0.18.2}/src/dirigent_cli/triggers.py

@@ -5,7 +5,7 @@ from typing import Annotated, Any, cast
 
 import typer
 
-from dirigent_cli.commands import paged, parse_log_levels, parse_params, parse_priority
+from dirigent_cli.commands import paged, parse_importance, parse_log_levels, parse_params, parse_priority
 from dirigent_cli.context import Session, client_for, state_of
 from dirigent_cli.messages import (
     AT_TAKES_AN_INSTANT,
@@ -15,6 +15,7 @@ from dirigent_cli.messages import (
     ONE_CLOCK,
 )
 from dirigent_cli.output import (
+    alert_event,
     console,
     emit_fact,
     emit_one,
@@ -24,8 +25,10 @@ from dirigent_cli.output import (
     render_bool,
     styled,
     table,
+    throttle_note,
+    watching,
 )
-from dirigent_client import AlertEvent, AlertScope, WebhookTokenOut
+from dirigent_client import LOG_NOTIFIER, AlertEvent, AlertScope, WebhookTokenOut
 from dirigent_common import Message
 
 schedule_app = typer.Typer(
@@ -416,15 +419,15 @@ def alerts_rules_list(
         return emit_records("alert_rule", rows)
     table(
         "alert rules",
-        ["code", "name", "event", "scope", "notifier", "throttle", "active", "last sent"],
+        ["code", "name", "event", "scope", "target", "throttle", "active", "last sent"],
         [
             [
                 row.code,
                 row.name or "-",
-                row.event.value,
-                row.pipeline or row.scope.value,
-                row.notifier,
-                row.throttle,
+                alert_event(row.event.value),
+                watching(row.pipeline or row.scope.value, row.importance),
+                row.connection or LOG_NOTIFIER,
+                throttle_note(row.throttle),
                 render_bool(row.active),
                 moment(row.last_sent_at),
             ]
@@ -444,11 +447,13 @@ def alerts_rules_create(
             help="The event that fires it: run_failed, run_completed_with_errors, run_succeeded, or run_stuck.",
         ),
     ],
-    notifier: Annotated[str, typer.Option("--notifier", help="The channel to deliver through, such as log.")],
     name: Annotated[str | None, typer.Option("--name", help="A human title for this rule.")] = None,
     description: Annotated[str | None, typer.Option("--description", help="What this rule is for.")] = None,
     pipeline: Annotated[str | None, typer.Option("--pipeline", help="Watch one pipeline instead of all.")] = None,
-    connection: Annotated[str | None, typer.Option("--connection", help="The credential the channel uses.")] = None,
+    connection: Annotated[
+        str | None,
+        typer.Option("--connection", help="The connection to deliver through; none delivers to the process log."),
+    ] = None,
     template: Annotated[
         str | None, typer.Option("--template", help="Subject, a Jinja template over the run's facts.")
     ] = None,
@@ -457,14 +462,22 @@ def alerts_rules_create(
         Path | None, typer.Option("--body-file", help="Read the body template from a file instead.")
     ] = None,
     throttle: Annotated[str, typer.Option("--throttle", help="At most one message per window, e.g. 15m.")] = "0s",
+    importance: Annotated[
+        str | None,
+        typer.Option(
+            "--importance",
+            help="Only pipelines carrying at least this much: routine, normal, or critical.",
+        ),
+    ] = None,
 ) -> None:
-    """Declare an alert rule binding an event at a scope to a channel."""
+    """Declare an alert rule binding an event at a scope to one target."""
     if event not in set(AlertEvent):
         _fail(NOT_AN_ALERT_EVENT, event=repr(event), allowed=", ".join(sorted(AlertEvent)))
     if body is not None and body_file is not None:
         _fail(ONE_BODY)
     if body_file is not None:
         body = body_file.read_text()
+    floor = parse_importance(importance)
     with client_for(state_of(ctx)) as dg:
         created = dg.call(
             dg.alerts.create_rule(
@@ -472,9 +485,9 @@ def alerts_rules_create(
                 name=name,
                 description=description,
                 event=AlertEvent(event),
-                notifier=notifier,
                 scope=AlertScope.PIPELINE if pipeline else AlertScope.GLOBAL,
                 pipeline=pipeline,
+                importance=floor,
                 connection=connection,
                 template=template,
                 body=body,
@@ -488,6 +501,7 @@ def alerts_rules_create(
         name=created.name,
         event=created.event.value,
         scope=created.pipeline or created.scope.value,
+        importance=created.importance.value if created.importance else None,
         notifier=created.notifier,
         connection=created.connection,
         template=created.template is not None,
@@ -532,16 +546,15 @@ def _set_rule_paused(ctx: typer.Context, code: str, *, paused: bool) -> None:
 @alerts_app.command("test")
 def alerts_test(
     ctx: typer.Context,
-    notifier: Annotated[str, typer.Argument(help="The channel to send through, such as log or webhook.")],
     connection: Annotated[
         str | None,
-        typer.Option("--connection", help="The credential record the channel delivers through."),
+        typer.Option("--connection", help="The connection to deliver through; none delivers to the process log."),
     ] = None,
     subject: Annotated[str, typer.Option("--subject", help="What the test message says.")] = "dirigent test alert",
 ) -> None:
-    """Send a test message through a channel, on the same queue a real alert takes."""
+    """Send a test message to one target, on the same queue a real alert takes."""
     with client_for(state_of(ctx)) as dg:
-        queued = dg.call(dg.alerts.test(notifier=notifier, connection=connection, subject=subject))
+        queued = dg.call(dg.alerts.test(connection=connection, subject=subject))
     emit_fact(
         "notification.queued",
         message="queued",