[ElliotSun]

Summary

PR #239 defines the canonical Data Engineer contract-release and runtime-deployment workflow around two immutable handoff artifacts:

base + candidate
→ GovernanceDecision
→ ChangeSet
→ ReleasePlan
→ VersionResolution
→ ReleaseSnapshot
→ ReleaseBundle
→ PUBLISH approval when REVIEW
→ ContractRelease
→ materialized versioned ODCS

Then, independently:

candidate source OR ContractRelease
+ DeploymentTarget
→ DeploymentSourceSnapshot
→ DeploymentPlan
→ CI-time DeploymentPreview
→ DeploymentBundle
→ protected CD execution context
→ fresh runtime observation
→ fresh DeploymentPreview
→ apply
→ fresh reconciliation
→ IN_SYNC / DRIFT / INDETERMINATE

Core boundaries

• Contract release and runtime deployment are separate lifecycles.
• A ContractRelease is target-neutral and versioned once.
• ContractRelease is provenance, not DEPLOY authorization.
• Runtime execution permission belongs to the surrounding protected CI/CD context.
• Git is a low-frequency governance ledger, not the CI/CD artifact transport and not an operational telemetry database.
• ApprovalRecord artifact is the canonical REVIEW handoff; persisted Git approval history remains audit/conflict evidence and a fallback lookup.
• DeploymentBundle is target-specific and never replays CI SQL blindly; CD always re-observes runtime.
• Candidate deployment does not calculate another semantic version, create release approval, or create release history.

Canonical CLI

Formal release:

semapact release assess ... --bundle-out release.bundle.json
semapact release approve \
  --bundle release.bundle.json \
  --approval-out release.approval.json ...   # REVIEW only

semapact release finalize \
  --bundle release.bundle.json \
  --approval release.approval.json \
  --output-contract contract.yaml \
  --release-out contract-release.json

Target-specific deployment:

semapact deployment assess \
  --release contract-release.json \
  --server production \
  --bundle-out production.deployment.bundle.json

semapact deployment deploy \
  --bundle production.deployment.bundle.json

--release-id remains only as a convenience fallback for resolving the same immutable ContractRelease from Git history.

History and telemetry

Git governance ledger:

• ApprovalRecord
• ContractRelease

Operational deployment telemetry:

• disabled by default;
• optional SQLite or Delta backend via typed history.operational config;
• never written to Git by the canonical workflow;
• operational event schema is versioned independently from governance artifacts.

Pydantic SemaPactConfigSchema is the source of truth for configuration schema; schemas/semapact-config.schema.json is generated/pinned by tests.

Databricks

After a finalized ContractRelease reaches fresh IN_SYNC reconciliation, SemaPact projects release provenance to Unity Catalog:

semapact_contract_id
semapact_contract_version
semapact_release_id
semapact_source_revision

Candidate deployments do not publish formal release/version tags. Business/ABAC tags remain outside automatic projection.

Architecture fitness tests

Two GitHub Actions examples remain in the repository and exercise only public CLI surfaces:

• examples/github/data-product-ci-cd.yml
• examples/github/central-contract-repo-ci-cd.yml

They are treated as architecture/usability smoke tests for release finalization, artifact handoff, central-repo fan-out, protected production deployment, and governance-ledger persistence.

Artifact schemas

This PR is treated as a greenfield architecture. There is no backward-compatibility layer for superseded deployment/release artifacts or package aliases. Canonical deployment plan, deployment bundle, release bundle, and operational event schemas start at version 1.

Validation

Coverage includes:

• target-neutral release finalization;
• exact REVIEW approval binding;
• direct ContractRelease artifact handoff;
• candidate vs finalized-release deployment provenance;
• content-addressed ReleaseBundle / DeploymentBundle integrity;
• fresh runtime preview and fail-closed stale evidence;
• SQLite/Delta operational history;
• central-repo/data-product GitHub workflow examples;
• Databricks convergence and Unity Catalog provenance tags.