Compatibility

Workload selection v1

--select and --exclude are additive project-workload options on check, airflow preview, and bounded run --sample --target temporary. Existing single-pipeline calls remain valid. Existing run --selector keeps its older meaning: one process selector inside a batch manifest. It is not renamed or reinterpreted by workload selection v1.

Selected preview output is an ordinary immutable release/deployment projection, so published provider APIs and previously generated release ids remain valid. State and named-selector files are build-plane inputs and are never required by the Airflow scheduler.

dpone follows a compatibility-first approach for manifests, public imports, CLI commands, and runtime connector contracts.

Project layout compatibility

Missing layout in dpone.yaml is exactly the existing flat behavior: pipeline sources remain under pipelines/, domain orchestration remains under domains/, and hermetic tests remain under top-level tests/.

layout.mode: domain_first is an explicit additive choice. It moves authoring authority to:

<layout.root>/<domain>/ownership.yaml
<layout.root>/<domain>/pipelines/<pipeline-id>/pipeline.yaml

Domain-first discovery is build-plane only. Airflow still parses immutable deployment indexes and never scans authoring directories. The generated dpone.workload-index.v1 is a projection, not a replacement source of truth. Its closed v1 projection binds layout root/scope, ownership, canonical source semantics, dependencies, logical connection refs, and durable Airflow participation. Baselines produced by development snapshots before this contract, or baselines whose declared fingerprints do not recompute, must be regenerated; dpone does not reinterpret them.

New scaffolds persist metadata.airflow as a boolean. Existing sources that omit it retain enabled behavior. metadata.airflow: false remains a valid runtime workload and produces no Airflow DAG. A first disabled preview creates no artifacts. If a verified current local preview still advertises the same pipeline and no other workload, dpone promotes an empty immutable compensating projection before returning DPONE_AIRFLOW_DISABLED. A multi-workload current is preserved and requires the reported bounded project refresh, preventing unrelated DAG removal.

No automatic file migration occurs between layouts. Changing layout.mode or layout.root without moving and validating the corresponding authoring sources fails closed. Existing flat projects require no edits.

dpone init pipeline is the canonical beginner authoring command in both layouts. Historical dpone workload init remains an advanced compatibility surface for GitOps catalog workflows; it is not the domain-first golden path.

Supported Python versions

dpone targets modern Python versions supported by the current packaging metadata. Use the published PyPI metadata as the source of truth for exact supported versions.

Airflow provider compatibility

The scheduler-side provider contract is intentionally narrow:

requires_airflow: ">=2.10,<3.4"
required_capabilities:
  - task_groups
optional_capabilities:
  - assets
  - partitioned_assets
  - dag_bundles

The exact CI matrix is:

Airflow	Python	apache-airflow-providers-cncf-kubernetes	Support tier
2.10.5	3.11	10.1.0	compatibility
2.10.5	3.12	10.1.0	compatibility
2.11.0	3.11	10.5.0	compatibility
2.11.0	3.12	10.5.0	compatibility
3.2.0	3.11	10.14.0	primary
3.2.0	3.12	10.14.0	primary
3.3.0	3.11	10.19.0	latest
3.3.0	3.12	10.19.0	latest

Provider pins follow the official Apache Airflow constraints files for each Airflow and Python pair. Expanding beyond <3.4 requires adding the new line to this table and to .github/workflows/airflow-pack-compat.yml in the same PR.

Executable indexed delivery has an explicit wire boundary:

Index	Delivery	Compatibility behavior
dpone.airflow-deployment-index.v1	local_preview	supported non-runnable preview
v1	init_fetch	fail closed with DPONE_RUNTIME_ARTIFACT_DELIVERY_MIGRATION_REQUIRED
dpone.airflow-deployment-index.v2	init_fetch	strict executable KPO path

The v0.73.1 four-option dpone airflow build invocation still parses, but it cannot safely reproduce the former incomplete v1 executable projection. It returns exit 2 with the migration code and no durable side effects. Supply the explicit trust tier, exact digest-pinned OCI image, and complete registry/trust ConfigMap references documented in the migration guide. Immutable v1 indexes are regenerated; they are never edited in place.

The canonical airflow.providers.dpone namespace is a PEP 561 typed package. Its stub exposes concrete Airflow DAG/TaskGroup returns and literal duplicate / invalid-DAG policies across the tested matrix. Type-only compatibility imports do not change the runtime rule: Airflow 3 materialization prefers airflow.sdk, Airflow 2 uses the supported fallback, and importing the provider without Airflow installed remains side-effect free. Legacy facade exports from dpone_airflow_pack retain their existing deprecation window and delegate to the same typed implementation.

