Environment contract.

The environment contract keeps platform execution choices separate from ingestion, annotations, operations and access semantics.

Use it for values that describe where and how a contract is planned or executed, not what data means.

Example

adapter: databricks

evidence:
  catalog: main
  schema: ops
  required: true

artifacts:
  uri: s3://contractforge-artifacts/prod/orders/
  include_contract_bundle: true
  include_normalized_contract: true

runtime:
  type: serverless
  notebook_name: jobs/bronze/b_orders

extensions:
  databricks:
    warehouse_id: "{{ secret:databricks/sql_warehouse_id }}"
    bundle_target: dev

Fields

Field	Purpose
adapter	Platform adapter requested for planning or execution.
evidence	Neutral evidence location and requirement hints.
artifacts	Adapter artifact publication location and retention options. AWS uses this for rendered Glue scripts and manifests in S3.
runtime	Runtime/deployment hints that are not source, target or write semantics.
extensions.<adapter>	Adapter-owned settings that should not leak into the core contract.

What belongs here

• adapter name and target environment;
• evidence catalog/schema/table-prefix choices;
• artifact publication URI and generated artifact retention choices;
• runtime type such as serverless, classic cluster, warehouse, job or pipeline;
• deployment target or bundle target;
• adapter-specific execution options;
• review-required environment assumptions.

What does not belong here

• source table, path, query or authentication;
• target table identity;
• write mode;
• quality rules;
• schema policy;
• row filters or column masks;
• owner, SLA or runbook.

Those remain in ingestion, source connection, access or operations contracts.

Adapter behavior

The core can validate the environment contract shape and preserve it in the bundle. The adapter decides how to interpret runtime and its own extensions.<adapter> block.

If an environment requests an adapter that is not installed or a runtime that cannot preserve the contract semantics, planning should return UNSUPPORTED or REVIEW_REQUIRED with a clear diagnostic.

AWS artifact example

AWS Glue runs a generic ContractForge AWS runner from S3. The AWS adapter uses environment.artifacts.uri to publish the runtime contract, environment and native artifacts before registering the Glue job. Runtime knobs such as Glue version, worker type, worker count, timeout and retries have adapter defaults, so they only need to be declared when you want to override them:

adapter: aws
artifacts:
  uri: s3://contractforge-artifacts/prod/orders/
  include_contract_bundle: true
  include_normalized_contract: true
parameters:
  aws:
    iceberg:
      warehouse: s3://contractforge-warehouse/prod/
    glue_job:
      role_arn: arn:aws:iam::123456789012:role/ContractForgeGlueRole

This does not change source, target, write mode or quality semantics. It only describes where native AWS artifacts live and how Glue should be configured.