The preceding models already expressed obligations: a user interface must reach its database through the service layer, and a job must pass through Running before Succeeded. A decision model makes explicit how to choose among alternatives: whether a result is acceptable, whether the evidence is sufficient, what to do after failure, or which strategy to try next. Its answer may be to accept, retry, repair, escalate, or stop.
A behavioral model describes possible states and transitions. A decision model states how to choose among them using the available evidence, the cost of further work, and the attempts remaining. For example, a repair process may allow another attempt, escalation, or termination. A decision table can state when the observed failure justifies another attempt, when more evidence is needed, and when the remaining budget requires stopping. The model supplies criteria for the choice; a separate mechanism carries it out.
2.4.1 The Canonical Move: Choosing Among Alternatives
Decision tables map conditions to choices; rule systems state how evidence affects a decision; constraint systems distinguish admissible alternatives. A policy is one kind of decision model: it specifies which alternatives an engineer permits, requires, or forbids. Access-control matrices record which subject may act on which object, 11. Butler W. Lampson, “Protection,”ACM SIGOPS Operating Systems Review 8, no. 1 (1974): 18–24, https://doi.org/10.1145/775265.775268. policy graphs declare permitted relationships, and feature models constrain valid combinations of options.
The meaning of an edge depends on the model’s purpose. In an observed call graph, A → B records that A calls B; in a policy graph, the same arrow means that A may call B. An absent observed edge means only that no such call was recorded within the observation’s coverage. An absent policy edge can mean that the call is prohibited, provided the policy declares a complete set of permitted relationships within its scope. These are different claims, even though both models use the same graphical notation. Comparing them lets engineers ask whether the implementation respects the declared permissions.
Once permission is declared, the claims a policy designer wants become expressible: which alternatives are permitted or forbidden, which are mutually exclusive, which imply prerequisites, whether the policy is internally consistent, whether it is complete over the cases that can arise, and whether it achieves least privilege. The analyses follow — evaluating a rule against a case, checking or solving constraints, detecting conflicts between rules, testing completeness and consistency. A declared policy turns "is this allowed?" into an evaluation rather than an argument.
2.4.2 Compare the Decision with the Facts
In a hypothetical system, a public web interface may call a report service, which may in turn call a renderer. The declared policy permits those relationships but prohibits the web interface from calling the renderer directly. Figure 2.4-1 compares that policy with an observed call graph. The observation contains a direct web-to-renderer call that the policy does not permit. Comparing the graphs therefore identifies a violation of the declared architectural boundary.
Figure 2.4-1.Observation compared with declared permission. The observed web-to-renderer call violates the declared policy.
The comparison asks whether observations conform to the declared policy, not whether the policy itself is correct. A policy could permit an undesirable relationship, and an implementation could faithfully follow it. Conversely, the absence of an observed call does not establish that the call can never occur; the observation may have incomplete coverage. Engineers must therefore evaluate both whether the policy expresses the intended architecture and whether the available evidence establishes conformance to it.
2.4.3 Preserve the Cases a Decision Must Distinguish
The input representation can make a decision wrong before any rule is evaluated. Return to the prepaid and unlimited subscriptions introduced earlier. For a simple policy with one applicable entitlement, Table 2.4-1 states when to admit a request and whether to charge finite credit.
Table 2.4-1.Admission under one entitlement. Unlimited entitlement admits covered work without drawing down finite credit; a finite balance must cover the requested work.
Entitlement
Requested work
Decision
Unlimited
Any amount covered by the subscription
Admit without drawing down finite credit
Finite balance
Enough credit for the request
Admit and charge the required credit
Finite balance
Insufficient credit for the request
Reject for insufficient credit
The table needs the entitlement kind as well as the balance. If a previous step passes only a number, zero cannot distinguish an exhausted finite allowance from unlimited use. The decision code cannot recover a distinction that its input has discarded.
When the Decision Depends on Context
Some decisions cannot be made from the object alone. Accessibility standards distinguish informative images, which need a text alternative, from decorative images, which assistive technology can ignore 2.2. World Wide Web Consortium, Web Content Accessibility Guidelines (WCAG) 2.1, 2018, https://www.w3.org/TR/2018/REC-WCAG21-20180605/. A blue square might decorate a restaurant menu but be the subject of a lecture on modern art.** For a real example, consider Yves Klein’s Blue Monochrome (1961), in the Museum of Modern Art’s collection 3.3. Museum of Modern Art, Yves Klein. Blue Monochrome. 1961, n.d., https://www.moma.org/collection/works/80103. What matters is the image’s contribution to the document, not merely what it depicts.
DocAble’s slide classifier gives a vision-language model (VLM) a rendered slide so it can judge each image or shape in context. The VLM returns a classification: clearly decorative, uncertain, or informational. That judgment supplies evidence; the decision policy determines what to do with it. For content-bearing images, only a clearly decorative verdict permits suppressing the description. An uncertain or missing verdict preserves the image’s informational role. The asymmetry is deliberate: an unnecessary description is audible, while wrongly hiding information can leave a screen-reader user unaware that anything was omitted.
An evaluation found that earlier classifiers had marked content-bearing images as decorative, particularly in visualization-heavy documents. We tightened the policy by representing uncertainty explicitly and making its conservative interpretation common to the classification paths. The decision model now states how uncertain evidence affects remediation without prescribing which VLM must supply that evidence. A different VLM can make the semantic judgment; it does not redefine the policy for acting on it.
DocAble supplies two worked applications of permission: a declared service-call policy and an upload-admission failure that required a richer decision model.
WORKED EXAMPLEDEEP DIVE
Worked example — Permission at two system boundaries
DocAble accepts documents for accessibility remediation, sends work among internal services, and returns corrected artifacts. Two decisions arise at different boundaries: which service may call another, and whether a user's entitlement permits a requested upload. Both can be modeled as permission, but they need different representations.
Which services may communicate?
DocAble distributes document remediation across several services. The public web tier receives requests, while internal services perform document editing, generation, rendering, OCR, and other work. Rather than specifying the permitted connections independently in deployment configuration, DocAble records them in a service-flow model. Each directed edge declares that one service may invoke another; an absent edge excludes that relationship from the declared policy.
Service-flow model · Decision
Engineering question — Which service may call which, and what may be reached from outside?
Model — a declared graph of services and the permitted edges between them; the deployment is wired from the graph rather than the graph inferred from the deployment.
Property — internal communication is permitted only along a declared edge; one declared node is the public entry.
Quality attribute — least privilege; architectural integrity; security.
Figure 2.4-2 shows a reduced view of the service-invocation policy. The web tier is the only publicly reachable service. Its declared outgoing edges permit calls to selected internal services. Separately, the worker may invoke generation, rendering, and OCR services. The arrows express permissions, not observed traffic or a requirement that every permitted call occur. Asynchronous job dispatch is omitted from this selected view; absence here does not imply prohibition by the full policy.
The service-flow model is the source of truth for these relationships. DocAble generates deployment configuration from the declared edges, and a completeness check requires each gated edge to contain the information needed for deployment. This prevents omissions in the declaration from silently producing incomplete configuration. It does not establish that runtime traffic follows the intended topology: the model defines the policy, while enforcing it against actual calls requires separate mechanisms.
Figure 2.4-2.DocAble’s service-flow model. Arrows show selected permitted service invocations; asynchronous job dispatch is omitted. The web tier is the sole public entry point. Deployment configuration is generated from the full model, while runtime conformance requires separate enforcement.
The declared graph can also serve as the policy against which observed service calls are checked. DocAble does not currently reconcile runtime traffic against that declaration. Whether to add such a check, and what consequences a violation should have, are Alignment decisions taken up in Chapter 3.
Which entitlement authorizes an upload?
The service-flow policy states an architectural decision. A different decision, whether a user may upload a document, exposed the cost of losing a domain distinction as the product changed.
DocAble admits an upload only when the user is entitled to it. A user receives that entitlement through groups. A group may carry a finite credit balance, drawn down as pages are processed, or it may provide unlimited use. The admission decision therefore depends on two different facts: how many finite credits are available, and whether any applicable entitlement is unlimited (Figure 2.4-3).
Figure 2.4-3.The upload-entitlement domain. A finite balance alone cannot determine admission: the model must also preserve whether any applicable group grants unlimited use.
The original client upload rule was easy to understand from the code: if the user’s credits covered the upload cost, allow the upload; otherwise, reject it. Box (1) in Figure 2.4-4 shows this balance-based check. A separate decision model would have added little to understanding that simple rule.
Unlimited groups changed what the upload decision had to account for. As box (2) shows, a group could authorize an upload without contributing finite credits to the balance. The server’s balance calculation, the client’s check before sending an upload, and the server admission gate represented entitlement in different ways. Understanding and updating the intended policy now required checking how each part of the implementation handled both finite and unlimited entitlement.
Box (3) traces the production failure. In August 2026, a user whose personal group provided unlimited use was blocked from uploading a thirty-eight-page presentation: the upload needs 38 credits, and you have 0. The legacy server function read each group’s unlimited flag twice: once to exclude unlimited groups from the credit sum, and once to compute a display class. For this user it returned zero credits and the class individual. The login response omitted the detailed group records but carried a separate unlimited-status flag. The client upload check ignored that flag, compared the zero balance with the required 38 credits, and rejected the upload before sending the file. The server’s admission logic, which handled this entitlement correctly, was never reached. The failure came from using the finite-credit total as an admission decision even though other system representations retained the unlimited entitlement.
The immediate fix made the client consult the existing unlimited-status flag it had been ignoring. We then introduced the entitlement decision model shown in box (4) to state the policy explicitly: given the user’s group entitlements and the requested work, should this upload be admitted, and under which entitlement? Property tests checked the model, and a cross-runtime parity corpus checked shared policy cases in the server and client. A further check validated the model’s shape. The display code derived its values from the model, and the server admission code delegated the policy decision to it.
Entitlement decision model · Decision
Engineering question — May this user upload this document, and under which entitlement?
Model — per-group entitlements that keep finite and unlimited as distinct cases; the output is a structured admission decision: admitted or not, the group that authorizes it, and the ordered plan by which the verdict was reached.
Property — an uncapped unlimited group can authorize an upload with zero finite credits; the display projection does not decide admission.
Quality attribute — decision correctness; fidelity between the domain and its representations.
Box (4) separates the admission decision from the display projection. For the same unlimited group, with no per-user cap, the model admits the 38-page upload and records the authorizing group and an admit_unlimited plan step. The group’s finite credit balance is still zero. The display projection, however, returns a special numeric value marking unlimited use; it returns a finite credit sum only when all of the user’s groups are finite. That display value is explicitly excluded from the admission decision. The two outputs answer different questions, and each preserves the information its consumer needs.
Figure 2.4-4.The admission check must preserve unlimited entitlement. Panels (1)–(4) explain the old representation, domain change, failure, and repair; they are not one runtime pipeline. In (3), the client uses the finite-credit total and ignores a separate unlimited signal. In (4), the same uncapped entitlement produces an admitting decision and a separate display value for unlimited use.
A note in the first person: I changed the domain in one place — groups could now be unlimited — and did not carry the change into every representation of the same decision. An explicit model would not have made the change automatically correct; it would have made the inconsistency visible as an engineering obligation. When the domain contains a consequential distinction, every representation used to reason about that decision must be capable of expressing it. Chapter 3 gives the recurring pattern here — a failure converted into explicit structure that later work inherits — a name.
The two models give a decision an explicit domain: permitted service pairs in the first case, distinct entitlement alternatives in the second. That makes the decision inspectable and checkable. It also exposes what must change when the intended policy or the product's domain changes.
Decision models make the criteria for a choice explicit, whether the choice concerns permission or what to do next. The final section steps back from one representation to ask how a family of models can answer questions together.