Partition-aware assets are capability-gated independently from provider import compatibility:

Airflow line	Asset surface	dpone partition behavior
3.2.x, 3.3.x	Asset partitions and public SDK timetables	native CronPartitionTimetable / PartitionedAssetTimetable with identity mapping
3.0.x, 3.1.x	Assets without partition timetables	explicit degraded_unpartitioned
2.10.x, 2.11.x	Dataset-compatible downgrade	explicit degraded_unpartitioned

An unavailable partition SDK is a supported downgrade. A partially available SDK, timetable constructor failure, mixed contracts, or missing native partition key is an error and never silently degrades. Exact Airflow-matrix CI is required before expanding this table; live producer-to-consumer event certification remains separate from package compatibility.

Public compatibility surface

The stable surface includes:

• Manifest schema fields documented in this site.
• CLI commands documented in CLI reference.
• Public imports exported by dpone and connector modules.
• Connector contracts used by source, sink, state, schema evolution, and quality services.

Internal modules may change between minor versions when they are not part of the documented public surface.

Airflow authoring modes

classic, flow, and folder are alternative primary authoring modes. A pipeline must use exactly one. Folder mode is additive: its root remains dpone.flow.v1, while explicitly listed dpone.flow-fragment.v1 files provide the process list. Existing classic, flow, dpone.batch.v1 + processes, and dpone.pipeline.v1 inputs keep their current compatibility behavior.

No migration is automatic. dpone migrate authoring --plan|--apply performs an explicit source-to-source rewrite and blocks unless the canonical semantic fingerprint remains equal. Recipe-authored sources are intentionally excluded: materializing a recipe would discard its version and provenance contract. Folder compilation reads no undeclared files and does not alter the Airflow parse contract; generated release, deployment, DAG-spec, and pack artifacts remain the provider input. The additive command and dpone.authoring-migration.v1 receipt do not change existing source behavior.

Declarative recipes, profiles, and components

External dpone.recipe.v1, dpone.profile.v1, and dpone.component.v1 artifacts are an additive flow authoring surface. Existing built-in recipes and explicit classic/flow/folder sources keep their behavior. External recipe sources require exact id@MAJOR.MINOR.PATCH refs plus immutable path/SHA-256 pins; version ranges and mutable aliases are not accepted.

The selected primary source remains the only editable pipeline authority. The recipe resolver returns data-only process mappings to the existing canonical compiler. Packs materialize generated dpone.batch.v1 runtime IR, so neither Airflow parse nor workload runtime executes recipe Python/Jinja/plugin code. Changing a recipe/profile/component version is an explicit authoring change and changes the source/release identity. Changing only artifact bytes behind an existing pin fails closed as digest drift.

Artifact lifecycle is publication-time-only. deprecated artifacts continue to resolve under their immutable pins and emit a deterministic warning. They remain readable until the normal public deprecation window has elapsed; an immutable artifact is never modified in place to propagate deprecation metadata. See Recipes, profiles, and components.

Hermetic pipeline tests

dpone.test.v1, dpone.test-report.v1, and dpone.test-suite-report.v1 are additive public contracts. Existing pipelines do not require test files. New Airflow self-service scaffolds add one starter test and fixture; repeated scaffold runs remain deterministic no-ops.

Hermetic v1 supports connector-neutral full_refresh, incremental_append, and fail-on-duplicate incremental_merge final-state semantics. Unsupported SQL, transforms, connectors, or strategy behavior fails explicitly rather than changing runtime behavior. Future optional expectations may be additive; changing existing defaults, identity inputs, exit meanings, or report redaction requires the normal deprecation policy. See Hermetic pipeline tests.

Airflow process visibility and selector-safe packs

execution.visibility is additive. Newly compiled processes default to inline; their DAG-spec nodes contain an explicit selector, visibility, TaskGroup metadata, and visible-task estimate. Existing DAG specs that omit visibility retain the former expanded task presentation.

New compact schema-v3 packs may contain runtime_selection: process_plan and a bounded process_plans mapping. The provider selects one prebuilt command and step graph and never edits shell text during DAG parsing. A selected node that references an older pack without a matching process plan fails closed with DPONE_AIRFLOW_PACK_SELECTOR_UNSUPPORTED; rebuild and promote the matching release/deployment rather than modifying an immutable pack. Selector-less legacy nodes continue to use the old top-level runtime command.

