Crosscutting concepts

A rule on this page is not attached to one phase, one page or one layer — breaking it would be wrong wherever in the factory it happened, which is exactly why each one below is enforced in a single place rather than asked for again at every call site.

Configuration

One precedence holds wherever a setting is read: the environment always wins, and the Connections page only fills the gaps it leaves. envvars.py's registry and settings.py's precedence are described in Components; what belongs here is that the rule is enforced in exactly one function, settings.into_environment, not at each of however many places read a setting, and that tests/test_envvars.py and tests/test_settings.py::test_stored_values_fill_the_environments_gaps_and_never_overwrite_it hold the two halves of the promise — a name the registry does not know about, and a form that would quietly overwrite a unit file. The generated configuration reference is that registry rendered as tables, so it cannot say anything the code does not.

Failing closed

Three places refuse rather than guess, each one tested as a refusal rather than only as a success:

• Contradictory identity settings. create_app's _one_door (dpf/web/__init__.py) raises before the application serves a single request if DPF_IDENTITY names something it does not recognise, if DPF_GATE is set alongside a different DPF_IDENTITY, or if link or site+link is missing its key or its allow list — guessing which half was meant is how a door ends up open. tests/test_entra.py::test_an_unknown_mode_refuses_to_start, tests/test_entra.py::test_two_doors_refuse_to_start.
• The workflow file. domain/flow.py's load() reads and validates workflow.yaml (or DPF_WORKFLOW's target) once, at import — a step that depends on one defined later, a parallel step that blocks nothing, a phase out of order, all raise WorkflowError before the process can run at all, rather than rendering a subtly wrong one as if it were fine. tests/test_workflow_config.py::test_a_later_dependency_is_named_as_such, tests/test_workflow_config.py::test_every_problem_is_reported_at_once.
• Every door. gate.install, gate.install_link, gate.install_both and entra.install each abort a request with a 503 the moment they cannot tell a reader from a stranger, rather than falling through to whichever check is easiest to satisfy. See Identity and Security model for what each door actually checks. tests/test_gate.py::test_closed_and_unconfigured_refuses_rather_than_opens.

Cross-site writes

A before_request hook (_same_origin, dpf/web/__init__.py) refuses every POST, PUT, PATCH and DELETE whose Origin or Referer disagrees with the host being asked, using the one comparison the application keeps for this, urls.same_origin. A request with neither header — every curl call, the CLI — is let through, because neither is a browser that could have been tricked into sending one. See Security model for why no token is needed on top of it. tests/test_urls.py::test_an_absolute_url_counts_only_on_this_origin.

One transaction per request

g.conn opens on the way into a request and is committed or rolled back exactly once, on the way out (_open, _close, dpf/web/__init__.py) — never per write inside it. See The record for what that buys pipeline.promote, and how the CLI gets the same guarantee a different way.

Static assets

A stylesheet or script's URL carries a short hash of its own bytes (asset(), dpf/web/__init__.py), and only a URL whose ?v= matches the file's current hash is marked cacheable for a year (_cache_policy); the same file asked for without its current hash is no-cache, and every page — the documentation and the API included — is private, no-store. A browser that already holds the old file fetches the new one the moment the file changes, rather than running new markup against a script that was fixed several edits ago. tests/test_asset_fingerprint.py::test_the_fingerprint_moves_when_the_file_does.

What reaches the model

DPF_LLM_DATA (dpf/privacy.py) decides what the three agents may send to Anthropic, redacted once in the function that gathers grounding rather than at each call site — see Components for llm.py's run() and Agents for what each of the three actually sees. The one fact that belongs here: every call is written to llm_calls before it returns, successful or not, so a failed call is still part of the record. tests/test_privacy_mode.py::test_metadata_mode_sends_no_value_from_any_row, tests/test_privacy_mode.py::test_an_unknown_setting_does_not_quietly_open_the_door.

Time

Nearly every timestamp in the record is db.now() (dpf/db.py) — UTC, ISO 8601, to the second — so the audit log's order is a plain string sort, never a timezone's arithmetic; db.clock() is the one seam that moves it, used by the test suite and by the worked example alike. domain/ takes a date as an argument almost everywhere rather than asking the system for one — with one exception: conformance.py's freshness check reads date.today() directly, because "how stale is this" has no answer without the day it is actually asked. tests/test_db.py::test_a_shifted_clock_only_ever_runs_forwards.

Testing strategy

Nothing in the default run touches the network: pytest.ini deselects the one marker that calls a real model (addopts = -m "not llm"), a second marker skips itself without real Databricks credentials, and a 30-second timeout turns a test that reaches for either anyway into a loud failure instead of a hang. The session-scoped warehouse fixture (tests/conftest.py) is the one expensive thing the suite pays for, once.

What gets faked depends on what is being tested, not on one house style. tests/test_llm_request.py captures what a fake Anthropic client receives, to catch a stale request parameter without a live call. tests/test_trackers.py replaces requests.post with something that raises, and only for the two tests that check a failed push leaves no row behind — everything else there asserts the request body as data. tests/test_catalog.py does not mock urlopen at all, because that would only prove the same URL was written down twice, and instead tests the response parsing and the sync comparison as pure functions, so the whole flow still runs offline.

Documentation as code

The documentation is reviewed in the pull request that changes what it describes, and python -m dpf docs check enforces that rather than trusting it — see Components for how the checker and the generators work. See Versioning for how the application and its documentation share one number, and for the four mechanisms that hold the docs to the code.