Build pipeline

A build turns an approved snapshot into a verified artifact. It runs four layers, each reporting independently.

Queueing

Builds are queued, not run on demand. Each build is a row in a queue table with a state, a priority, an attempt count, and a lease.

Workers claim jobs optimistically: a worker updates the job from queued to building only if it is still queued at that instant, and it succeeds only if it changed exactly one row. If two workers reach the same job, exactly one wins. No distributed lock service is involved, because there is no budget for one and a database row is sufficient.

Each worker holds a lease on the job it is running and refreshes it periodically. If a worker dies, its lease expires and a reaper returns the job to the queue with an incremented attempt count. Builds that exceed the maximum attempt count are marked failed with the last error attached.

The four layers

1. Lint

Structural validity of the specification: the feature files parse, the Gherkin rules hold, the OpenAPI document is valid against the specification, and the project’s own conventions are respected — naming, tag usage, Background discipline, the style guide.

This layer fails on things a human would call "that is not how we write things here". It is cheap, it runs first, and it prevents the later layers from reporting confusing errors.

2. Type check

The generated implementation’s types are checked for internal consistency. Type errors surface here rather than as a runtime failure in a trial environment three stages later.

This layer catches a real category of defect — mismatched shapes between producer and consumer — but it says nothing about whether the types are the right ones. A program can be perfectly type-consistent and still implement the wrong requirement.

3. Cross-format consistency

The Gherkin and OpenAPI halves are checked against each other: referenced operations exist, declared status codes are the ones the scenarios expect, example values satisfy their schemas, tags resolve.

This is the layer that catches mismatches no single-format tool can see. It is described in detail in cross-format consistency.

4. Scenario execution

The specified behaviours are executed against the built artifact, in a throwaway environment with seeded data. Every scenario produces a pass, fail, or skip, with the evidence attached — the request, the response, the database state after.

Every scenario also receives its assertion strength grade, which is reported alongside the result. A scenario that passes and is graded weak is reported as "passed, but the assertion is too weak to be informative" — not as a green check.

Layer ordering

The layers run in order and stop at the first failure, with one exception: the consistency layer always runs to completion, because its failures are cheap to collect and are much more useful in full than one at a time.

When a layer fails, the build stops. A scenario that fails is not allowed to proceed into the trial environment — deploying something that is known not to meet its own specification would waste the most expensive resource in the system and teach the user something false.

Failure attribution

Failures are attributed to the clause that caused them, not just to the file.

A failing scenario names its clause. A type error names the operation and the clause whose contract it violates. A consistency failure names the clause and the document section involved. This attribution is what turns a red build into a review action: you reject the named clause, it regenerates, and the build re-runs.

A failure that cannot be attributed to any clause is reported as a build defect rather than a specification defect. It is escalated separately, and it counts against the platform’s own reliability metric, not against the specification’s.

Reproducibility

Every build records the model version, every tool invocation with its inputs, and the hash of the snapshot. Rebuilding the same snapshot produces the same result, or a documented difference.

Where a provider changes behaviour underneath us — a model version is retired, a tool’s output changes — the difference is recorded rather than hidden. We do not silently re-draft a specification to keep a build green.

Logs and artifacts

Build logs are files, not database rows. They are large, they are written at high frequency, and their value density is low — they are worth keeping for a window and then deleting, which is exactly the wrong shape for a relational table.

They are retrieved by byte offset, so a client that loses its connection resumes where it left off rather than re-downloading. The client can also fetch directly from object storage with a signed URL, bypassing the control plane entirely — which matters when the control plane is in one region and the build is in another.

Metadata about the log — its key, total size, and expiry — is stored in the database. The log itself is not.

Next