DponeTaskGroup.from_pack remains the complete-pack escape hatch. A multi-process process-plan pack therefore uses its top-level whole-workload command inside that explicit TaskGroup; it does not project selector plans. The lower-level selector-less task builder keeps the same whole-pack behavior for backward compatibility. Process-scoped plan selection is owned only by DponeDag.from_spec and load_dpone_dags when a DAG-spec node supplies the selector.

inline validates synchronous KPO results after execute and deferrable KPO results after trigger_reentry, which is the supported CNCF Kubernetes provider callback across the tested matrix. Provider lines that publish the sidecar result through task XCom but return None are normalized by reading that already-published value during task execution; this never happens during DAG parsing. A missing, malformed, or non-passed XCom summary fails the Airflow task; no visibility mode can convert a dpone runtime failure into Airflow success.

Bounded Airflow backfill mapping

airflow.mapping is additive and defaults to internal; existing packs and workloads keep one concrete Airflow runtime task. New packs may carry dpone.airflow-mapping-plan.v1 and mapped items use dpone.airflow-mapping-item.v1. Rebuild the release with a current provider before enabling visible or summary; an older provider must not interpret a mapped plan as an internal campaign. Generated mapped packs expose mapped_kpo_kwargs instead of legacy kpo_kwargs; the current provider normalizes it only after plan validation, while older providers stop on their existing required-field check.

The provider compatibility matrix above constructs a real mapped KubernetesPodOperator on Airflow 2.10.5, 2.11.0, 3.2.0 and 3.3.0. The contract uses only partial/expand, a static pool and max_active_tis_per_dag. It does not read max_map_length or any other Airflow configuration during parse.

Mapped execution is certified only for PostgreSQL and MSSQL audit-state coordination in v1. Local-file and ClickHouse audit state remain valid for internal mode but reject mapped mode with DPONE_AIRFLOW_MAPPING_STATE_UNSUPPORTED. Rollback is configuration-only: change the policy to internal, rebuild and promote. The deterministic chunk identities and ledger remain reusable; do not delete the campaign state.

Canonical DLQ and legacy quarantine

sink.options.dlq is additive and defaults to reference_only when schema enforcement is quarantine. Canonical dpone.dlq.v1 artifacts contain no raw row values by default, use stable reason codes, and are verified by checksum. The data-contract evidence projection no longer serializes accepted target rows or invalid actual_value strings. Consumers of durable evidence must use counts, safe diagnostics, record IDs, and data_outcome instead.

The import dpone.ops.quarantine.QuarantineService, quarantine.dir, and raw JSONL export remain available for the compatibility window. They are not the default for new runtime composition. The previous quarantine-replay --yes behavior was unsafe because it reported rows as applied without invoking a sink; it now fails with exit code 4 and DPONE_DLQ_REPLAY_EXECUTOR_REQUIRED. This safety correction is intentionally immediate. Use the plan-first DlqReplayService with injected DlqRecordResolver and DlqReplaySink for real replay.

Backward compatibility policy

• Patch releases should be backward-compatible.
• Minor releases may add new optional fields, connectors, and strategies.
• Breaking changes require a migration note and should be reserved for major releases.
• Deprecated behavior should remain available for at least one minor release when practical.

Airflow cache promotion migration

The cache integrity hardening planned for 0.72.2 is an explicitly approved fail-closed security exception to the normal major-release rule: dpone airflow cache-sync no longer promotes a deployment projection when its pinned release-set or indexed DAG/workload artifacts are absent. Existing projection-only caches must rematerialize their immutable release content before upgrading. The dpone.release-set.v1 schema remains compatible with the legacy artifact_ref field when it contains a safe release-relative path; generated releases use path. Release-set cache:// references and entries with both locator fields are rejected. See the Airflow cache sync and recovery runbook.

Promotion now also recomputes deployment_id, checks every environment field mirrored into airflow-index.json, serializes CAS through a local promotion lock, and rejects symlinked control files. First promotion must use --expect-current-absent; updates use --expected-current-deployment-id. Recovery apply now requires a promoter identity and the active-state guard from the reviewed plan. Caches with non-content-addressed deployment directories or a copied current directory must be rematerialized before promotion.

Rollout is fail-closed: materialize the release and run cache-sync in a non-production cache before upgrading production. A validation failure happens before activation; pointer/audit preparation failures expose whether recovery is required. Leave the existing deployment current while the release handoff is repaired. Rolling the binary back temporarily restores the old behavior but also removes the new integrity gate; it requires an explicit security exception and is not a data-plane repair. If trusted release content cannot be recovered, stop and escalate rather than editing the published cache.

Native-transfer target-commit guard rollout

