Skip to content

No executable conformance contract for warehouse adapters #317

Description

@marcociav-exmergo

The storage seam and the project-format seam each ship an executable conformance
suite: an outside implementer subclasses a contract, runs it, and a green suite
means the implementation is correct. The warehouse adapter seam, which has the
most implementations by a wide margin, has none. What it has instead is a
per-connector test file that each new connector copies and adapts, plus a block
in the safety suite.

That worked at three connectors and is showing its age at seven. Concretely: the
shared expectations are real but unwritten, so they are discovered by reading
another adapter and are easy to miss. Recent examples, each found by hand rather
than by a contract: profile_estimate must accept an include_blobs keyword
because a caller always passes it; a batched probe must degrade to an empty
result rather than self-escalate past its ceiling; table_metadata must supply
an exact row count where list_objects may supply an estimate; every billed
statement must carry a server-side cap derived from the remaining budget.

A contract in the shipped style would let a new connector, in-tree or out, assert
those in one subclass. It would also make the read-only and cost-gate families
enforceable at the seam rather than restated per connector.

Two things to settle before writing it, and they are the interesting part:

  • Which members are mandatory. A large slice of the adapter surface is
    probed with getattr and degrades gracefully when absent, which is deliberate
    and should stay. The contract has to distinguish "required" from "optional but
    must behave this way if present", or it will force implementations of things
    that were designed to be skippable.
  • How to exercise it without a live warehouse. The storage contract runs
    against in-memory implementations. An adapter contract needs the implementer
    to supply a fake, which is a real cost to impose, so the contract should be
    worth more than the fake costs.

Marking help wanted rather than good first issue: the design question above
is the work, and getting it wrong produces a contract people route around.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions