Appendix B — Models-bridge patterns

Appendix B - 12. Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost)

The Structure of Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost) — its shape at a glance:

Every edge declares one of three intents. Only correctness and cost-gate edges live in the graph, which is host-identical; load edges migrate to a typed Scheduler that reads a per-host profile and emits the execution plan.

flowchart LR
  Edge[Edge intent] --> Corr[CORRECTNESS<br/>in graph]
  Edge --> Cost[COST_GATE<br/>in graph]
  Edge --> Load[LOAD<br/>banned in graph]
  Load --> Sched[Scheduler]
  Prof[(Per-host profile)] --> Sched
  Sched --> Plan([Execution plan])

Accessible description: an edge declares one of three intents. Correctness and cost-gate edges stay in the host-identical graph; load edges are banned from it and move to a Scheduler, which reads a per-host profile and produces the execution plan.

Projected from the catalogue entry system-models / Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Keep a build/deploy dependency graph a statement of correctness only, host-identical everywhere, and push every environment-specific execution concern — how much may run at once, and whether a costly step is worth running — into a typed Scheduler that reads a per-host profile and produces the execution plan. Separate three edge intents so a reader can tell a real dependency from a resource or budget accommodation (our instance: a deploy DAG whose edges carry a CORRECTNESS/COST_GATE/LOAD intent, with LOAD edges migrated out to a typed Scheduler that reads a per-host (concurrency-ceiling, budget) profile).

Motivation

A build or deploy pipeline is a dependency graph: B needs A means B runs after A. The graph is supposed to state correctness — B produces a wrong or failed result without A. In practice two other concerns leak into the same needs= syntax, and once they do the graph stops meaning one thing:

The graph now lies to its reader: three unrelated intents wear one syntax, and telling them apart takes per-edge archaeology. The usual patch makes it worse — a per-environment conditional in graph construction (if host == "prod": drop this edge) that strips the rationing edges back out where the box is elastic. The graph mutates per host, the strip rule lives in control flow rather than the types, and two failure modes go uncaught: a rationing edge added without the guard silently ships to an elastic host, and a correctness edge caught by an over-broad strip silently disables a gate. One incident is the shape in miniature — a single-worker queue-drain wait modeled as a needs edge took a multi-paragraph root-cause analysis to prove it was "stale convenience, not a true dependency" before it could be removed. The graph did not encode why the edge existed, so every host difference became a prose-guarded special case.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

Each edge carries a typed intent. A lint bans load edges from the graph, and a Scheduler maps a per-host (ceiling, budget) profile to a plan — so raising a host's concurrency is a one-row profile edit, never a graph edit.

from dataclasses import dataclass
import sys

DAG_RESIDENT = {"CORRECTNESS", "COST_GATE"}   # the single source the load lint reads

@dataclass(frozen=True)
class Edge:
    frm: str
    to: str
    intent: str        # CORRECTNESS | COST_GATE | LOAD

def load_lint(edges: list[Edge]) -> list[str]:
    """A LOAD edge in the graph is a finding — load rationing belongs to the Scheduler."""
    return [f"{e.frm}->{e.to}: intent {e.intent} not allowed in graph"
            for e in edges if e.intent not in DAG_RESIDENT]

def plan_for(concurrency_ceiling: int, budget: float) -> dict:
    """Pure map from a host profile to an execution plan (permits + cost-gate honoring)."""
    return {"permits": concurrency_ceiling, "run_cost_gated": budget > 0.0}

if __name__ == "__main__":
    edges = load_graph()                  # reads the built dependency graph's typed edges
    findings = load_lint(edges)
    for f in findings:
        print(f"LOAD-IN-GRAPH: {f}")
    # A new host is a new profile row, e.g. plan_for(concurrency_ceiling=1, budget=0.0)
    sys.exit(1 if findings else 0)

Consequences

Example use within DocAble

Contents
⇐ Beginning of this partNext part ⇒Next chapter ›⇤ BeginningEnd ⇥Index
© James C. Davis, 2026–present