The patch after 0.73.1 adds an optional target_commit_guard inside the existing partition-checkpoint diagnostics. Checkpoint schemas, statuses and store APIs remain compatible, and old checkpoint records without the guard keep their previous resume behavior.

Runtime compatibility is intentionally asymmetric: new workers fail closed on unresolved or malformed guards, while older workers do not understand them. Do not run mixed old/new worker pools for guarded native routes. Drain older workers or disable automatic scheduling before deployment, upgrade every worker that can execute the route, then re-enable retries. A rollback to an older runtime after any guarded attempt requires an explicit safety exception and manual target/checkpoint reconciliation.

native_transfer_manual_reconciliation_required is not cleared by changing query, schema or partition identity. Repair the same source/target/strategy route deliberately. The guard prevents unsafe automatic target I/O but does not provide target fencing, CAS or exactly-once certification; those remain in ADR 0022.

Native-transfer quality row authority

The same patch family adds additive checkpoint diagnostics rows_loaded and row_count_authority=source_export_and_target_loader. Checkpoint schemas and store APIs remain compatible. Older committed checkpoints without the authority marker still deserialize and participate in resume planning, but native quality scopes treat their source and target row counts as unavailable. Planned estimated_rows never certify reconciliation. Rerun the source export (or use a separately certified live target probe) to create current evidence; dpone does not manufacture provenance for old state.

Production route-attestation migration

Explicit production safe-sample execution no longer accepts raw route IDs from CLI application context as authorization. It requires the four platform-owned route-attestation inputs documented in the production route-attestation runbook. This is a fail-closed security correction: development rehearsal remains available, but production live copy does not fall back to the old string seam.

The v1 verifier certifies cosign >=3.0.4,<4.0.0, exact certificate identity and OIDC issuer matching, and a local trusted-root digest. Unsupported or unavailable verifier/trust material is unverified, never success. Expanding the version range requires current adapter tests, security review, and live certification evidence. Route-attestation schemas are additive; safe-sample runtime execution evidence gains an optional verification receipt.

Beginner automatic live-selection compatibility

Starting with 0.72.7, the existing fifth beginner command automatically selects the signed live runtime only when platform CI has materialized all four route-authorization files for the exact pinned deployment and pipeline. This is an additive facade change rather than a second execution path:

• no authorization directory preserves the existing network-free local handoff and exit behavior;
• a complete directory delegates to the same route-attestation verifier, live assembly, pinned init-fetch, temporary-target lifecycle, copier, and evidence writer used by dpone ops safe-sample-runtime-run;
• an existing but incomplete or unsafe directory fails closed instead of silently falling back;
• the explicit dpone ops safe-sample-runtime-run command remains available as the platform diagnostic and compatibility escape hatch;
• execution_mode is an optional additive field in dpone.safe-sample-runtime-execution.v1, so previously written v1 evidence remains valid.

The overlay status field is named authorization_overlay_profile; it describes the local cache-layout contract and must not be confused with the signed route-attestation authorization_profile. External manifests require no migration. Platform CI may opt in by atomically publishing the layout in the production route-attestation runbook.

Upgrade and rollback are explicit:

1. Upgrade without publishing an overlay to retain the 0.72.6 network-free behavior.
2. Verify and atomically publish a complete deployment/pipeline overlay to opt that deployment into automatic live selection.
3. If a partial directory is observed, replace it from staging and rerun the same beginner command; do not edit immutable files in place.
4. To roll back the facade selection, atomically remove the complete overlay. The next invocation returns to local_handoff; already persisted evidence remains immutable. The explicit platform command is unchanged.

Airflow Connection Secret isolation

Starting with 0.72.8, the operator-side Airflow Connection bridge treats the pack's connection_projection.secret_name as a base prefix and derives one physical Kubernetes Secret per Airflow task attempt. Existing compact packs and schemas remain valid; no authoring migration is required.

This is an intentional fail-closed security correction. The compatibility-named AirflowConnectionSecretProjector.upsert() method now means create-only publication. A pre-existing name returns DPONE_AIRFLOW_CONNECTION_SECRET_CONFLICT and is never replaced. Injected projector implementations require a code review/migration to the same create-only semantic contract even though the Python method signature is unchanged. Synchronous cleanup deletes only the derived attempt object; deferrable runs still require cleanup_policy: retain and platform-managed cleanup.

Provider code that inspected the internal airflow_connection_projected_secret attribute now receives only digest-safe reference metadata rather than URI-bearing stringData. Use airflow_connection_projected_secret_ref for new diagnostics. Rolling back restores shared mutable Secret behavior; if rollback is unavoidable, serialize all bridge tasks through an Airflow pool until the fixed provider is restored.

