Proving Input Contracts on Pure Library Primitives

A function that parses a duration string passes four unit tests. It parses "10s", "2m", "1h", and "500ms". The suite is green. The build passes. The artifact is packaged and published to an internal package registry.

Two weeks later, a background worker ingests "0s", and the service divides by zero because the author assumed duration was strictly positive. Another service passes " -5s", and the regex matches the digit, discards the sign, and schedules a job five seconds in the future instead of failing.

The tests did not lie about what they ran. They just ran four happy paths that mirrored the mental model of the engineer who wrote the implementation. A green suite does not prove that a component is safe to reuse across a codebase. It proves only that the author’s imagination was consistent with their own code on the day they wrote it.

The Gap Between Assertion and Verification

Most unit test suites test implementation artifacts rather than domain boundaries. When the author writes both the code and the test, the test inevitably inherits every blind spot present in the logic.

## The implementation
def window_slice(items: list[T], size: int, step: int) -> list[list[T]]:
    return [items[i : i + size] for i in range(0, len(items), step)]

## The author's test
def test_window_slice():
    assert window_slice([1, 2, 3, 4, 5], size=2, step=2) == [[1, 2], [3, 4], [5]]

The test passes. But what happens when step=0? An unhandled ValueError: range() arg 3 must not be zero halts the process. What happens when size=-1? It silently returns empty inner lists. What happens when step > len(items)?

A pure library primitive cannot rely on downstream callers to be polite. If a primitive is intended for catalog graduation—where other engineers or automated pipelines will consume it without reading the source—it requires formal verification. You must establish an explicit contract:

1. Preconditions: The exact domain of valid inputs (e.g., size > 0, step > 0, items is not None).
2. Postconditions: The structural guarantees of the return value (e.g., len(result) == ceil(len(items) / step)).
3. Invariants: What remains true regardless of input shape (e.g., elements retain their relative order).

When tests only verify a fixed list of examples, they provide zero executable proof that these invariants hold under hostile or degenerative inputs.

Subjecting Primitives to an Independent Test Harness

To move from an author’s test suite to genuine code certification, the contract verification must be separated from the implementation. The code must be evaluated by a test harness designed to attack boundaries rather than confirm expectations.

For pure functions—components with no side effects and no external I/O—this means three specific boundary categories must be exercised:

1. The Degenerate Extents

Every data type has edges where control flow fractures. For integers, it is 0, 1, -1, MAX_INT, and MIN_INT. For sequences, it is empty sequences, singletons, sequences with duplicate references, and collections whose length matches or exceeds pointer bounds. An input contract must explicitly define whether these inputs are valid transformations or immediate, typed rejections.

2. Type-Adjacent Contaminants

In languages with dynamic or loose typing, primitives frequently fail on non-canonical structures: strings with leading null bytes, floating-point NaN values passed to numeric comparators, or nested structures with cyclic references. The harness must verify that rejecting invalid input is as deterministic as accepting valid input.

3. State Invariance Under Property Generation

Instead of hand-rolling three arrays to test a sorting or slicing primitive, an automated property harness generates thousands of pseudo-random permutations, tracking whether the stated invariants hold on every single run. If step > 0 is satisfied, does the function ever raise an unhandled runtime exception? If it does, the primitive fails certification immediately.

## Contract-driven harness property
@given(
    items=st.lists(st.integers()),
    size=st.integers(min_value=1, max_value=1000),
    step=st.integers(min_value=1, max_value=1000)
)
def test_window_slice_invariants(items, size, step):
    result = window_slice(items, size, step)
    
    # Invariant: Total elements processed matches coverage expectation
    flattened = [item for sublist in result for item in sublist]
    assert all(x in items for x in flattened)
    
    # Invariant: Sub-window sizes never exceed declared size
    assert all(len(w) <= size for w in result)

The Ladder of Confidence

A function that compiles is merely well-formed syntax. A function with passing unit tests is merely compliant with its author's assumptions.

Graduating a piece of software to a shared catalog requires a distinct posture. In our engineering doctrine, this boundary is explicit: code does not get marked as catalog-grade until its input contracts have been exercised against deterministic failure boundaries. As outlined in The Four Verdicts Between Green Tests and Correct Code, acknowledging what an automated suite has and has not proven prevents provisional code from masquerading as a hardened foundation.

What to Do on Monday

Pick one core utility module in your repository—the string formatter, the math helper, or the slice parser that everyone imports.

1. Delete the happy-path unit tests from your evaluation. Assume they tell you nothing new.
2. Write down the precondition contract in docstrings or type assertions: state every invariant regarding zero, negative values, empty buffers, and maximum sizes.
3. Run property-based boundary generation against that contract. Use Hypothesis (Python), fast-check (TypeScript), or testing/quick (Go).
4. Enforce hard failure: If the function accepts invalid inputs without raising a defined error, or if valid edge inputs trigger generic runtime crashes, revoke its status as a trusted utility until the contract is patched.