End-to-end examples

These examples show how ContractForge AI should be used in realistic consulting-style projects: generate or inspect project files, validate with Core and adapters, then review the HTML report before deployment.

Supabase JDBC medallion

Goal:

• shared JDBC connection;
• products and product movements;
• bronze, silver and gold layers;
• Databricks and AWS targets;
• minimal contract differences;
• adapter warnings visible.

Prompt:

Create a Supabase medallion ingestion project for Databricks and AWS.
Use one shared JDBC connection.
Products use hash_diff_upsert with product_id as merge key.
Product movements append by movement_uid.
Create silver current movement and exploded product tag tables.
Create gold brand inventory aggregation.
Run daily with cron 0 6 * * * in America/Sao_Paulo.
Do not generate raw secrets. Use secret placeholders.

Generate:

contractforge-ai generate \
  --prompt-file prompts/supabase-medallion.txt \
  --schemas schemas/products.json schemas/product_movements.json \
  --with-ai \
  --provider openai \
  --output-dir generated/supabase-jdbc-medallion

Validate:

contractforge-ai validate-project-structure generated/supabase-jdbc-medallion \
  --adapter databricks \
  --adapter aws \
  --format html > generated/supabase-jdbc-medallion/project_validation.html

Expected result:

• READY or READY_WITH_WARNINGS;
• Databricks planner evidence for each Databricks contract;
• AWS planner evidence for each AWS contract;
• AWS warnings visible when Spark SQL quality expressions or Iceberg hash-diff performance require review.

Representative project layout:

generated/supabase-jdbc-medallion/
  project.yaml
  environments/
    aws.environment.yaml
    databricks.environment.yaml
  connections/
    supabase.yaml
  contracts/
    databricks/
      bronze/bronze_supabase_products/bronze_supabase_products.ingestion.yaml
      bronze/bronze_supabase_movements/bronze_supabase_movements.ingestion.yaml
      silver/silver_supabase_product_tags/silver_supabase_product_tags.ingestion.yaml
      gold/gold_supabase_brand_inventory/gold_supabase_brand_inventory.ingestion.yaml
    aws/
      bronze/bronze_supabase_products/bronze_supabase_products.ingestion.yaml
      bronze/bronze_supabase_movements/bronze_supabase_movements.ingestion.yaml
      silver/silver_supabase_product_tags/silver_supabase_product_tags.ingestion.yaml
      gold/gold_supabase_brand_inventory/gold_supabase_brand_inventory.ingestion.yaml
  AI_REVIEW.html
  project_validation.html

When a platform-specific contract folder exists, the reviewer should inspect why. The target state is minimal drift: most source, target, mode, transform, quality and access fields should be the same, with differences isolated in environment files or guarded adapter extensions.

Example shared connection plus override:

# connections/supabase.yaml
source:
  type: connector
  connector: postgres
  system: supabase
  options:
    url: "{{ secret:supabase/jdbc_url }}"
auth:
  type: basic
  username: "{{ secret:supabase/user }}"
  password: "{{ secret:supabase/password }}"

# contracts/.../bronze_supabase_products.ingestion.yaml
source:
  type: connection
  connection_path: project://connections/supabase.yaml
  table: public.products
  read:
    partition_column: product_id
    num_partitions: 8

USGS REST/GeoJSON medallion

Goal:

• REST/HTTP file source;
• GeoJSON payload;
• bronze raw ingest;
• silver extraction and normalization;
• gold magnitude summaries;
• Databricks and AWS validation.

Prompt:

Create a USGS earthquake REST GeoJSON medallion project for Databricks and AWS.
Bronze reads https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson.
Silver extracts event_id, event_time, magnitude, place, longitude and latitude.
Gold creates daily summary and magnitude band aggregates.
Use portable connectors where possible.
Keep platform-specific differences in environment or adapter extensions only.

Generate:

contractforge-ai generate \
  --prompt-file prompts/usgs-geojson.txt \
  --schemas schemas/usgs-events.json \
  --with-ai \
  --provider openai \
  --output-dir generated/usgs-earthquake-rest-medallion

Validate:

contractforge-ai validate-project-structure generated/usgs-earthquake-rest-medallion \
  --adapter databricks \
  --adapter aws \
  --format html > generated/usgs-earthquake-rest-medallion/project_validation.html

Expected result:

• READY_WITH_WARNINGS is acceptable when AWS reports expression-portability warnings.
• The report should show that source intent, target intent, write modes, quality and medallion structure are mostly unchanged across adapters.

Example REST connection:

source:
  type: connector
  connector: rest_api
  system: usgs
  options:
    url: https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson
    method: GET
    format: geojson
limits:
  max_total_bytes: 104857600
  max_records: 100000

The bronze contract inherits the endpoint. Silver and gold usually read from logical downstream table refs, so the adapter can resolve the physical Databricks or AWS table name from the project environment.

Review checklist

Before deployment, review:

1. AI_REVIEW.html or PROJECT_REVIEW.html.
2. project_validation.html.
3. project.yaml execution order and schedule.
4. environments/*.environment.yaml artifact and evidence destinations.
5. connections/*.yaml secret references.
6. Merge keys and hash column policy.
7. Adapter warnings.
8. Any extensions.<adapter> blocks.

Then deploy with the adapter CLI:

contractforge-databricks deploy-project project.yaml --target dev
contractforge-aws deploy-project project.yaml --environment environments/aws.environment.yaml

The adapters execute or deploy. ContractForge AI only plans, generates, validates and explains.

What not to do

• Do not paste raw secrets into generated YAML.
• Do not let provider text override planner status.
• Do not move adapter deployment settings into ingestion contracts.
• Do not use separate Databricks/AWS contracts unless a real adapter extension or reviewed semantic difference requires it.
• Do not treat READY_WITH_WARNINGS as invisible success; keep warnings in the approval report.