sqlbuild 0.72.0__tar.gz → 0.72.2__tar.gz

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/Cargo.lock

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

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/PKG-INFO

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

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/crates/sqlbuild-kata-native/Cargo.toml

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

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/pyproject.toml

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

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/cli/output/_helpers/execution_protocol_v1.py

@@ -8,6 +8,7 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import cast
 
+from sqlbuild.cli.output._helpers.future_cursor_safety import serialize_future_cursor_safety
 from sqlbuild.compiler.auditing.types import AuditOutcome
 from sqlbuild.compiler.compile.types import CompiledResourceType
 from sqlbuild.compiler.planner.models import (
@@ -498,6 +499,7 @@ def _format_model_assets(
                 "error_help": result.error_help,
                 "error_message": result.error_message,
                 "warnings": result.warning_messages,
+                "future_cursor_safety": serialize_future_cursor_safety(result.future_cursor_safety),
                 "microbatch": _format_microbatch_result(result),
             }
         )

sqlbuild-0.72.2/src/sqlbuild/cli/output/_helpers/future_cursor_safety.py

@@ -0,0 +1,50 @@
+"""Structured future-cursor safety output."""
+
+from __future__ import annotations
+
+from sqlbuild.compiler.planner.models import FutureCursorSafetyEvidence
+
+
+def serialize_future_cursor_safety(
+    evidence: FutureCursorSafetyEvidence | None,
+) -> dict[str, object] | None:
+    """Serialize cap policy, bounds, and physical input evidence."""
+
+    if evidence is None:
+        return None
+    return {
+        "action": evidence.action.value,
+        "max_distance": evidence.max_distance,
+        "invocation_time": evidence.invocation_time,
+        "discovered_bounds": {
+            "start": evidence.discovered_start,
+            "end": evidence.discovered_end,
+        },
+        "applied_bounds": {
+            "start": evidence.applied_start,
+            "end": evidence.applied_end,
+        },
+        "maximum_allowed_bounds": {
+            "start": evidence.maximum_allowed_start,
+            "end": evidence.maximum_allowed_end,
+        },
+        "future_start_detected": evidence.future_start_detected,
+        "future_end_detected": evidence.future_end_detected,
+        "determining_input": (
+            {
+                "relation": evidence.determining_relation,
+                "cursor_column": evidence.determining_cursor_column,
+            }
+            if evidence.determining_relation is not None
+            else None
+        ),
+        "inputs": [
+            {
+                "relation": item.relation,
+                "cursor_column": item.cursor_column,
+                "minimum": item.minimum,
+                "maximum": item.maximum,
+            }
+            for item in evidence.inputs
+        ],
+    }

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/cli/output/_helpers/plan_json.py

@@ -7,11 +7,13 @@ import json
 from typing import cast
 
 from sqlbuild.cli.output._helpers.cursor_plan import build_cursor_plan_details
+from sqlbuild.cli.output._helpers.future_cursor_safety import serialize_future_cursor_safety
 from sqlbuild.cli.output.models import CursorPlanDetails
 from sqlbuild.compiler.pipeline.models import PythonPlanEntry
 from sqlbuild.compiler.planner.models import (
     CascadeResult,
     FunctionPlanEntry,
+    FutureCursorSafetyEvidence,
     ModelPlanEntry,
     PlanOutput,
     PlanProviderUsage,
@@ -136,6 +138,16 @@ def _serialize_model_entry(entry: ModelPlanEntry) -> dict[str, object]:
             "start": entry.cursor_bounds.start,
             "end": entry.cursor_bounds.end,
         }
+    future_safety: FutureCursorSafetyEvidence | None = (
+        entry.microbatch_range.future_safety
+        if entry.microbatch_range is not None and entry.microbatch_range.future_safety is not None
+        else (entry.cursor_bounds.future_safety if entry.cursor_bounds is not None else None)
+    )
+    serialized_future_safety: dict[str, object] | None = serialize_future_cursor_safety(
+        future_safety
+    )
+    if serialized_future_safety is not None:
+        model["future_cursor_safety"] = serialized_future_safety
     cursor_details: CursorPlanDetails | None = build_cursor_plan_details(entry=entry)
     if cursor_details is not None:
         model["cursor"] = _serialize_cursor_details(details=cursor_details)

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/compiler/discovery/_helpers/yml/project.py

