Architecture and package boundaries.

ContractForge is organized around one hard boundary: the core describes ingestion intent, and adapters translate that intent to platform-native behavior.

Layered flow

The core can plan without Spark, Databricks, boto3, Azure SDK, Fabric SDK or Snowflake clients. Platform libraries live in adapter packages only.

Core responsibilities

Domain	Core owns
Contracts	Ingestion, annotations, operations, access and environment models.
Semantics	Immutable semantic contract objects and portable validation.
Capabilities	Capability declarations, matching and planning statuses.
Planning	Abstract execution plans, blockers, warnings and review markers.
Evidence	Neutral evidence concepts and required fields for operational parity.
Diagnostics	Portability messages, validation errors and adapter authoring expectations.

The core should never contain branches such as if platform == "databricks". Use capability declarations and adapter behavior instead.

Adapter responsibilities

Domain	Adapter owns
Capabilities	What the platform can preserve, what requires review and what is unsupported.
Rendering	Native SQL, Python, YAML, pipeline definitions, bundle files or review reports.
Execution	Optional runtime execution against the target platform.
Evidence filling	Platform-specific values passed into the core evidence API.
Governance application	Native grants, row filters, masks, tags, comments and policy primitives.
Runtime dependencies	SDKs, Spark, platform clients, drivers and credential resolution.

Databricks is the reference adapter. It owns Delta, Unity Catalog, Auto Loader, Lakeflow, Databricks SQL, Asset Bundles, runtime helpers and Databricks-specific extensions.

Repository layout

src/
  contractforge_core/
    contracts/
    semantic/
    capabilities/
    planner/
    evidence/
    connectors/
    adapters/base/
adapters/
  databricks/
    src/
      contractforge_databricks/
docs/
  specs/
  adrs/
site/
  docs/
  src/

Publication stays split:

Distribution	Contains	Depends on
contractforge-core	contractforge_core	No platform adapter.
contractforge-databricks	contractforge_databricks	contractforge-core.
Future adapter wheels	One adapter package each	contractforge-core.

Public APIs

The stable core API is used by tooling, CI and adapter authors:

Area	Example entry points
Contract validation	validate_contract, load_contract_bundle, compose_contract_sections
Semantic normalization	semantic_contract_from_mapping
Planning	plan_contract, PlanningResult, PlanningStatus
Capabilities	PlatformCapabilities, NativeCapability
Adapter protocol	PlatformAdapter, RenderedArtifacts

The Databricks adapter exposes Databricks-specific execution and rendering:

Area	Example entry points
Planning/rendering	plan_databricks_contract, render_databricks_contract
Runtime execution	ingest_databricks_bundle, ingest_databricks_contract
Environment	DatabricksEnvironment, DatabricksIngestOptions

Design rules

• Keep platform SDKs out of contractforge_core.
• Prefer immutable semantic objects in planner-facing code.
• Make unsupported semantics explicit.
• Never silently downgrade write mode, governance behavior or evidence requirements.
• Add docs, tests, capability mapping and adapter behavior for every new semantic concept.
• Split modules by stable domain boundaries, not by convenience.

Extension path

To add a new platform adapter:

1. Implement a capability declaration.
2. Reuse core planning unless the adapter needs stricter diagnostics.
3. Render native artifacts from the abstract plan.
4. Fill the neutral evidence model with platform-specific values.
5. Document supported, warning, review-required and unsupported behavior.
6. Publish the adapter as its own wheel.

See Adapter authoring for the full contract.