Appendix B — Models-bridge patterns

Appendix B - 13. Journey-criticality → test-tier placement (which host a test runs on, derived)

The Structure of Journey-criticality → test-tier placement (which host a test runs on, derived) — its shape at a glance:

Each journey-part's criticality derives its host tier by a total function, stored nowhere by hand. A coverage-floor lint walks the model and fails when a major part has no test in a local home.

flowchart TD
  Part[Journey-part<br/>criticality] --> Derive{major?}
  Derive -->|yes| Local[local + staging]
  Derive -->|no| Staging[staging only]
  Local --> Floor{{Coverage-floor lint}}
  Floor -->|major part, no local test| Fail([finding])

Accessible description: a journey-part's criticality routes through a derivation — a major part to local plus staging, a minor part to staging only. A coverage-floor lint checks that every major part has a local test and reports one that does not.

Projected from the catalogue entry system-models / Journey-criticality → test-tier placement (which host a test runs on, derived).

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

Intent

Intent — Make a journey's criticality the single input that derives which environment tier its tests run in, and hold a coverage floor over the derivation: every high-criticality journey-part carries a test in the fast local tier, so a green local run means the major paths work. Placement is derived from a typed trait, never hand-drawn (our instance: a typed journey-criticality model whose MAJOR/MINOR axis derives each journey-part's local vs staging tier, guarded by a coverage-floor lint).

Motivation

A test suite runs across environments of different cost. A fast local tier gates every commit; a heavier staging tier runs the full matrix. Which test runs where is usually a hand-drawn line — "keep the important journeys local, push the heavy remainder to staging" — and a hand-drawn line drifts from what actually matters. So a major user path ends up staging-only: the local gate passes, a reviewer merges, and the broken revenue-core flow surfaces only later on staging. Call it the local-green / staging-red surprise. It has two causes, and both come from the line being drawn by hand:

The failure is a fast gate that is trusted to mean more than it covers: local passes, the majors look green, and one of them is broken.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

The tier is a pure function of criticality — a stored tier literal is banned, so demoting a part to staging-only forces a visible criticality edit. The coverage-floor lint fails when a major part has no local test, making "local-green ⟹ every major path ran locally" a checked property.

import sys

def derive_tier(criticality: str) -> str:
    """Total function: criticality alone decides the host tier. No hand-typed tier literal."""
    return "local-depth" if criticality == "major" else "staging-full"

def coverage_floor(parts: list[dict], local_tests: set[str]) -> list[str]:
    """Every major journey-part must have a test in a sanctioned local home."""
    findings = []
    for p in parts:
        if p["criticality"] == "major" and p["join_key"] not in local_tests:
            findings.append(f"major part '{p['name']}' has no local test")
    return findings

if __name__ == "__main__":
    # `load_parts` reads journey-parts + criticality; `local_test_keys` lists tests in local homes.
    findings = coverage_floor(load_parts(), local_test_keys())
    for f in findings:
        print(f"UNCOVERED-MAJOR: {f}")
    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