Adapters

Adapters are how ContractForge becomes native on each platform without putting platform code in the core.

The core answers: what does the contract mean?
The adapter answers: can this platform preserve that meaning, and how should it run?

Responsibility split

Layer	Owns	Does not own
Core	Contract vocabulary, semantic normalization, capability matching, abstract plans, evidence concepts.	Spark, Databricks SDK, boto3, Azure SDK, Fabric SDK, Snowflake clients or runtime execution.
Adapter	Platform capabilities, native rendering, optional execution, SDK integration, credential resolution and platform-specific evidence values.	Changing the contract meaning or silently downgrading semantics.

Planning statuses

Status	Adapter behavior
SUPPORTED	Render or execute normally.
SUPPORTED_WITH_WARNINGS	Render or execute with explicit warnings in the planning result and review artifact.
REVIEW_REQUIRED	Produce diagnostics and optional review artifacts, but do not pretend the mapping is fully equivalent.
UNSUPPORTED	Return blockers and do not generate runnable artifacts for the unsafe behavior.

Adapter examples

Adapter	Native implementation surface
Databricks	Delta, Unity Catalog, Auto Loader, Lakeflow, Databricks SQL, Asset Bundles, Jobs and Delta-backed evidence.
AWS	Glue Spark, Iceberg, Glue Catalog, Lake Formation, S3 artifact publication, Glue job definitions, Terraform/CloudFormation and Iceberg-backed evidence.
Fabric	Lakehouse notebooks, OneLake, Lakehouse tables, shortcuts, deployment pipelines, Fabric governance APIs and Delta-backed evidence.
Snowflake	SQL, warehouses, tasks, streams, masking policies, row access policies and audit tables. See Snowflake parity.
GCP	BigQuery, GCS load jobs, Workflows orchestration, Dataplex quality/lineage/aspects, Secret Manager and BigQuery evidence.

Databricks is the reference implementation. AWS, Snowflake, Fabric and GCP now have stable supported surfaces for their documented scopes, with real cross-adapter validation and explicit review boundaries. Future adapters must prove parity through capability declarations, tests and documentation.

For side-by-side adapter guidance, see Test contracts across adapters. It shows the same GeoJSON medallion contracts reused across Databricks, AWS, Snowflake, Fabric and GCP with minimal native binding differences kept explicit at the platform boundary.

What adapters must preserve

Adapters should preserve ContractForge semantics first and choose native implementation second.

Examples:

• upsert requires upsert/merge semantics.
• scd2 requires history semantics, effective dating and current-row behavior.
• row filters and column masks require native governance primitives or an explicit review-required mapping.
• quarantine must keep run success/failure separate from quality status.
• evidence must record runs, errors, quality, quarantine, schema changes, lineage, source metadata, governance actions and cost signals where available.

Packaging

Each adapter is published independently:

contractforge-core
contractforge-databricks
contractforge-aws
contractforge-fabric
contractforge-snowflake
contractforge-gcp

Dependency direction is one-way:

adapter -> contractforge-core
contractforge-core -> no adapter dependency

This lets teams install only the adapters they need and lets each adapter move at the pace of its platform runtime.

Runtime package delivery

All adapters are Python distributions, but runtime delivery is adapter-owned:

Adapter	Package install	Runtime delivery
Databricks	PyPI package or uploaded wheel.	PyPI install in job/cluster/notebook environments is the normal path; attached wheels are the offline/pinned fallback.
AWS	PyPI package for local or CI deployment tooling.	Glue jobs should use S3-hosted wheels for contractforge-core and contractforge-aws; public PyPI is only appropriate when the job has controlled outbound package access.
Snowflake	PyPI package for local or CI deployment tooling.	SQL artifacts run natively; hosted Snowpark procedures stage ZIP imports produced from the core and adapter libraries.
Fabric	PyPI package or attached wheel.	Fabric notebooks need the core and Fabric adapter available in the notebook runtime; wheel attachment is the offline/pinned fallback.
GCP	PyPI package for local, CI or runner-side tooling.	BigQuery and Workflows execute native artifacts; Python packages are required where adapter commands render, deploy or smoke-test those artifacts.

Deployment versioning

Contract deployment versioning is a shared control-plane contract. Core owns the ctrl_deployment_versions schema and deterministic hash rules; adapters own where the table lives and how it is created, updated and queried on each platform.

Each deploy command creates one unique deployment_id. Each deployed contract step or native artifact creates a ledger row with:

• deployment_step_id: deterministic id for the step inside the deployment;
• deployment_hash: stable hash of the deployment row, excluding mutable result metadata;
• contract_hash: stable hash of the contract payload used for that step;
• environment_hash: stable hash of the resolved environment payload;
• manifest_hash: stable hash of the adapter deployment manifest payload.

Adapter	Version ledger storage
Databricks	Delta table in the configured evidence catalog/schema.
AWS	Iceberg table registered in Glue Catalog.
Snowflake	SQL table in the configured evidence database/schema.
Fabric	Lakehouse Delta table in the configured evidence schema.
GCP	BigQuery table in the configured evidence dataset.

The ledger does not change ingestion semantics. It records exactly which contract payload, environment payload, platform artifact and runtime package versions were deployed so repeated deploys can be compared without relying on file names or platform timestamps.

AWS deployment shape

AWS does not parse YAML contracts inside Glue. The adapter interprets contracts before deployment:

contract bundle
  -> render artifacts
  -> publish to environment.artifacts.uri
  -> materialize Glue job definition
  -> create or update Glue job

Use:

contractforge-aws deploy contracts/orders.ingestion.yaml --environment environments/prod.aws.yaml

The environment owns S3 artifact location, Glue role, dependencies and Iceberg warehouse. The ingestion contract remains semantic.

AWS renders review artifacts alongside runtime artifacts:

• deployment manifests record artifact sizes and runtime flow;
• IAM policies derive source, warehouse, artifact, script and dependency boundaries from the contract and environment;
• performance profiles define benchmark cases for mappings such as hash_diff_upsert;
• failure-path projects validate ctrl_ingestion_errors and failed run evidence without editing generated Glue code.