Deterministic local concurrency and lifecycle contracts are covered by the v0.72.8 test suite. Real overlapping Airflow/Kubernetes execution remains UNVERIFIED until an approved cluster produces the live certification artifact; this does not weaken the fail-closed runtime behavior, but it is not a production certification claim.

Airflow Connection Secret retention GC

Starting with 0.72.9, new attempt Secrets and their consuming Pods carry digest-only lifecycle metadata. Existing compact packs remain valid and ordinary pipeline owners do not gain a new command. Platform operators can use dpone airflow connection-secret-gc-plan followed by an explicitly confirmed connection-secret-gc-apply in one namespace.

The platform command uses the optional dpone[kubernetes] extra (kubernetes>=32.0.1,!=36.0.0,<37). Base dpone and scheduler-side provider imports remain SDK-free. Existing Airflow images may satisfy the dependency through their CNCF Kubernetes provider; a separate restricted GC image is preferred to avoid coupling scheduler packages and platform cleanup RBAC.

The GC never adopts pre-0.72.9 unlabelled objects. Review and remove those through the v0.72.8 digest-reconstruction procedure. Injected/custom Secret projectors must preserve the provider-supplied labels and annotations; no Python signature changes, but dropping metadata means the object remains a manual-cleanup object. Deploy the provider first, observe plans for at least one retention window, then enable apply.

The dedicated GC identity needs namespace-scoped list on Secrets and Pods and delete on Secrets. Kubernetes RBAC cannot constrain list secrets to the metadata representation, so use a dedicated ephemeral-credential namespace and do not give this identity a general shell. The client itself requires PartialObjectMetadataList and fails on HTTP 406; it never falls back to a full Secret/Pod response. Remove the obsolete replace permission from the provider task identity.

Rollback is non-destructive: suspend GC apply first, then roll back the CLI or provider. Existing labelled objects remain eligible for a later fixed GC; newly created unlabelled objects require manual cleanup. Local fake-transport, concurrency, redaction, and 10,000-item inventory tests are covered in v0.72.9. Real Airflow/Kubernetes lifecycle certification remains UNVERIFIED until an approved cluster produces current evidence.

Airflow release/deployment artifact delivery

Starting with 0.72.10, dpone airflow publish and dpone airflow cache-materialize are the canonical platform surfaces for one content-addressed release/deployment pair. They are additive: existing authoring sources, local_preview release/deployment projections, local cache-sync, provider loader APIs, and compact packs require no migration. Executable v1 init_fetch is the exception: it is rejected fail-closed and must be regenerated as a new immutable deployment-set.v2 / airflow-deployment-index.v2, then published, materialized, and promoted. Never rename or edit the v1 projection in place.

dpone gitops airflow publish and dpone-airflow-pack-sync remain legacy pack-only compatibility paths for at least two minor releases and 12 months. They retain their historical generation/latest behavior, but that behavior is never imported into the canonical release/deployment identity model. New deployments must not mix a mutable legacy index with dpone.airflow-deployment-index.v1.

Concrete built-in object-storage clients gain additive put_file_if_absent() and stat() methods. The existing ObjectStorageClient protocol is unchanged for third-party staging clients; the new interface-segregated ImmutableObjectStorageClient capability carries the two stronger operations. Custom clients used as the new ArtifactRegistry backend must implement true conditional create; an overwrite emulation is incompatible and fails the immutability contract.

Azure registry workload identity requires dpone[azure] or dpone[object_storage], which include azure-identity>=1.13,<2, and the account-scoped URI azure://<account>/<container>/<root>. Existing injected Azure clients may continue to use the accountless az:// compatibility form; the workload-identity composition rejects it because an account endpoint cannot be derived safely.

Rollback means stop invoking the new publisher/materializer and leave the last validated local current active. Do not overwrite or delete content-addressed remote objects to roll back. Production materialization remains fail-closed when required_for_prod attestation cannot be verified. Local adapter tests do not constitute S3/GCS/Azure or Kubernetes production certification; those profiles remain UNVERIFIED until current approved evidence exists.

Formal Airflow provider and v1 public contract

The canonical airflow.providers.dpone namespace and Airflow discovery entry point are owned by apache-airflow-providers-dpone. The dpone-airflow-pack distribution is its dependency-light static reader and no longer owns discovery metadata. Both distributions stay on the same dpone release line.

Provider facade exports from dpone_airflow_pack remain compatibility aliases for at least two minor releases and 365 days after their 0.72.0 announcement, whichever is later. Their earliest removal is therefore both release 0.74.0 or later and date 2027-07-13 or later. They warn at most once per process; new code imports airflow.providers.dpone.

