Appendix C - 10. DDT pin-trailers (doc-derived characterization)

The Structure of DDT pin-trailers (doc-derived characterization) — its shape at a glance:

Each doc-derived test carries a provenance trailer citing its source. Editing a cited source obliges regenerating the trailer in the same commit; a presence lint blocks a missing trailer, a freshness lint warns on a stale one.

flowchart LR
  Src[/Cited source/] -->|derive| Test["Test + provenance trailer"]
  Src -.->|edit obliges regen| Regen[Trailer regenerator]
  Regen --> Test
  Test --> P{{Presence lint}}
  Test --> F{{Freshness lint}}

Accessible description: a test is derived from a cited source and carries a provenance trailer. Editing the source obliges regenerating the trailer in the same commit. A presence lint blocks a missing trailer; a freshness lint warns when the trailer is stale.

Projected from the catalogue entry regression-tests / DDT pin-trailers (doc-derived characterization).

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

Intent

Intent — Doc-derived tests that characterize current behaviour before structural churn, each carrying a provenance trailer (audited / source / pins) so it is regenerated when the source it cites is edited.

Motivation

Before a big refactor you want to pin current behaviour so the change is provably behaviour- preserving, and doc-derived tests can silently drift from the doc or source they were derived from. The failure is two-sided: unpinned behaviour lost in churn, or a doc-derived test that no longer matches its cited source. It recurs before every structural change and whenever a cited source is edited.

Applicability

• A characterization-test convention and a provenance-trailer schema.
• A regen tool run in the same commit as a cited-source edit.
• Presence + freshness lints to keep trailers real.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The trailer is structured metadata parsed from the test file: what it was derived from, and the points it pins. A presence check reads it and blocks a doc-derived test that lacks one; a freshness check compares the recorded source hash against the source on disk and warns when they diverge — the signal an ordinary test never carries.

import ast, hashlib, re

def read_trailer(source: str) -> dict | None:
    # trailer lives right after the module docstring: DDT-source / DDT-pins lines
    m = re.search(r"DDT-source:\s*(?P<src>\S+).*?DDT-hash:\s*(?P<hash>[0-9a-f]+)", source, re.S)
    return m.groupdict() if m else None

def check(test_path: str, test_source: str, read_source) -> list[str]:
    trailer = read_trailer(test_source)
    if ast.get_docstring(ast.parse(test_source)) and trailer is None:
        return [f"{test_path}: doc-derived test missing provenance trailer"]   # blocking
    if trailer:
        live = hashlib.sha1(read_source(trailer["src"]).encode()).hexdigest()[:len(trailer["hash"])]
        if live != trailer["hash"]:
            return [f"{test_path}: trailer stale — cited source changed, regenerate"]  # warning
    return []

Consequences

• Trailer maintenance. Editing a cited source obliges a regen, a real if small per-edit cost.
• Low defect yield by design. These are characterization pins; a near-zero find rate is the success condition, not a sign they aren't working.
• Freshness is informational only — the fresh lint never blocks, so a stale trailer can linger.

Example use within DocAble

• The doc-derived test files + the DDT-audited / DDT-source / DDT-pins trailer.
• The trailer regenerator; the trailer-present lint (BLOCKING) + the trailer-freshness lint (WARNING).

Related Patterns

• See also (sibling) — test-onion-tiers, property-tests: the other behaviour-pinning bodies.
• Counterpart — the freshness lint detects drift of the test from its cited source (keeps the provenance honest).