> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> Validate required or exact model output schemas.

A model's declared columns describe expected output metadata. The `contract` policy determines whether SQLBuild treats that declaration as an open shape or a complete exact shape.

| Value      | Behavior                                                                                                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `none`     | Statically check declared columns when SQLBuild can infer the output; allow undeclared output columns. This is the default.             |
| `enforced` | Treat declared columns as the complete authoritative output shape and enable runtime exact-schema checks on supported materializations. |

```sql theme={null}
MODEL (
  materialized table,
  contract enforced,
  columns (
    order_id (type INTEGER, nullable false),
    customer_id (type INTEGER, nullable false),
    amount_cents (type INTEGER),
    status (type VARCHAR),
  ),
);
```

## Validation

### Compile time

When SQL analysis can infer the model's output, both contract policies check declared columns against that inference:

* A missing declared column fails.
* A proven type mismatch fails when type enforcement or an exact contract is active.
* A declared non-null column fails when its expression is proven nullable.
* Additional inferred columns fail only for `contract enforced`.

If SQLBuild cannot infer the output shape, these static shape checks cannot run. `contract none` does not add a later runtime requirement. An enforced contract additionally requires a non-empty column declaration.

Configuration fields that reference output columns, including `unique_key`, `cursor`, `updated_at`, and `check_columns`, are checked against an enforced declaration.

### Runtime

For supported materialization paths, `contract enforced` inspects the staged relation and rejects:

* Missing declared columns.
* Additional undeclared columns.
* Warehouse types that differ from declared types.

Runtime contract validation does not scan data for nulls and does not inspect warehouse nullability metadata. `nullable false` participates in static nullability analysis; add a `not_null` audit when null values must be checked at runtime.

Runtime exact-schema validation currently runs for:

* Staged full-table builds.
* Non-microbatch incremental deltas.
* Snapshot deltas.

Views and custom materializations rely on compile-time contract analysis. Microbatch incrementals currently apply type enforcement and audits but do not perform the framework runtime exact-schema validation step.

Staged table validation happens before promotion, so a failure leaves the existing destination untouched. Direct table promotion is incompatible with `contract enforced` because SQLBuild cannot validate output before replacing the destination.

## Type enforcement

Declaring a model column type enables type enforcement automatically, independently of the contract policy. Type enforcement controls static type compatibility and runtime casts on supported table and incremental paths; contracts control output shape. See [Type Enforcement](/concepts/models/type-enforcement) for the materialization matrix.

## Reusable schemas

Contracts apply to the effective declaration, not only the reusable base:

```sql theme={null}
MODEL (
  model_schema order,
  columns (
    ingestion_batch_id (type VARCHAR, nullable false),
  ),
  contract enforced,
);
```

With `contract enforced`, this requires exactly the resolved `order` columns plus `ingestion_batch_id`. With `contract none`, SQLBuild checks those columns when static inference is available and permits further output. See [Schemas](/concepts/models/schemas).

## Enum columns

A column may use a declared enum as a portable logical domain type:

```sql theme={null}
MODEL (
  contract enforced,
  columns (
    market_type (type market_type),
  ),
);
```

This does not require, create, or reference a warehouse-native enum type. SQLBuild resolves string-valued enums to `VARCHAR` and integer-valued enums to `INTEGER`. Under `contract enforced`, it also generates an `accepted_values` audit for the declared members. Audit severity and timing follow normal audit configuration and materialization behavior. With the default error severity, it gates staged-table promotion and pre-DML delta paths; views and custom materializations may already have changed their relation when the audit runs.

Enum member references such as `@enum("market_type").WIN` are a separate feature that render one validated SQL literal. See [Enums and Constants](/concepts/enums-and-constants#enum-typed-contracts) for the complete distinction and lowering behavior.

## Related policies

The core default is `contract none`. A repository can enable [`SQBKR401`](/concepts/kata#layers-and-model-grammar) to require enforced contracts through Kata architecture policy.

Contracts also constrain schema-change behavior. For example, `snapshot_schema_change append_new_columns` is incompatible with `contract enforced` because an unannounced appended column would violate the exact declaration.