The reviewed Airflow self-service public contract freezes the beginner CLI, canonical provider signatures, schema majors, package ownership and support window targeted for v1. CI checks the real parser, provider AST, schema registry and package metadata without importing Airflow or performing network, database, secret or cache-refresh I/O.

Airflow self-service authoring v1

New dpone init pipeline calls emit dpone.flow.v1 unless --authoring classic is selected. Flow, folder, and classic modes compile into the existing dpone.batch.v1 canonical execution IR, so pack, release, runtime, and provider contracts are unchanged. The incorrectly labelled legacy kind: dpone.batch.v1 plus processes: source remains readable and reports DPONE_LEGACY_SELF_SERVICE_BATCH_PROCESSES; new sources must use kind: dpone.flow.v1. The earlier safe-sample schema: dpone.pipeline.v1 shape remains readable with DPONE_LEGACY_SELF_SERVICE_PIPELINE_V1. Folder composition is additive and uses an explicit, confined, resource-bounded fragment list; it does not scan directories or change scheduler parse behavior.

The compatibility aliases are intentionally reader-only and do not validate against the current batch JSON Schema. Schema validation is the write contract: rename the short source kind to dpone.flow.v1 and set authoring.mode: flow. Runtime/check compatibility prevents an emergency break, but does not authorize new batch + processes files.

Airflow composite identity and rerun plans

Index-backed provider tasks add dpone.airflow-run-identity.v1 to task params, runtime environment, XCom, and evidence. Existing deployment indexes without airflow_bundle_ref, legacy tasks without the environment value, and older XCom/evidence files remain readable because the new fields are additive. A release-policy evidence bundle requires the identity; advisory/PR collection reports its absence as a warning.

dpone airflow rerun-plan never invents missing historical state. Critical plans require complete release/deployment/runtime references and a versioned Airflow bundle or a content-addressed snapshot. Git bundle refs are treated as versioned. Local, S3, GCS, and unknown bundle refs are non-versioned unless a snapshot is present, so selecting an original bundle fails with DPONE_RERUN_NOT_REPRODUCIBLE. Selecting the latest non-versioned bundle is an explicit warning only for a non-critical plan.

Airflow bundle selection and dpone artifact selection remain independent. An original/original plan requests clearing the existing run without Airflow's latest-version override; every mixed/latest selection requests a new pinned rerun. The planner performs no Airflow API call. Rollback stops injecting the optional identity and leaves existing artifacts readable; it cannot make an expired release or non-versioned historical bundle reproducible.

Airflow observability correlation

dpone.airflow-correlation.v1 is additive to the final Airflow evidence bundle. Existing evidence, OpenLineage exports, and OTel-compatible metrics exports remain readable when no correlation input is supplied. Supplying --airflow-evidence-bundle opts into strict validation: the bundle must contain a complete correlation, otherwise the exporter exits red instead of silently emitting partially joined telemetry.

OpenLineage keeps the historical dpone run ID when no correlation is supplied. With correlation, run.runId is a deterministic UUIDv5 and the original dpone run ID remains in the dpone facet. The custom correlation facet uses a pinned v0.73.0 schema URL. OTel correlation attributes are additive. They are not copied into Prometheus labels, baggage, or synthetic trace/span identifiers. Rollback is omission of the optional evidence-bundle argument; no stored run identity or immutable evidence is rewritten.

Credential resolver lifecycle

The connection-registry v1 schema continues to parse version_policy: pinned and resolution_scope: dag_run_start for diagnostic and migration compatibility. dpone does not execute those values: readiness and runtime return DPONE_CREDENTIAL_PINNED_VERSION_UNSUPPORTED or DPONE_CREDENTIAL_DAG_RUN_SCOPE_UNSUPPORTED before credential backend I/O. The supported runtime policy is latest + workload_start.

For explicit Vault KV v2 entries, successful evidence requires a positive resolved version and every declared field mapping must produce a non-empty value. Vault KV v1 remains readable with resolved_version: null and is not rotation-version certified. CredentialResolutionError subclasses ValueError, preserving callers that already catch validation failures while adding stable code and resolver fields. See the credential lifecycle compatibility and recovery runbook.

Studio API v1 and capability discovery