@@ -37,8 +37,10 @@ from sqlbuild.spec.contracts.models import (
     ClonePolicy,
     ConstantsConfig,
     CostConfig,
+    CursorsConfig,
     DbtConfig,
     DefaultsConfig,
+    FutureCursorsConfig,
     JanitorConfig,
     LocalClonePolicy,
     LocalConfig,
@@ -57,6 +59,7 @@ from sqlbuild.spec.contracts.models import (
     TargetConfig,
 )
 from sqlbuild.spec.contracts.types import (
+    FutureCursorAction,
     TableType,
     TableTypeDowngradePolicy,
     TableTypeValue,
@@ -75,6 +78,9 @@ _DEFAULT_HISTORICAL_SNAPSHOT_FULL_REFRESH: str = "require_confirmation"
 _DEFAULT_SNAPSHOT_SCHEMA_CHANGE: str = "append_new_columns"
 _DEFAULT_WILDCARD_CHECK_SNAPSHOT_SCHEMA_CHANGE: str = "require_confirmation"
 _BATCH_CONCURRENCY_CONFIG_KEY: str = "batch_concurrency"
+_CURSOR_DURATION_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?=.*[1-9])(?:(\d+)y)?(?:(\d+)mo)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$"
+)
 
 
 def load_project_config(*, project_dir: Path) -> ProjectConfig:
@@ -96,6 +102,7 @@ def load_project_config(*, project_dir: Path) -> ProjectConfig:
     constants: ConstantsConfig = _load_constants(
         payload=payload.get("constants"), file_path=file_path
     )
+    cursors: CursorsConfig = _load_cursors(payload=payload.get("cursors"), file_path=file_path)
     defaults: DefaultsConfig = _load_defaults(payload=payload.get("defaults"), file_path=file_path)
     materialization_defaults: MaterializationDefaultsConfig = _load_materialization_defaults(
         payload=payload.get("materialization_defaults"), file_path=file_path
@@ -133,6 +140,7 @@ def load_project_config(*, project_dir: Path) -> ProjectConfig:
         scopes=scopes,
         cost=cost,
         constants=constants,
+        cursors=cursors,
         defaults=defaults,
         materialization_defaults=materialization_defaults,
         path_defaults=path_defaults,
@@ -353,6 +361,38 @@ def _load_settings(*, payload: object, file_path: Path) -> SettingsConfig:
     )
 
 
