Soft Transaction Model

Soft Transactions in Kubling define a logical execution boundary that groups multiple operations into a single, coordinated unit of work.

This model is implemented entirely at the engine level and is designed to operate across heterogeneous systems, including data sources with and without native transactional support.

Rather than assuming uniform guarantees, Kubling explicitly models execution, ordering, and finalization to preserve correctness where possible and make limitations explicit where not.

A Soft Transaction establishes:

• A consistent execution scope
• Controlled coordination of side effects
• Deterministic finalization paths

Soft Transaction Strategies

Execution behavior within a Soft Transaction is governed by the Soft Transaction Strategy, which is configured per Data Source, not globally.

Kubling supports two strategies:

• DEFER_OPERATION (default)
• IMMEDIATE_OPERATION

Because strategies are defined per data source, a single Soft Transaction may coordinate:

• Deferred execution for some data sources
• Immediate execution for others
• Native transactions for certain systems
• Compensation-based rollback for non-transactional systems

This flexibility is fundamental to Kubling’s ability to orchestrate heterogeneous environments.

Transaction Lifecycle (Logical Model)

Independently of the strategies involved, every Soft Transaction follows the same logical lifecycle:

1. Begin
2. Execution
3. Pre-Commit
4. Commit or Rollback

The phases below describe this lifecycle and identify where strategy- and data-source-specific behavior applies.

Begin

When a Soft Transaction begins:

• A transaction identifier is created
• A transaction context is established
• Data sources become participants as operations are evaluated

At this stage, no external side effects have occurred.

Execution Phase

During execution, operations are evaluated under the active transaction context.

Operation Enlistment Model

Operations are enlisted per Data Source.

For each participating data source:

• A dedicated operation group is created
• Operations targeting that data source are appended to its group
• Execution order is preserved within each group

This model allows Kubling to:

• Apply different execution strategies per data source
• Preserve deterministic ordering where required
• Coordinate systems with incompatible transactional semantics

DEFER_OPERATION

With the DEFER_OPERATION strategy:

• Operations are enlisted, not executed immediately
• The engine accumulates operations per data source
• No interaction with the underlying system occurs during execution

This behavior is identical regardless of whether the underlying data source supports native transactions.

IMMEDIATE_OPERATION

With the IMMEDIATE_OPERATION strategy:

• Operations are executed as they are evaluated
• If the underlying data source supports transactions:
  • Kubling opens a native transaction
  • The connection is retained and not returned to the pool
• If the underlying data source does not support transactions:
  • Operations are executed directly
  • Side effects become immediately visible

Pre-Commit

Before finalization, the engine enters a pre-commit phase.

During this phase:

• No new operations are admitted
• The set of participating data sources is fixed
• The final commit or rollback path is determined per data source

Pre-commit establishes a stable boundary before irreversible actions occur.

Commit (Structural Semantics)

Commit marks the point at which a Soft Transaction is finalized successfully from the engine’s perspective.

Commit behavior is evaluated per Data Source, according to its configured strategy and capabilities:

• Under DEFER_OPERATION, enlisted operations may be executed at this stage
• Under IMMEDIATE_OPERATION, commit may be purely logical

Commit does not imply uniform transactional guarantees across all systems.
Its semantic implications are described in detail in Commit, Rollback & Compensation.

Rollback (Structural Semantics)

Rollback indicates that a Soft Transaction should not be considered successful.

Rollback behavior is also evaluated per Data Source:

• Native rollback is used where supported
• Explicit compensation is used where required

Rollback does not imply that no side effects occurred.
Its semantic meaning and limitations are described in detail in Commit, Rollback & Compensation.

Transaction Boundaries and Visibility

Soft Transactions define clear coordination boundaries:

• External systems do not observe in-progress transactional intent
• The engine maintains a consistent internal view of execution state
• Finalization determines when effects become stable or are reconciled

Concurrency control and visibility within these boundaries are enforced through row-level locking and transaction-local visibility mechanisms, described in subsequent sections.