Skip to content
ContractSpec
Start here

Core guide · Guides · 3 min read

Generation and drift: what changes, what does not

Use derived artifacts deliberately and understand the current boundary of generation plans and apply.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Separate authored behavior from derived artifacts

Keep the contract and the business implementation distinct from files produced by tooling. Review the source that owns a change, then regenerate the affected output instead of patching a derived file as the permanent fix.

At the inspected snapshot, the plain generate command calls the artifact service to create documentation and supported materialized targets. This is narrower than generating and deploying an entire correct application.

1 / 4

0 points in your packet

Separate authored behavior from derived artifacts

Keep the contract and the business implementation distinct from files produced by tooling. Review the source that owns a change, then regenerate the affected output instead of patching a derived file as the permanent fix.

At the inspected snapshot, the plain generate command calls the artifact service to create documentation and supported materialized targets. This is narrower than generating and deploying an entire correct application.

Understand the current command boundary

The source exposes separate generation, planning and apply paths. Their names do not imply equal maturity: the plan currently contains no write actions, and non-dry-run apply is deliberately refused.

Source commandObserved implementationHow to use the result
contractspec generateGenerates docs and supported materialized artifactsReview the actual derived diff
contractspec generate planBuilds a dry-run artifact with an empty actions listInspect its diagnostics; do not interpret zero actions as complete semantic analysis
contractspec generate apply --dry-runReturns the current dry-run plan with zero writesPreview only
contractspec generate applyRefuses writes with exit code 3Do not present as a shipping write workflow

Read an artifact drift result correctly

The drift service generates expected artifacts in a temporary directory and compares them with the selected generated directory. It can identify missing, extra or changed files.

This answers whether the derived output matches the current source and generator. It does not prove that a handwritten handler implements every business rule or that a migration is safe for production data.

Use a small review loop

Change one contract, regenerate only the relevant derived surface through the supported workflow, inspect the diff and run the owning checks. If the diff is unexpectedly large, first verify the source version, configuration and generator version.

Keep a deterministic example with the docs so a future release can reproduce the result. Broader reviewed repair or apply workflows should be described with their actual status until the write path is implemented and qualified.

A change has an owner and a set of consequences.

A report export now needs a reason. Follow the change through authored meaning, derived output and a caller that still uses the old input.

Which part are you changing?

A CONCRETE SITUATION

The requirement becomes part of declared behavior.

A required reason is added to the operation input.

01 / Author

Change the declaration that owns the required input.

What changes

Callers must now supply the new field for that contract version.

What stays explicit

The handler still decides how the reason affects the business work.

Follow the consequence

Plan compatibility for existing consumers. A required input can be a behavioral break even if the handler’s main implementation is unchanged.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.