sqlbuild 0.79.0__tar.gz → 0.80.0__tar.gz

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/Cargo.lock

@@ -572,7 +572,7 @@ checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "sqlbuild-kata-native"
-version = "0.79.0"
+version = "0.80.0"
 dependencies = [
  "fensu-policy",
  "globset",

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.79.0
+Version: 0.80.0
 Requires-Dist: duckdb>=1.3.2
 Requires-Dist: filelock>=3.20.3
 Requires-Dist: polyglot-sql>=0.9.2

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/crates/sqlbuild-kata-native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlbuild-kata-native"
-version = "0.79.0"
+version = "0.80.0"
 edition.workspace = true
 license.workspace = true
 publish.workspace = true

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlbuild"
-version = "0.79.0"
+version = "0.80.0"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/compile/_helpers/config/model_validation.py

@@ -9,6 +9,8 @@ from decimal import Decimal, InvalidOperation
 from typing import cast
 
 from sqlbuild.compiler.compile.constants import (
+    MICROBATCH_LIMIT_ACTION_KEY,
+    MICROBATCH_LIMIT_MAX_BATCHES_KEY,
     SQL_WILDCARD_TOKEN,
     WATERMARK_CURSOR_INPUT_BLOCK_KEYS,
 )
@@ -41,7 +43,7 @@ from sqlbuild.spec.contracts.models import (
     SchemaColumn,
     SettingsConfig,
 )
-from sqlbuild.spec.contracts.types import FutureCursorAction
+from sqlbuild.spec.contracts.types import FutureCursorAction, MicrobatchLimitAction
 
 _VALID_STRATEGIES: frozenset[str] = frozenset(s.value for s in IncrementalStrategy)
 _VALID_CURSOR_TYPES: frozenset[str] = frozenset(ct.value for ct in CursorType)
@@ -90,6 +92,7 @@ _SNAPSHOT_DISALLOWED_KEYS: tuple[str, ...] = (
     "microbatch_strategy",
     "cursor_watermark_mode",
     "max_microbatches",
+    "microbatch_limit",
     "lookback",
 )
 _CUSTOM_MATERIALIZATION_DISALLOWED_KEYS: tuple[str, ...] = (
@@ -108,6 +111,7 @@ _CUSTOM_MATERIALIZATION_DISALLOWED_KEYS: tuple[str, ...] = (
     "microbatch_strategy",
     "cursor_watermark_mode",
     "max_microbatches",
+    "microbatch_limit",
     "lookback",
 )
 
@@ -136,6 +140,7 @@ class _IncrementalConfigValues:
     microbatch_strategy: str | None
     cursor_watermark_mode: str | None
     max_microbatches: object | None
+    microbatch_limit: object | None
     cursor_grain: str | None
     replay_on_change: object | None
     merge_exclude_columns: object | None
@@ -262,10 +267,16 @@ def _validate_incremental_batching(
         known_input_names=known_input_names,
         inputs=_CursorInputValidation(values=values, ref_count=ref_count),
     )
-    if isinstance(values.max_microbatches, int) and not isinstance(values.max_microbatches, bool):
+    resolved_limit: int | None = _validate_model_microbatch_limit(
+        model_name=model_name,
+        max_microbatches=values.max_microbatches,
+        microbatch_limit=values.microbatch_limit,
+        microbatch_strategy=values.microbatch_strategy,
+    )
+    if resolved_limit is not None:
         _validate_static_watermark_limit(
             model_name=model_name,
-            max_microbatches=values.max_microbatches,
+            max_microbatches=resolved_limit,
             lookback=values.lookback,
             batch_size=values.batch_size,
         )
@@ -371,6 +382,7 @@ def _resolve_incremental_config_values(*, config: CompileModelConfig) -> _Increm
         microbatch_strategy=_str(config=config, key="microbatch_strategy"),
         cursor_watermark_mode=_str(config=config, key="cursor_watermark_mode"),
         max_microbatches=config.values.get("max_microbatches"),
+        microbatch_limit=config.values.get("microbatch_limit"),
         cursor_grain=_str(config=config, key="cursor_grain"),
         replay_on_change=config.values.get("replay_on_change"),
         merge_exclude_columns=config.values.get("merge_exclude_columns"),
@@ -514,6 +526,51 @@ def _validate_cursor_input_config(
         )
 
 
+def _validate_model_microbatch_limit(
+    *,
+    model_name: str,
+    max_microbatches: object | None,
+    microbatch_limit: object | None,
+    microbatch_strategy: str | None,
+) -> int | None:
+    if max_microbatches is not None and microbatch_limit is not None:
+        raise CompileInputError(
+            f"model '{model_name}': use either max_microbatches or microbatch_limit, not both"
+        )
+    if microbatch_limit is None:
+        return (
+            max_microbatches
+            if isinstance(max_microbatches, int) and not isinstance(max_microbatches, bool)
+            else None
+        )
+    if not isinstance(microbatch_limit, dict) or set(microbatch_limit) != {
+        MICROBATCH_LIMIT_MAX_BATCHES_KEY,
+        MICROBATCH_LIMIT_ACTION_KEY,
+    }:
+        raise CompileInputError(
+            f"model '{model_name}': microbatch_limit requires exactly max_batches and action"
+        )
+    limit_mapping: dict[str, object] = cast(dict[str, object], microbatch_limit)
+    max_batches: object | None = limit_mapping.get(MICROBATCH_LIMIT_MAX_BATCHES_KEY)
+    action: object | None = limit_mapping.get(MICROBATCH_LIMIT_ACTION_KEY)
+    if isinstance(max_batches, bool) or not isinstance(max_batches, int) or max_batches < 1:
+        raise CompileInputError(
+            f"model '{model_name}': microbatch_limit max_batches must be a positive integer"
+        )
+    valid_actions: frozenset[str] = frozenset(item.value for item in MicrobatchLimitAction)
+    if not isinstance(action, str) or action not in valid_actions:
+        raise CompileInputError(
+            f"model '{model_name}': microbatch_limit action must be one of: "
+            + ", ".join(sorted(valid_actions))
+        )
+    if microbatch_strategy != MicrobatchStrategy.WATERMARK:
+        raise CompileInputError(
+            f"model '{model_name}': microbatch_limit is only valid with "
+            "microbatch_strategy=watermark"
+        )
+    return max_batches
+
+
 def _validate_known_cursor_inputs(
     *, model_name: str, value: object, known_input_names: frozenset[str]
 ) -> None:

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/compile/constants.py

@@ -18,6 +18,9 @@ CURSOR_INPUTS_CONFIG_KEY: str = "cursor_inputs"
 CURSOR_FILTER_INPUTS_CONFIG_KEY: str = "cursor_filter_inputs"
 CURSOR_WATERMARK_INPUTS_CONFIG_KEY: str = "cursor_watermark_inputs"
 MAX_MICROBATCHES_CONFIG_KEY: str = "max_microbatches"
+MICROBATCH_LIMIT_CONFIG_KEY: str = "microbatch_limit"
+MICROBATCH_LIMIT_MAX_BATCHES_KEY: str = "max_batches"
+MICROBATCH_LIMIT_ACTION_KEY: str = "action"
 WATERMARK_CURSOR_INPUT_BLOCK_KEYS: frozenset[str] = frozenset({"column", "roles"})
 MODEL_HEADER_METADATA_KEYS: frozenset[str] = frozenset(
     {"description", "columns", "model_schema", "audits", "enums", "constants"}

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/discovery/_helpers/yml/project.py

@@ -562,6 +562,8 @@ def _load_microbatches(*, payload: object, file_path: Path) -> MicrobatchesConfi
         action: MicrobatchLimitAction = MicrobatchLimitAction(raw_action)
     except ValueError:
         raise ProjectConfigError("microbatches.limits.action must be one of: error, warn") from None
+    if action not in {MicrobatchLimitAction.ERROR, MicrobatchLimitAction.WARN}:
+        raise ProjectConfigError("microbatches.limits.action must be one of: error, warn")
     return MicrobatchesConfig(limits=MicrobatchLimitsConfig(max_batches=max_batches, action=action))
 
 

sqlbuild-0.80.0/src/sqlbuild/compiler/planner/_helpers/output/microbatch_bounds.py

@@ -0,0 +1,62 @@
+"""Planner-private microbatch range capping."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from sqlbuild.compiler.planner.models import CursorBounds, Duration
+from sqlbuild.compiler.planner.types import CursorType
+from sqlbuild.spec.contracts.types import MicrobatchLimitAction
+
+
+def cap_microbatch_bounds(
+    *,
+    bounds: CursorBounds,
+    batch_size: str,
+    cursor_type: str,
+    max_batches: int,
+    action: MicrobatchLimitAction,
+) -> CursorBounds:
+    """Cap one concrete range to its earliest or latest batch windows."""
+
+    if action not in {
+        MicrobatchLimitAction.CAP_FROM_END,
+        MicrobatchLimitAction.CAP_FROM_START,
+    }:
+        return bounds
+    if cursor_type == CursorType.INTEGER:
+        try:
+            start: int = int(Decimal(bounds.start))
+            end: int = int(Decimal(bounds.end))
+            size: int = int(Decimal(batch_size))
+        except (InvalidOperation, ValueError, OverflowError):
+            return bounds
+        if size <= 0:
+            return bounds
+        if action == MicrobatchLimitAction.CAP_FROM_START:
+            return CursorBounds(start=bounds.start, end=str(min(end, start + size * max_batches)))
+        batch_count: int = max(0, (end - start + size - 1) // size)
+        skipped_batches: int = max(0, batch_count - max_batches)
+        return CursorBounds(start=str(start + size * skipped_batches), end=bounds.end)
+
+    if cursor_type != CursorType.TIMESTAMP:
+        return bounds
+    duration: Duration | None = Duration.parse(batch_size)
+    if duration is None:
+        return bounds
+    try:
+        start_at: datetime = datetime.fromisoformat(bounds.start)
+        end_at: datetime = datetime.fromisoformat(bounds.end)
+    except (TypeError, ValueError):
+        return bounds
+    if action == MicrobatchLimitAction.CAP_FROM_START:
+        capped_end: datetime = start_at
+        for _ in range(max_batches):
+            capped_end = min(duration.add_to(capped_end), end_at)
+        return CursorBounds(start=bounds.start, end=capped_end.isoformat())
+    boundaries: list[datetime] = [start_at]
+    while boundaries[-1] < end_at:
+        boundaries.append(min(duration.add_to(boundaries[-1]), end_at))
+    capped_start: datetime = boundaries[max(0, len(boundaries) - 1 - max_batches)]
+    return CursorBounds(start=capped_start.isoformat(), end=bounds.end)

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/planner/_helpers/output/plan_entry.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass, replace
 from datetime import UTC, date, datetime
 from decimal import Decimal
-from typing import Any
+from typing import Any, cast
 
 from sqlbuild.adapter.contract.classes.base_adapter import BaseAdapter
 from sqlbuild.adapter.contract.models import ColumnInfo, RelationInfo
@@ -31,6 +31,7 @@ from sqlbuild.compiler.planner._helpers.output.cursor_type_check import (
 from sqlbuild.compiler.planner._helpers.output.inclusive_cursor_end import (
     resolve_bounded_cursor_override,
 )
+from sqlbuild.compiler.planner._helpers.output.microbatch_bounds import cap_microbatch_bounds
 from sqlbuild.compiler.planner._helpers.output.microbatch_count import count_microbatches
 from sqlbuild.compiler.planner._helpers.output.strategy import (
     build_model_warnings,
@@ -70,9 +71,7 @@ from sqlbuild.compiler.planner.main.execution.effective_microbatch_batch_size im
 from sqlbuild.compiler.planner.main.execution.future_cursor_safety import apply_future_cursor_safety
 from sqlbuild.compiler.planner.main.execution.future_cursor_warning import future_cursor_cap_warning
 from sqlbuild.compiler.planner.main.execution.maximum_start_warning import maximum_start_cap_warning
-from sqlbuild.compiler.planner.main.execution.microbatch_limit import (
-    microbatch_limit_warning,
-)
+from sqlbuild.compiler.planner.main.execution.microbatch_limit import microbatch_limit_warning
 from sqlbuild.compiler.planner.models import (
     BackfillResult,
     ChangeDetectionResult,
@@ -415,24 +414,10 @@ def build_plan_entries(
                 ),
             )
             if entry.action != PlanAction.SKIP:
-                entry, limit_warning = _apply_microbatch_limit(
-                    entry=entry,
-                    max_batches=(
-                        inputs.max_microbatches
-                        if inputs.max_microbatches_is_override
-                        else (
-                            None
-                            if entry.microbatch_strategy == MicrobatchStrategy.ROLLING_WINDOW
-                            and entry.reason != PlanReason.FULL_REFRESH
-                            and entry.start_cursor_override is None
-                            and entry.end_cursor_override is None
-                            else entry.microbatch_limit or inputs.max_microbatches
-                        )
-                    ),
-                    action=inputs.microbatch_limit_action,
+                entry, limit_warnings = _apply_configured_microbatch_limits(
+                    entry=entry, inputs=inputs
                 )
-                if limit_warning is not None:
-                    warnings.append(limit_warning)
+                warnings.extend(limit_warnings)
         entries.append(entry)
         warnings.extend(entry_warnings)
     configured_concurrent_entries: tuple[ModelPlanEntry, ...] = tuple(
@@ -477,12 +462,67 @@ def build_plan_entries(
     return PlannerModelEntryResults(entries=tuple(entries), warnings=tuple(warnings))
 
 
+def _apply_configured_microbatch_limits(
+    *, entry: ModelPlanEntry, inputs: PlanEntryBuildInputs
+) -> tuple[ModelPlanEntry, tuple[PlanWarning, ...]]:
+    """Apply CLI, project, and model policies in their documented precedence order."""
+
+    if inputs.max_microbatches_is_override:
+        limited_entry, warning = _apply_microbatch_limit(
+            entry=entry,
+            max_batches=inputs.max_microbatches,
+            action=MicrobatchLimitAction.ERROR,
+        )
+        return limited_entry, (() if warning is None else (warning,))
+
+    if entry.declared_microbatch_limit_action is not None:
+        warnings: list[PlanWarning] = []
+        declared_action: MicrobatchLimitAction = entry.declared_microbatch_limit_action
+        if inputs.max_microbatches is not None:
+            _, safety_warning = _apply_microbatch_limit(
+                entry=entry,
+                max_batches=inputs.max_microbatches,
+                action=inputs.microbatch_limit_action,
+            )
+            entry = replace(
+                entry,
+                microbatch_safety_limit=inputs.max_microbatches,
+                microbatch_safety_limit_action=inputs.microbatch_limit_action,
+            )
+            if safety_warning is not None:
+                warnings.append(safety_warning)
+        entry, model_warning = _apply_microbatch_limit(
+            entry=entry,
+            max_batches=entry.microbatch_limit,
+            action=declared_action,
+        )
+        if model_warning is not None:
+            warnings.append(model_warning)
+        return entry, tuple(warnings)
+
+    max_batches: int | None = (
+        None
+        if entry.microbatch_strategy == MicrobatchStrategy.ROLLING_WINDOW
+        and entry.reason != PlanReason.FULL_REFRESH
+        and entry.start_cursor_override is None
+        and entry.end_cursor_override is None
+        else entry.microbatch_limit or inputs.max_microbatches
+    )
+    limited_entry, warning = _apply_microbatch_limit(
+        entry=entry,
+        max_batches=max_batches,
+        action=inputs.microbatch_limit_action,
+    )
+    return limited_entry, (() if warning is None else (warning,))
+
+
 def _apply_microbatch_limit(
     *, entry: ModelPlanEntry, max_batches: int | None, action: MicrobatchLimitAction
 ) -> tuple[ModelPlanEntry, PlanWarning | None]:
     if entry.action == PlanAction.SKIP:
         return entry, None
     batch_count: int | None = None
+    effective_batch_size: str | None = None
     if (
         entry.microbatch_range is not None
         and entry.batch_size is not None
@@ -499,7 +539,7 @@ def _apply_microbatch_limit(
                 relation.cursor_grain for relation in entry.cursor_input_relations
             ),
         )
-        effective_batch_size: str = (
+        effective_batch_size = (
             resolve_effective_microbatch_batch_size(
                 batch_size=entry.batch_size,
                 effective_grain=effective_grain,
@@ -523,8 +563,28 @@ def _apply_microbatch_limit(
             action=action,
         )
     )
+    limited_range: CursorBounds | None = entry.microbatch_range
+    if (
+        warning is not None
+        and effective_batch_size is not None
+        and entry.microbatch_range is not None
+        and max_batches is not None
+        and action
+        in {
+            MicrobatchLimitAction.CAP_FROM_END,
+            MicrobatchLimitAction.CAP_FROM_START,
+        }
+    ):
+        limited_range = cap_microbatch_bounds(
+            bounds=entry.microbatch_range,
+            batch_size=effective_batch_size,
+            cursor_type=entry.cursor_type or "",
+            max_batches=max_batches,
+            action=action,
+        )
     limited_entry: ModelPlanEntry = replace(
         entry,
+        microbatch_range=limited_range,
         microbatch_limit=max_batches,
         microbatch_limit_count=batch_count,
         microbatch_limit_action=action if max_batches is not None else None,
@@ -773,7 +833,8 @@ def plan_model_from_change(
             model=model, key="unaccounted_partition_policy"
         ),
         microbatch_range=microbatch_range,
-        microbatch_limit=_get_positive_config_int(model=model, key="max_microbatches"),
+        microbatch_limit=_get_model_microbatch_limit(model=model)[0],
+        declared_microbatch_limit_action=_get_model_microbatch_limit(model=model)[1],
         start_cursor_override=start_cursor_override,
         end_cursor_override=end_cursor_override,
         future_cursor_config=effective_future_cursor_config,
@@ -1052,6 +1113,24 @@ def _get_positive_config_int(*, model: CompiledModel, key: str) -> int | None:
     return raw if isinstance(raw, int) and not isinstance(raw, bool) and raw > 0 else None
 
 
+def _get_model_microbatch_limit(
+    *, model: CompiledModel
+) -> tuple[int | None, MicrobatchLimitAction | None]:
+    raw: object | None = model.config.values.get("microbatch_limit")
+    if isinstance(raw, dict):
+        limit_mapping: dict[str, object] = cast(dict[str, object], raw)
+        max_batches: object | None = limit_mapping.get("max_batches")
+        action: object | None = limit_mapping.get("action")
+        if (
+            isinstance(max_batches, int)
+            and not isinstance(max_batches, bool)
+            and max_batches > 0
+            and isinstance(action, str)
+        ):
+            return max_batches, MicrobatchLimitAction(action)
+    return _get_positive_config_int(model=model, key="max_microbatches"), None
+
+
 def _get_check_columns(model: CompiledModel) -> tuple[str, ...]:
     """Extract check_columns from model config as a normalized tuple."""
 

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/planner/main/execution/microbatch_limit.py

@@ -15,5 +15,16 @@ def microbatch_limit_warning(
     return (
         f"MICROBATCH LIMIT EXCEEDED: model '{model_name}' planned {batch_count} batches, "
         f"above the per-model limit of {max_batches} (action={action.value}). "
-        "Use --max-microbatches with an intentional invocation-specific value for this backfill."
+        + (
+            f"Selected {max_batches} batches and deferred {batch_count - max_batches}."
+            if action
+            in {
+                MicrobatchLimitAction.CAP_FROM_END,
+                MicrobatchLimitAction.CAP_FROM_START,
+            }
+            else (
+                "Use --max-microbatches with an intentional invocation-specific value for "
+                "this backfill."
+            )
+        )
     )

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/planner/main/identity/_version_identity_config.py

@@ -29,6 +29,7 @@ def build_version_identity_config(config_values: dict[str, object]) -> dict[str,
         "microbatch_strategy",
         "cursor_watermark_mode",
         "max_microbatches",
+        "microbatch_limit",
         "incremental_strategy",
         "merge_exclude_columns",
         "full_refresh",

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/compiler/planner/models.py

@@ -788,6 +788,9 @@ class ModelPlanEntry:
     unaccounted_partition_policy: str | None = None
     microbatch_range: CursorBounds | None = None
     microbatch_limit: int | None = None
+    declared_microbatch_limit_action: MicrobatchLimitAction | None = None
+    microbatch_safety_limit: int | None = None
+    microbatch_safety_limit_action: MicrobatchLimitAction | None = None
     microbatch_limit_count: int | None = None
     microbatch_limit_action: MicrobatchLimitAction | None = None
     microbatch_limit_warning: str | None = None

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/executor/run/_helpers/materializations/microbatch.py

@@ -400,7 +400,12 @@ def execute_microbatch_entry(
     state = _with_reconciliation_warnings(context=context, state=state, history=history_context)
     if not batch_plan.batches:
         state = replace(state, warnings=[*state.warnings, "no batches to process"])
-    context, state, limit_failure = _enforce_microbatch_limit(
+    state, safety_failure = _enforce_microbatch_safety_limit(
+        context=context, state=state, batch_plan=batch_plan
+    )
+    if safety_failure is not None:
+        return safety_failure
+    context, state, batch_plan, limit_failure = _enforce_microbatch_limit(
         context=context, state=state, batch_plan=batch_plan
     )
     if limit_failure is not None:
@@ -645,12 +650,61 @@ def _no_work_microbatch_result(
     )
 
 
+def _enforce_microbatch_safety_limit(
+    *,
+    context: ModelMaterializationContext,
+    state: MicrobatchLifecycleState,
+    batch_plan: _MicrobatchPlan,
+) -> tuple[MicrobatchLifecycleState, ModelExecutionResult | None]:
+    max_batches: int | None = context.entry.microbatch_safety_limit
+    action: MicrobatchLimitAction | None = context.entry.microbatch_safety_limit_action
+    warning: str | None = (
+        None
+        if action is None
+        else microbatch_limit_warning(
+            model_name=context.entry.name,
+            max_batches=max_batches,
+            batch_count=len(batch_plan.batches),
+            action=action,
+        )
+    )
+    if warning is None:
+        return state, None
+    if action == MicrobatchLimitAction.WARN:
+        return replace(state, warnings=[*state.warnings, warning]), None
+    safety_entry: ModelPlanEntry = replace(
+        context.entry,
+        microbatch_limit=max_batches,
+        microbatch_limit_count=len(batch_plan.batches),
+        microbatch_limit_action=action,
+        microbatch_limit_warning=warning,
+    )
+    safety_context: ModelMaterializationContext = replace(context, entry=safety_entry)
+    failure: ModelExecutionResult = build_failed_result(
+        entry=safety_entry,
+        phase=ExecutionPhase.STAGING,
+        error=warning,
+        warnings=state.warnings,
+        audit_results=state.audit_results,
+        statement_recorder=state.statement_recorder,
+    )
+    return state, replace(
+        failure,
+        microbatch_run_type=_microbatch_run_type(context=safety_context).value,
+    )
+
+
 def _enforce_microbatch_limit(
     *,
     context: ModelMaterializationContext,
     state: MicrobatchLifecycleState,
     batch_plan: _MicrobatchPlan,
-) -> tuple[ModelMaterializationContext, MicrobatchLifecycleState, ModelExecutionResult | None]:
+) -> tuple[
+    ModelMaterializationContext,
+    MicrobatchLifecycleState,
+    _MicrobatchPlan,
+    ModelExecutionResult | None,
+]:
     limit_count: int = len(batch_plan.batches)
     action: MicrobatchLimitAction | None = context.entry.microbatch_limit_action
     warning: str | None = (
@@ -663,20 +717,66 @@ def _enforce_microbatch_limit(
             action=action,
         )
     )
+    limited_plan: _MicrobatchPlan = batch_plan
+    if (
+        warning is not None
+        and context.entry.microbatch_limit is not None
+        and action
+        in {
+            MicrobatchLimitAction.CAP_FROM_END,
+            MicrobatchLimitAction.CAP_FROM_START,
+        }
+    ):
+        selected_batches: tuple[BatchWindow, ...] = (
+            batch_plan.batches[-context.entry.microbatch_limit :]
+            if action == MicrobatchLimitAction.CAP_FROM_END
+            else batch_plan.batches[: context.entry.microbatch_limit]
+        )
+        selected_batches = tuple(
+            replace(batch, index=index) for index, batch in enumerate(selected_batches)
+        )
+        selected_intervals: tuple[MicrobatchInterval, ...] = tuple(
+            MicrobatchInterval(start=batch.start, end=batch.end) for batch in selected_batches
+        )
+        limited_plan = replace(
+            batch_plan,
+            batches=selected_batches,
+            resolved_intervals=selected_intervals,
+            resolved_range=(
+                CursorBounds(start=selected_batches[0].start, end=selected_batches[-1].end)
+                if selected_batches
+                else None
+            ),
+        )
+    effective_warning: str | None = warning or context.entry.microbatch_limit_warning
+    effective_count: int = (
+        context.entry.microbatch_limit_count
+        if context.entry.microbatch_limit_count is not None
+        and context.entry.microbatch_limit_warning is not None
+        else limit_count
+    )
     limited_context: ModelMaterializationContext = replace(
         context,
         entry=replace(
             context.entry,
-            microbatch_limit_count=limit_count,
-            microbatch_limit_warning=warning,
+            microbatch_limit_count=effective_count,
+            microbatch_limit_warning=effective_warning,
         ),
     )
-    limited_context = _context_with_microbatch_range(context=limited_context, batch_plan=batch_plan)
+    limited_context = _context_with_microbatch_range(
+        context=limited_context, batch_plan=limited_plan
+    )
     if warning is None:
-        return limited_context, state, None
+        return limited_context, state, limited_plan, None
     if action == MicrobatchLimitAction.WARN:
         warned_state: MicrobatchLifecycleState = replace(state, warnings=[*state.warnings, warning])
-        return limited_context, warned_state, None
+        return limited_context, warned_state, limited_plan, None
+    if action in {
+        MicrobatchLimitAction.CAP_FROM_END,
+        MicrobatchLimitAction.CAP_FROM_START,
+    }:
+        warned_state = replace(state, warnings=[*state.warnings, warning])
+        return limited_context, warned_state, limited_plan, None
     failure: ModelExecutionResult = build_failed_result(
         entry=limited_context.entry,
         phase=ExecutionPhase.STAGING,
@@ -688,6 +788,7 @@ def _enforce_microbatch_limit(
     return (
         limited_context,
         state,
+        limited_plan,
         replace(
             failure,
             microbatch_run_type=_microbatch_run_type(context=limited_context).value,

{sqlbuild-0.79.0 → sqlbuild-0.80.0}/src/sqlbuild/spec/contracts/types.py

@@ -24,6 +24,8 @@ class FutureCursorAction(StrEnum):
 class MicrobatchLimitAction(StrEnum):
     """Response when one model plans more than the configured batch limit."""
 
+    CAP_FROM_END = "cap_from_end"
+    CAP_FROM_START = "cap_from_start"
     ERROR = "error"
     WARN = "warn"