feat(deployment): add immutable CI deployment bundle handoff

.semapact.yaml

@@ -17,3 +17,4 @@ llm:
   model_name: gpt-4-turbo
   api_key: ''
   base_url: ''
+

README.md

@@ -67,20 +67,32 @@ GovernanceDecision
 Governance Gate
 ```
 
-Canonical ContractOps then carries the exact governed decision forward:
+The exact governed decision then feeds either candidate deployment or an explicit formal release:
 
 ```text
 GovernanceDecision
 → ChangeSet
-→ ReleasePlan
-→ VersionResolution
-→ ContractOpsAuthorization
-→ AppliedContractRelease
-→ DeploymentPlan
-→ DeploymentAuthorization
-→ runtime mutation
+   ├─ candidate deployment
+   │    → DeploymentSourceSnapshot(source_kind=candidate)
+   │    → DeploymentPlan
+   │    → DeploymentBundle
+   │
+   └─ formal release
+        → ReleasePlan
+        → VersionResolution
+        → ReleaseSnapshot
+        → ReleaseBundle
+        → ContractRelease
+             ↓
+          + target
+             ↓
+        DeploymentSourceSnapshot(source_kind=contract_release)
+        → DeploymentPlan
+        → DeploymentBundle
 ```
 
+Release approval protects formal publication. Runtime deployment permission belongs to the surrounding protected execution context; ContractRelease is provenance, not DEPLOY authorization.
+
 For production assurance:
 
 ```text
@@ -126,9 +138,9 @@ DRAFT → ACTIVE → DEPRECATED → RETIRED
 
 Lifecycle status does not itself mean that a revision has been authorized for release.
 
-### Side effects are operation-scoped
+### Side effects have explicit trust boundaries
 
-SemaPact distinguishes analysis and planning from side effects. APPLY, PUBLISH, and DEPLOY are separate protected operations. A publication authorization cannot be reused as runtime deployment authority.
+SemaPact distinguishes pure planning/materialization from external side effects. Formal release PUBLISH approval is recorded explicitly when governance requires review. Runtime DEPLOY permission belongs to the surrounding protected execution boundary (for example a GitHub or Azure DevOps Environment), not to the ContractRelease artifact. Release state therefore cannot authorize runtime mutation by itself.
 
 ### Runtime-aware without becoming platform-owned
 
@@ -155,7 +167,7 @@ SemaPact currently supports deterministic change analysis and lifecycle-aware po
 - relationship change handling;
 - version-policy classification;
 - deterministic `GovernanceDecision` artifacts;
-- centralized governance gates for ANALYZE / PROPOSE / APPLY / PUBLISH / DEPLOY / CI operations.
+- centralized governance and release-approval boundaries, with runtime deployment permission delegated to the protected execution environment.
 
 ### Canonical ContractOps release planning
 
@@ -177,33 +189,67 @@ SemaPact supports two version-authority modes:
 
 See [`docs/contractops_phases.md`](docs/contractops_phases.md) and [`docs/version_authority.md`](docs/version_authority.md).
 
-### Governed runtime deployment
+### Contract release and runtime deployment
+
+SemaPact treats formal contract release and runtime deployment as separate lifecycles.
 
-`semapact deployment` exposes a canonical CLI/CI surface:
+A formal release is target-neutral:
 
 ```text
-plan
-→ DeploymentPlan
+release assess
+→ GovernanceDecision
+→ ChangeSet
+→ ReleasePlan
+→ VersionResolution
+→ ReleaseSnapshot
+→ ReleaseBundle
+
+REVIEW → exact release approval
+        ↓
+release finalize
+→ ContractRelease
+→ materialize the selected version back to ODCS
+```
+
+The selected version is calculated once. The resulting `ContractRelease` can then be deployed to any number of runtime targets without another version bump:
+
+```text
+orders@1.4.0
+├── dev
+├── test
+└── prod
+```
 
-preview
-→ fresh runtime observation
-→ DeploymentPreview
+Deployment is target-specific:
 
-execute
-→ exact plan + preview + DeploymentAuthorization
-→ provider execution
+```text
+deployment assess --release ./artifacts/contract-release.json
+→ DeploymentSourceSnapshot
+→ DeploymentPlan
+→ fresh runtime preview
+→ DeploymentBundle
 
-verify
-→ fresh observation + reconciliation
+deployment deploy
+→ fresh preview → execute → fresh verify
 → IN_SYNC / DRIFT / INDETERMINATE
 ```
 
-Planning and preview are read-only. Runtime mutation occurs only through `deployment execute`, and provider execution success is not treated as convergence proof.
+Candidate/non-release deployment remains available directly from base + candidate and does not create a new contract version or release history.
 