The canonical Studio HTTP surface is /api/v1/*; /healthz and /openapi.json remain unversioned protocol endpoints. Existing /api/* operations remain deprecated compatibility surfaces for at least two minor releases and 12 months, with an earliest planned removal date of 2027-07-23. They emit Deprecation: true, Sunset, and an OpenAPI Link header. /api/manifests/draft and /api/plan are direct aliases. Connector, connection-capability, and certification views migrate to /api/v1/capabilities while preserving their old response shapes on old paths. Doctor, performance, state, run, security, audit, SLO, deployment, schema, quality, GitOps, and reconciliation operations are retirement-only: they have no v1 replacement and must not be adopted by new clients.

Safety corrections are not optional compatibility modes:

• empty, skipped-only, and plan-only quality checks no longer report success;
• quality outcome status is passed, failed, skipped, or unverified; advisory failures retain mode: warn instead of inventing a fifth status;
• missing, stale, failed, malformed, or foreign-commit certification evidence cannot promote route certification;
• mock contract certification remains behaviorally reportable but is UNVERIFIED and cannot satisfy evidence-bundle/go-live gates;
• unsupported route drafts, plans, static checks, and reconciliation fail before project writes or successful plan output;
• Studio plan and static-check compile one canonical process snapshot, so classic schemas[].tables[].overrides cannot bypass route support checks;
• Airflow explain reads only the requested pipeline.

Legacy certification JSON that has passed: true but no evidence_status: PASS now fails every certification-sensitive release gate. This is an intentional safety correction. Regenerate the artifact with a current certifier; do not edit historical evidence. Generic non-certification artifacts retain their existing evaluation contract. The positional ConnectorCatalogEntry constructor remains source-compatible: omitted maturity defaults to experimental, and omitted release_phase inherits the legacy status.

dpone connectors certify is strict by default. --report-only explicitly selects a non-gating report. The old --fail-on-missing option remains accepted with one process-level deprecation warning during the same compatibility window.

The generated Studio OpenAPI contract, dpone.capability-discovery.v1, and dpone.pipeline-summary.v1 are additive public contracts. The bundled stdlib server remains a local development adapter; shared-token remote opt-in is not production hosting or RBAC.

Direct Python construction through StudioApiService(artifact_roots=...) and the historical openapi(), record_audit(), certification_matrix(), and capabilities() methods remain as deprecated compatibility facades through at least 2027-07-23. capabilities() preserves its historical connection DTO; canonical /api/v1/capabilities uses capability_snapshot(). New integrations construct the DI-first service with build_studio_api_service() or consume /api/v1; compatibility calls emit one DeprecationWarning per symbol and retain the hardened fail-closed semantics.

Historical imports of StudioApiError, StudioHttpConfig, and StudioAuditLog from dpone.readiness.studio_api remain re-exports for the same window. Their canonical module is dpone.readiness.studio_http_models.

Legacy connectors certify capability rows keep their historical lowercase unknown value inside the legacy DTO. Canonical capability discovery does not reuse that field: it exposes evidence as PASS, FAIL, SKIP, or UNVERIFIED and keeps connector maturity, release phase, route support, and certification level separate. Mocked, missing, stale, skipped, malformed, or foreign-commit evidence is always UNVERIFIED; only approved current evidence for the exact subject and commit can certify a route.

The marketplace projection is now explicitly dpone.connector-marketplace.v2. Its legacy status and badge fields map to the connector release_phase; canonical maturity and release_phase are also present and must be used by new consumers. The projection carries the canonical snapshot_id, passed, and issues; marketplace CLI and evidence bundles fail when capability authority has issues. This safety correction removes the old ambiguous use of certified as a connector-wide claim without route evidence.

Self-service and discovery result payloads remain on stdout, including structured passed: false results, so existing automation can always decode the command result from one stream. The exit code remains authoritative. Parser/usage diagnostics and fatal Studio startup errors use stderr. Commands may return usable discovery data together with passed: false and issues[], but exit non-zero until the project configuration issue is fixed.

MSSQL BCP streaming buffer migration

source.options.native_transfer.snapshot.streaming.read_buffer_bytes replaces the deprecated streaming-only field target_chunk_bytes. The canonical field controls the number of bytes requested from the BCP FIFO per read, defaults to 4MiB, and accepts 64KiB..16MiB. String values use whole KiB or MiB units; integer values are bytes.

The canonical field is introduced in 0.72.4. The legacy field remains accepted through the 0.73.x dedicated deprecation release, with 0.74.0 as the earliest possible removal. Its value intentionally does not control the effective buffer because previous releases always read a fixed 4 MiB. When both fields are present, the canonical field wins and runtime decision evidence includes streaming_target_chunk_bytes_deprecated_use_read_buffer_bytes. Values outside the canonical range fail before BCP with streaming_read_buffer_bytes_out_of_range. Malformed legacy-only values continue to fail before BCP, now with streaming_target_chunk_bytes_invalid. A malformed legacy value is ignored only when a valid canonical field is present and therefore has precedence.

Replace only the full snapshot.streaming.target_chunk_bytes path. Do not rename physical_chunking.target_chunk_bytes, columnar/object-storage chunk targets, or execution.transport.stream_buffer_bytes. Rolling back to a release without the canonical field requires restoring the legacy streaming key; custom buffer tuning then falls back to the historical 4 MiB behavior.

SQL dependency symlink hardening

Canonical authoring compilation now records SQL dependencies by their lexical project-relative path and rejects symbolic links at every path component. This closes a check-to-use race in which a symlink could be retargeted after compilation while the recorded resolved target remained unchanged.

Projects that previously referenced an in-repository SQL symlink must replace it with a regular project file or generate the file before dpone check. Absolute paths, traversal, symlinked parents, and final-leaf symlinks fail with DPONE_AUTHORING_DEPENDENCY_READ_FAILED; dpone does not silently follow or copy the target. Regular SQL files and their semantic fingerprints are unchanged.

Signed catalog bundles and conformance

dpone.catalog-bundle.v1 is an additive platform promotion format. Existing trusted local recipe catalogs and connection registries remain readable and do not require signatures unless a platform policy separately requires the signed promotion path. Bundle verification does not alter recipe pins, deployment fingerprints, Airflow parsing, or runtime credential resolution.

The existing route-attestation Python imports and route-specific error codes remain stable. They delegate to the same generic bounded cosign blob verifier used by catalog verification. The local HMAC supply-chain helper remains non-production and is not accepted as catalog verification evidence.

Extension conformance is additive release evidence. PASS describes the exact subject and closed profile only; it does not upgrade a connector route or credential resolver to production-certified without the profile's required approved live evidence.

Connector maturity labels

• certified - covered by the required unit, contract, local integration, and approved current live certification artifacts for the exact subject and commit. Mock artifacts never establish this status.
• experimental - usable but still missing part of the certification matrix.
• community - maintained through public contribution flow and must declare its supported capabilities.

Generated compatibility matrix

Deprecated path	Canonical path	Scope	Status	Removal policy
dpone.core.artifacts	dpone.runtime.artifacts	module	transitional-shim	after internal callers migrate to runtime.artifacts
dpone.core.errors	dpone.contracts.errors	module	transitional-shim	after internal callers migrate to contracts.errors
dpone.core.etl_types	dpone.contracts.process_types	module	transitional-shim	after internal callers migrate to contracts.process_types
dpone.core.runtime	dpone.contracts.run_context	module	transitional-shim	after internal callers migrate to contracts.run_context
dpone.credentials	dpone.runtime.credentials	package	deprecated-shim	after one dedicated deprecation release
dpone.etl	dpone.runtime.etl	package	deprecated-shim	after one dedicated deprecation release
dpone.etl_logging	dpone.runtime.etl_logging	package	deprecated-shim	after one dedicated deprecation release
dpone.lib.connectors	dpone.runtime.connectors	package	deprecated-shim	after one dedicated deprecation release
dpone.lib.connectors.base	dpone.ports.db_connector	module	transitional-shim	after internal callers migrate to ports.db_connector
dpone.lib.technical_columns	dpone.contracts.technical_columns	module	transitional-shim	after internal callers migrate to contracts.technical_columns
dpone.lib.utils.data_type_mapper	dpone.runtime.support.data_type_mapper	module	transitional-shim	after internal callers migrate to runtime.support.data_type_mapper
dpone.lib.utils.timezone_converter	dpone.runtime.support.timezone	module	transitional-shim	after internal callers migrate to runtime.support.timezone
dpone.reconciliation	dpone.runtime.reconciliation	package	deprecated-shim	after one dedicated deprecation release
dpone.sink	dpone.runtime.sinks	package	deprecated-shim	after one dedicated deprecation release
dpone.source	dpone.runtime.sources	package	deprecated-shim	after one dedicated deprecation release
dpone.sql_helpers	dpone.runtime.sql_helpers	package	deprecated-shim	after one dedicated deprecation release
dpone.state	dpone.runtime.state	package	deprecated-shim	after one dedicated deprecation release
dpone.xmin	dpone.runtime.xmin	package	deprecated-shim	after one dedicated deprecation release
dpone.yaml_config_handler	dpone.dag	package	deprecated-shim	after one dedicated deprecation release
				Legacy DAG package kept as re-export shim during migration.

Related docs

• Source -> sink matrix
• Connector certification
• Production readiness
• Release process