+def _load_cursors(*, payload: object, file_path: Path) -> CursorsConfig:
+    mapping: dict[str, object] = _coerce_mapping(
+        payload=payload, label="cursors", file_path=file_path
+    )
+    _validate_allowed_keys(
+        mapping=mapping,
+        allowed_keys=frozenset({"future"}),
+        label="cursors",
+        file_path=file_path,
+    )
+    future: dict[str, object] = _coerce_mapping(
+        payload=mapping.get("future"), label="cursors.future", file_path=file_path
+    )
+    _validate_allowed_keys(
+        mapping=future,
+        allowed_keys=frozenset({"max_distance", "action"}),
+        label="cursors.future",
+        file_path=file_path,
+    )
+    max_distance: str | None = _optional_str(payload=future, key="max_distance")
+    if max_distance is not None and _CURSOR_DURATION_PATTERN.fullmatch(max_distance) is None:
+        raise ProjectConfigError(
+            "cursors.future.max_distance must be a positive duration like 7d, 12h, or 1mo"
+        )
+    raw_action: str | None = _optional_str(payload=future, key="action")
+    try:
+        action: FutureCursorAction = FutureCursorAction(raw_action or FutureCursorAction.ERROR)
+    except ValueError:
+        raise ProjectConfigError("cursors.future.action must be one of: cap, error") from None
+    return CursorsConfig(future=FutureCursorsConfig(max_distance=max_distance, action=action))
+
+
 def _load_scopes(*, payload: object, file_path: Path) -> ScopesConfig:
     mapping: dict[str, object] = _coerce_mapping(
         payload=payload, label="scopes", file_path=file_path

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/compiler/planner/_helpers/output/plan_entry.py

@@ -55,10 +55,13 @@ from sqlbuild.compiler.planner.constants import (
 )
 from sqlbuild.compiler.planner.exceptions import PlannerInputError
 from sqlbuild.compiler.planner.main.changes._model_changes import detect_model_changes
+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.models import (
     BackfillResult,
     ChangeDetectionResult,
     CursorBounds,
+    CursorInputEvidence,
     CursorInputRelation,
     CursorOverridePair,
     CursorOverrides,
@@ -92,7 +95,13 @@ from sqlbuild.compiler.planner.types import (
 )
 from sqlbuild.compiler.references.main._render_source_relation import render_source_relation
 from sqlbuild.compiler.references.types import ExternalSqlReferenceResolver, SqlReferenceKind
-from sqlbuild.spec.contracts.models import LocalConfig, ProjectConfig, SchemaColumn, SourceEntry
+from sqlbuild.spec.contracts.models import (
+    FutureCursorsConfig,
+    LocalConfig,
+    ProjectConfig,
+    SchemaColumn,
+    SourceEntry,
+)
 from sqlbuild.spec.contracts.types import TableType
 
 _MODELS_DIR_PREFIX: str = "models/"
@@ -290,6 +299,8 @@ def build_plan_entries(
                 source_warehouse_columns=relations.source_warehouse_columns,
                 star_exclude_keyword=relations.star_exclude_keyword,
                 runtime_cursor_producer_names=runtime_cursor_producer_names,
+                future_cursor_config=inputs.future_cursor_config,
+                invocation_time=inputs.invocation_time,
             ),
             sql_analysis_enabled=project.settings.sql_analysis,
             full_refresh=effective_full_refresh,
@@ -391,7 +402,6 @@ def plan_model_from_change(
     if backfill_override is not None:
         change_result = replace(change_result, backfill=backfill_override)
 
-    models_by_name: dict[str, CompiledModel] = context.models_by_name
     start_cursor_override: str | None = cursor_overrides.start_cursor_override
     end_cursor_override: str | None = cursor_overrides.end_cursor_override
     backfill: BackfillResult = (
@@ -404,7 +414,7 @@ def plan_model_from_change(
     validate_source_cursor_input_columns(
         model=model,
         cursor_column=cursor_column,
-        models_by_name=models_by_name,
+        models_by_name=context.models_by_name,
         source_map=context.source_map,
         source_warehouse_columns=context.source_warehouse_columns,
     )
@@ -464,7 +474,7 @@ def plan_model_from_change(
             model=model,
             adapter=adapter,
             model_locations=context.model_locations,
-            models_by_name=models_by_name,
+            models_by_name=context.models_by_name,
             seed_locations=context.seed_locations,
             source_map=context.source_map,
             cursor_column=cursor_column,
@@ -481,6 +491,8 @@ def plan_model_from_change(
         start_cursor_override=start_cursor_override,
         end_cursor_override=end_cursor_override,
         runtime_owned_cursor_bounds=runtime_owned_cursor_bounds,
+        future_cursor_config=context.future_cursor_config,
+        invocation_time=context.invocation_time,
     )
 
     cursor_type_warning: PlanWarning | None = check_cursor_type_consistency(
@@ -516,6 +528,14 @@ def plan_model_from_change(
         end_cursor_override=end_cursor_override,
         runtime_owned_cursor_bounds=runtime_owned_cursor_bounds,
         cursor_input_relations=cursor_input_relations,
+        future_cursor_config=context.future_cursor_config,
+        invocation_time=context.invocation_time,
+    )
+
+    warnings = _append_future_cap_warning(
+        warnings=warnings,
+        model_name=model.name,
+        bounds=microbatch_range or cursor_bounds,
     )
 
     fingerprint: Fingerprint | None = snapshot.fingerprints.models.get(model.name)
@@ -591,6 +611,8 @@ def plan_model_from_change(
         microbatch_range=microbatch_range,
         start_cursor_override=start_cursor_override,
         end_cursor_override=end_cursor_override,
+        future_cursor_config=context.future_cursor_config,
+        invocation_time=context.invocation_time,
         unique_key=unique_key,
         merge_exclude_columns=_get_config_string_tuple(model=model, key="merge_exclude_columns"),
         snapshot_strategy=snapshot_strategy,
@@ -860,6 +882,8 @@ def _compute_microbatch_range(
     end_cursor_override: str | None,
     runtime_owned_cursor_bounds: bool,
     cursor_input_relations: tuple[CursorInputRelation, ...],
+    future_cursor_config: FutureCursorsConfig | None = None,
+    invocation_time: datetime | None = None,
 ) -> CursorBounds | None:
     """Compute the real overall cursor range for microbatch batch splitting."""
 
@@ -906,7 +930,7 @@ def _compute_microbatch_range(
     if backfill.action == BackfillAction.BOUNDED:
         backfill_duration = backfill.duration
 
-    return compute_cursor_bounds(
+    bounds: CursorBounds | None = compute_cursor_bounds(
         cursor_snapshot=cursor_snapshot,
         cursor_type=cursor_type,
         cursor_start=cursor_start,
@@ -917,6 +941,16 @@ def _compute_microbatch_range(
         cursor_grain=effective_grain,
         is_microbatch=False,
     )
+    return _apply_future_safety(
+        bounds=bounds,
+        cursor_type=cursor_type,
+        cursor_grain=effective_grain,
+        start_cursor_override=start_cursor_override,
+        end_cursor_override=end_cursor_override,
+        future_cursor_config=future_cursor_config,
+        invocation_time=invocation_time,
+        input_evidence=cursor_snapshot.input_evidence,
+    )
 
 
 def resolve_microbatch_lookback(model: CompiledModel) -> str | None:
@@ -943,6 +977,8 @@ def _compute_plan_cursor_bounds(
     start_cursor_override: str | None,
     end_cursor_override: str | None,
     runtime_owned_cursor_bounds: bool,
+    future_cursor_config: FutureCursorsConfig | None = None,
+    invocation_time: datetime | None = None,
 ) -> CursorBounds | None:
     """Compute cursor bounds for inclusion on the plan entry."""
 
@@ -976,16 +1012,73 @@ def _compute_plan_cursor_bounds(
     if backfill.action == BackfillAction.BOUNDED:
         backfill_duration = backfill.duration
 
-    return compute_cursor_bounds(
+    cursor_type: str | None = _get_config_str(model=model, key="cursor_type")
+    cursor_grain: str | None = _get_config_str(model=model, key="cursor_grain")
+    bounds: CursorBounds | None = compute_cursor_bounds(
         cursor_snapshot=cursor_snapshot,
-        cursor_type=_get_config_str(model=model, key="cursor_type"),
+        cursor_type=cursor_type,
         cursor_start=cursor_start,
         lookback=lookback,
         backfill_duration=backfill_duration,
         start_cursor_override=start_cursor_override,
         end_cursor_override=end_cursor_override,
         is_microbatch=is_microbatch,
-        cursor_grain=_get_config_str(model=model, key="cursor_grain"),
+        cursor_grain=cursor_grain,
+    )
+    return _apply_future_safety(
+        bounds=bounds,
+        cursor_type=cursor_type,
+        cursor_grain=cursor_grain,
+        start_cursor_override=start_cursor_override,
+        end_cursor_override=end_cursor_override,
+        future_cursor_config=future_cursor_config,
+        invocation_time=invocation_time,
+        input_evidence=cursor_snapshot.input_evidence,
+    )
+
+
+def _apply_future_safety(
+    *,
+    bounds: CursorBounds | None,
+    cursor_type: str | None,
+    cursor_grain: str | None,
+    start_cursor_override: str | None,
+    end_cursor_override: str | None,
+    future_cursor_config: FutureCursorsConfig | None,
+    invocation_time: datetime | None,
+    input_evidence: tuple[CursorInputEvidence, ...],
+) -> CursorBounds | None:
+    if bounds is None:
+        return None
+    if bounds.end == MICROBATCH_END_SENTINEL:
+        return bounds
+    return apply_future_cursor_safety(
+        bounds=bounds,
+        cursor_type=cursor_type,
+        cursor_grain=cursor_grain,
+        config=future_cursor_config,
+        invocation_time=invocation_time,
+        has_complete_override=(
+            start_cursor_override is not None and end_cursor_override is not None
+        ),
+        input_evidence=input_evidence,
+    )
+
+
+def _append_future_cap_warning(
+    *, warnings: tuple[PlanWarning, ...], model_name: str, bounds: CursorBounds | None
+) -> tuple[PlanWarning, ...]:
+    message: str | None = future_cursor_cap_warning(bounds)
+    if message is None:
+        return warnings
+    return (
+        *warnings,
+        PlanWarning(
+            model_name=model_name,
+            severity=WarningSeverity.WARNING,
+            code="FUTURE_CURSOR_CAPPED",
+            message=message,
+        ),
     )
 
 

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/compiler/planner/_helpers/planning/entries.py

@@ -64,6 +64,12 @@ def build_planner_entry_results(
                 else frozenset()
             ),
             external_blocked_model_names=frozenset(overrides.external_blocked_model_names),
+            future_cursor_config=(
+                runtime.project_config.cursors.future
+                if runtime.project_config is not None
+                else None
+            ),
+            invocation_time=runtime.invocation_time,
         ),
     )
     return PlannerEntryResults(

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/compiler/planner/_helpers/planning/warehouse_state.py

@@ -10,6 +10,7 @@ from sqlbuild.compiler.planner._helpers.planning.full_refresh import (
 )
 from sqlbuild.compiler.planner._helpers.warehouse.snapshot import gather_warehouse_snapshot
 from sqlbuild.compiler.planner.models import (
+    CursorSnapshotScope,
     DeferralInputs,
     PlannerOverrides,
     PlannerRelationsContext,
@@ -44,7 +45,10 @@ def gather_planner_warehouse_state(
         ),
         on_progress=runtime.on_progress,
         deferred_locations=deferral.deferred_locations,
-        runtime_producer_keys=scopes.selected_scope.selected_keys,
+        cursor_scope=CursorSnapshotScope(
+            model_keys=scopes.selected_scope.selected_keys,
+            runtime_producer_keys=scopes.selected_scope.selected_keys,
+        ),
     )
     inspection_relations: PlannerRelationsContext = build_planner_relations_context(
         project=runtime.project,

{sqlbuild-0.72.0 → sqlbuild-0.72.2}/src/sqlbuild/compiler/planner/_helpers/resolve/cursor.py

@@ -121,6 +121,7 @@ def normalize_cursor_snapshot_grain(
             _floor_timestamp_string(value=value, grain=effective_grain)
             for value in cursor_snapshot.upstream_maxes
         ),
+        input_evidence=cursor_snapshot.input_evidence,
         expected_watermark_count=cursor_snapshot.expected_watermark_count,
         unavailable_watermark_tags=cursor_snapshot.unavailable_watermark_tags,
     )

sqlbuild-0.72.2/src/sqlbuild/compiler/planner/_helpers/resolve/future_cursor_safety.py

@@ -0,0 +1,190 @@
+"""Future cursor safety calculation."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, date, datetime, time, timedelta
+
+from sqlbuild.compiler.planner.exceptions import FutureCursorSafetyError
+from sqlbuild.compiler.planner.models import (
+    CursorBounds,
+    CursorInputEvidence,
+    Duration,
+    FutureCursorSafetyEvidence,
+)
+from sqlbuild.compiler.planner.types import CursorGrain, CursorType
+from sqlbuild.spec.contracts.models import FutureCursorsConfig
+from sqlbuild.spec.contracts.types import FutureCursorAction
+
+
+def resolve_future_cursor_safety(
+    *,
+    bounds: CursorBounds,
+    cursor_type: str | None,
+    cursor_grain: str | None,
+    config: FutureCursorsConfig | None,
+    invocation_time: datetime | None,
+    has_complete_override: bool,
+    input_evidence: tuple[CursorInputEvidence, ...] = (),
+) -> CursorBounds:
+    """Apply future cursor policy to effective timestamp bounds."""
+
+    if (
+        config is None
+        or config.max_distance is None
+        or cursor_type != CursorType.TIMESTAMP
+        or invocation_time is None
+        or has_complete_override
+    ):
+        return bounds
+    duration: Duration | None = Duration.parse(config.max_distance)
+    if duration is None:
+        raise FutureCursorSafetyError(
+            f"invalid cursors.future.max_distance '{config.max_distance}'"
+        )
+    allowed_start, allowed_end = _allowed_bounds(
+        discovered_end=bounds.end,
+        cursor_grain=cursor_grain,
+        invocation_time=invocation_time,
+        duration=duration,
+    )
+    future_start_detected: bool = _comparison_key(bounds.start) > _comparison_key(allowed_start)
+    future_end_detected: bool = _comparison_key(bounds.end) > _comparison_key(allowed_end)
+    if not future_start_detected and not future_end_detected:
+        return bounds
+    determining: CursorInputEvidence | None = _determining_input(input_evidence)
+    if config.action == FutureCursorAction.ERROR:
+        raise FutureCursorSafetyError(
+            _error_message(
+                bounds=bounds,
+                allowed_start=allowed_start,
+                allowed_end=allowed_end,
+                max_distance=config.max_distance,
+            )
+        )
+    applied_end: str = allowed_end if future_end_detected else bounds.end
+    return replace(
+        bounds,
+        end=applied_end,
+        future_safety=FutureCursorSafetyEvidence(
+            action=config.action,
+            max_distance=config.max_distance,
+            invocation_time=invocation_time.astimezone(UTC).isoformat(),
+            discovered_start=bounds.start,
+            discovered_end=bounds.end,
+            applied_start=bounds.start,
+            applied_end=applied_end,
+            maximum_allowed_start=allowed_start,
+            maximum_allowed_end=allowed_end,
+            future_start_detected=future_start_detected,
+            future_end_detected=future_end_detected,
+            determining_relation=determining.relation if determining is not None else None,
+            determining_cursor_column=(
+                determining.cursor_column if determining is not None else None
+            ),
+            inputs=input_evidence,
+        ),
+    )
+
+
+def _allowed_bounds(
+    *,
+    discovered_end: str,
+    cursor_grain: str | None,
+    invocation_time: datetime,
+    duration: Duration,
+) -> tuple[str, str]:
+    clock: datetime = invocation_time.astimezone(UTC).replace(tzinfo=None)
+    maximum: datetime = duration.add_to(clock)
+    plain_date: date | None = _plain_date(discovered_end)
+    if plain_date is not None:
+        allowed_date: date = _floor_date(value=maximum.date(), cursor_grain=cursor_grain)
+        return allowed_date.isoformat(), _advance_date(
+            value=allowed_date, cursor_grain=cursor_grain
+        ).isoformat()
+    allowed_timestamp: datetime = _floor_timestamp(value=maximum, cursor_grain=cursor_grain)
+    if datetime.fromisoformat(discovered_end).tzinfo is not None:
+        allowed_timestamp = allowed_timestamp.replace(tzinfo=UTC)
+    return (
+        allowed_timestamp.isoformat(),
+        _advance_timestamp(value=allowed_timestamp, cursor_grain=cursor_grain).isoformat(),
+    )
+
+
+def _floor_date(*, value: date, cursor_grain: str | None) -> date:
+    if cursor_grain == CursorGrain.MONTH:
+        return value.replace(day=1)
+    if cursor_grain == CursorGrain.YEAR:
+        return value.replace(month=1, day=1)
+    return value
+
+
+def _advance_date(*, value: date, cursor_grain: str | None) -> date:
+    moment: datetime = datetime.combine(value, time.min)
+    if cursor_grain == CursorGrain.MONTH:
+        return Duration(months=1).add_to(moment).date()
+    if cursor_grain == CursorGrain.YEAR:
+        return Duration(years=1).add_to(moment).date()
+    return value + timedelta(days=1)
+
+
+def _floor_timestamp(*, value: datetime, cursor_grain: str | None) -> datetime:
+    if cursor_grain == CursorGrain.YEAR:
+        return value.replace(month=1, day=1, hour=0, minute=0, second=0, microsecond=0)
+    if cursor_grain == CursorGrain.MONTH:
+        return value.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    if cursor_grain == CursorGrain.DAY:
+        return value.replace(hour=0, minute=0, second=0, microsecond=0)
+    if cursor_grain == CursorGrain.HOUR:
+        return value.replace(minute=0, second=0, microsecond=0)
+    if cursor_grain == CursorGrain.MINUTE:
+        return value.replace(second=0, microsecond=0)
+    return value.replace(microsecond=0)
+
+
+def _advance_timestamp(*, value: datetime, cursor_grain: str | None) -> datetime:
+    if cursor_grain == CursorGrain.YEAR:
+        return Duration(years=1).add_to(value)
+    if cursor_grain == CursorGrain.MONTH:
+        return Duration(months=1).add_to(value)
+    if cursor_grain == CursorGrain.DAY:
+        return value + timedelta(days=1)
+    if cursor_grain == CursorGrain.HOUR:
+        return value + timedelta(hours=1)
+    if cursor_grain == CursorGrain.MINUTE:
+        return value + timedelta(minutes=1)
+    return value + timedelta(seconds=1)
+
+
+def _comparison_key(value: str) -> datetime:
+    plain_date: date | None = _plain_date(value)
+    if plain_date is not None:
+        return datetime.combine(plain_date, time.min)
+    parsed: datetime = datetime.fromisoformat(value)
+    return parsed.astimezone(UTC).replace(tzinfo=None) if parsed.tzinfo is not None else parsed
+
+
+def _plain_date(value: str) -> date | None:
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _determining_input(
+    evidence: tuple[CursorInputEvidence, ...],
+) -> CursorInputEvidence | None:
+    if not evidence:
+        return None
+    return min(evidence, key=lambda item: _comparison_key(item.maximum))
+
+
+def _error_message(
+    *, bounds: CursorBounds, allowed_start: str, allowed_end: str, max_distance: str
+) -> str:
+    return (
+        "future cursor safety limit exceeded: effective bounds "
+        f"['{bounds.start}', '{bounds.end}') exceed maximum allowed bounds "
+        f"['{allowed_start}', '{allowed_end}') "
+        f"(cursors.future.max_distance={max_distance})"
+    )