-The first Databricks write capability is intentionally narrow: create a missing managed Delta table, add missing nullable governed columns to an existing managed table, or perform NO_OP when the governed shape is already satisfied. Rename, existing-column type/nullability mutation, required-column addition without a safe migration strategy, DROP, and existing external/non-managed asset mutation fail closed.
+Deployment telemetry is disabled by default. High-frequency execution history can be enabled once in typed `.semapact.yaml` configuration with a SQLite or Delta backend; it is not written into Git governance history. The `--operational-history` CLI option is only an override.
 
-See [`docs/deployment_plans.md`](docs/deployment_plans.md).
+For Databricks, once deployment of a finalized formal release verifies `IN_SYNC`, SemaPact projects the finalized release provenance to governed Unity Catalog tables using reserved tags:
 
+```text
+semapact_contract_id
+semapact_contract_version
+semapact_release_id
+semapact_source_revision
+```
+
+Candidate deployments do not publish formal version/release tags. Business classifications or ABAC tags are not automatically mapped.
+
+See [`docs/deployment_plans.md`](docs/deployment_plans.md).
 ### Databricks discovery and observation
 
 With the `databricks` extra, SemaPact provides a thin read-side integration using the official Databricks SDK:
@@ -329,15 +375,82 @@ pip install "semapact[databricks]"
 
 The Databricks SDK owns authentication-provider selection. SemaPact forwards supported connection hints rather than implementing a separate credential system.
 
-After an exact `AppliedContractRelease` and deployment authorization have been produced, the runtime path is exposed through:
+Assess a candidate deployment without creating a new contract version:
+
+```bash
+semapact deployment assess \
+  --base ./contracts/orders.yaml \
+  --candidate ./contracts/orders.candidate.yaml \
+  --base-revision-ref git:abc123 \
+  --candidate-revision-ref git:def456 \
+  --server development \
+  --bundle-out ./artifacts/orders-dev.bundle.json
+```
+
+Build a target-neutral formal release separately:
+
+```bash
+semapact release assess \
+  --base ./contracts/orders.yaml \
+  --candidate ./contracts/orders.candidate.yaml \
+  --base-revision-ref git:abc123 \
+  --candidate-revision-ref git:def456 \
+  --bundle-out ./artifacts/orders.release.bundle.json
+```
+
+For REVIEW releases, record the exact external approval and then finalize the release:
 
 ```bash
-semapact deployment plan --help
-semapact deployment preview --help
-semapact deployment execute --help
-semapact deployment verify --help
+semapact release approve \
+  --bundle ./artifacts/orders.release.bundle.json \
+  --actor-reference github-environment:contract-release \
+  --recorded-at 2026-09-20T10:00:00+10:00 \
+  --approval-out ./artifacts/orders.approval.json
+
+semapact release finalize \
+  --bundle ./artifacts/orders.release.bundle.json \
+  --approval ./artifacts/orders.approval.json \
+  --output-contract ./contracts/orders.yaml \
+  --release-out ./artifacts/orders.contract-release.json
 ```
 
+Finalization writes the selected semantic version back to the ODCS contract and records the immutable `ContractRelease` in the Git governance ledger. The release records the source revision from which it was derived; the finalized release identity is the immutable released-contract snapshot, not a claim that the source revision already contained the materialized version bump.
+
+Deployment then consumes the finalized release artifact directly:
+
+```bash
+semapact deployment assess \
+  --release ./artifacts/orders.contract-release.json \
+  --server production \
+  --bundle-out ./artifacts/orders-prod.deployment.bundle.json
+
+semapact deployment deploy \
+  --bundle ./artifacts/orders-prod.deployment.bundle.json \
+  --warehouse-id <databricks-sql-warehouse-id>
+```
+
+Candidate deployments do not require release approval.
+
+Operational deployment history is configured project-wide rather than repeated on every deploy:
+
+```yaml
+history:
+  operational:
+    backend: sqlite
+    path: .semapact/operational.db
+```
+
+For a shared Delta sink:
+
+```yaml
+history:
+  operational:
+    backend: delta
+    table_uri: s3://governance/semapact/operational-history
+```
+
+The config is fail-closed against the typed `SemaPactConfigSchema`. `--operational-history` remains available only as a per-invocation override. If neither config nor override is present, operational persistence stays disabled. See [`docs/configuration.md`](docs/configuration.md) for precedence and schema details.
+
 ## Optional Dependencies
 
 | Extra | Purpose |
@@ -359,29 +472,28 @@ Optional extras are intentionally separate from the base distribution. If an int
 
 ```text
 semapact/
-  core/             # loading, validation, compatibility workflow boundaries
+  core/             # loading, configuration and validation
   lifecycle/        # canonical identity, lifecycle and change policy
   governance/       # GovernanceDecision and centralized gate
-  contractops/      # deterministic release planning / authorization / apply / publish domain
-  deployment/       # provider-neutral deployment plans, authorization, preview contracts
+  contractops/      # deterministic release planning, approval and release artifacts
+  deployment/       # provider-neutral deployment source, plan and preview contracts
   runtime/          # provider-neutral governed runtime asset projection
   application/      # interface-independent use-case models + orchestration
     models/         # application result DTOs; no domain authority
     services/       # thin orchestration over canonical domain rules/ports
-  services/         # backward-compatible imports only
   observation/      # platform-neutral observed state + fingerprint
   reconciliation/   # governed desired vs observed comparison
   platforms/        # provider adapters such as Databricks
   importers/        # external metadata → ODCS projection
   exporters/        # SQL / graph and other outputs
   quality/          # quality intent adapters
   interfaces/       # CLI and user-facing boundaries
-  devops/           # Git / CI compatibility helpers
+  devops/           # Git / CI integration helpers
 ```
 
 A central architectural rule is:
 
-> **Interfaces parse and render. Application services orchestrate. Domain packages own business meaning. Platform adapters own provider-specific effects. Compatibility packages do not become new owners.**
+> **Interfaces parse and render. Application services orchestrate. Domain packages own business meaning. Platform adapters own provider-specific effects. There is one canonical workflow per lifecycle.**
 
 See [`ARCHITECTURE.md`](ARCHITECTURE.md) for package/model placement rules.
 

docs/approval_history.md

@@ -102,6 +102,39 @@ record = service.record_review_action(
 Callers using another future persistence backend can provide the same
 `ApprovalHistoryRepository` capability without changing `ApprovalRecordService`.
 
+## Release approval handoff and resolution
+
+Formal REVIEW approval belongs to the PUBLISH boundary, not to runtime deployment.
+
+The canonical CI/CD handoff is an exact `ApprovalRecord` artifact:
+
+```text
+release assess
+→ ReleaseBundle
+
+protected release environment
+→ release approve --approval-out release.approval.json
+
+release finalize --approval release.approval.json
+→ ContractRelease
+```
+
+The approval must match all of the following:
+
+- exact `decisionId`;
+- exact `changeSetId`;
+- exact `releasePlanId`;
+- exact `versionResolutionId`;
+- operation `PUBLISH`;
+- exact `ReleaseSnapshot` as `scopeReference`;
+- exact `ReleaseBundle` digest in `evidenceReferences`.
+
+`release approve` also persists the same approval in the Git governance ledger. That ledger is durable audit/conflict evidence, not the preferred in-pipeline transport.
+
+As a convenience fallback, `release finalize` may resolve the same exact PUBLISH approval from the Git ledger when `--approval` is omitted. If the exact scope contains conflicting review evidence such as `REQUEST_CHANGES` or `REJECT`, finalization fails closed. SemaPact does not apply a hidden "latest review wins" rule.
+
+Runtime deployment has no SemaPact deployment-approval artifact. Whether `semapact deployment deploy` may run is controlled by the surrounding protected CI/CD execution context. Candidate deployment therefore does not create or resolve release approval records, and a finalized `ContractRelease` is provenance rather than DEPLOY authority.
+
 ## Trust boundary
 
 `ApprovalRecord` preserves review evidence; it is not an authentication credential.

docs/configuration.md

@@ -0,0 +1,59 @@
+# Configuration
+
+SemaPact loads configuration in this order:
+
+1. explicit CLI override for the current operation;
+2. local project config at `.semapact.yaml`;
+3. global config at `~/.config/semapact/config.yaml`;
+4. feature default.
+
+Operational deployment history is disabled when no backend is configured.
+
+## Operational history
+
+SQLite:
+
+```yaml
+history:
+  operational:
+    backend: sqlite
+    path: .semapact/operational.db
+```
+
+Delta:
+
+```yaml
+history:
+  operational:
+    backend: delta
+    table_uri: s3://governance/semapact/operational-history
+```
+
+The configuration is validated fail closed. Supported backends require exactly their backend-specific fields:
+
+- `sqlite`: `backend` + `path`;
+- `delta`: `backend` + `table_uri`.
+
+Unknown backends, missing required fields, and extra fields under `history.operational` are rejected.
+
+The canonical schema is defined by `SemaPactConfigSchema` and published for editor/tooling use at:
+
+```text
+schemas/semapact-config.schema.json
+```
+
+## CLI override
+
+`--operational-history` is a per-invocation override, not the normal configuration path.
+
+For example:
+
+```bash
+semapact deployment deploy \
+  --bundle ./artifacts/orders.bundle.json \
+  --operational-history sqlite:///./tmp/one-run.db
+```
+
+If the flag is omitted, SemaPact resolves `history.operational` from project/global config. If neither exists, operational history persistence remains disabled.
+
+Operational telemetry is separate from the Git governance ledger. Formal release/approval facts may be stored in Git, while high-frequency deployment events are written only to an explicitly configured SQLite or Delta backend.