fix: parent state cursor fallback

[Maxime Carbonneau-Leclerc (maxi297)]

What

Addressing oncall issue https://github.com/airbytehq/oncall/issues/9163

How

Ensuring that the state migration only happens if the child state is {<cursor_field>: <cursor value>}

Summary by CodeRabbit

• Bug Fixes
  • Corrected parent stream state inference to only occur when the child state contains a single cursor. This prevents constructing invalid parent state from multi-cursor child states, reducing edge-case errors.
  • Improves reliability of incremental syncs by avoiding unintended state assumptions, leading to more predictable behavior and fewer sync interruptions.

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@maxi297/fix_fallback_for_parent_state#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch maxi297/fix_fallback_for_parent_state

Helpful Resources

• CDK API Reference

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📝 Edit this welcome message.

[coderabbitai]

📝 Walkthrough

Walkthrough

Narrowed condition in _instantiate_parent_stream_state_manager to construct a parent state only when the child state has exactly one cursor value. Added an explanatory comment about the expected child state shape. This changes the control flow by restricting when a parent state is derived from the child.

Changes

Cohort / File(s)	Summary of Changes
Declarative source parsing airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py	Updated condition to require len(cursor_values) == 1 before generating a parent state from a child state; added inline comment clarifying assumption about child state structure; adjusted control flow accordingly.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Caller
  participant ModelToComponentFactory as ModelToComponentFactory
  participant ChildState as Child Stream State
  participant ParentStateMgr as Parent State Manager

  Caller->>ModelToComponentFactory: _instantiate_parent_stream_state_manager(child_state)
  ModelToComponentFactory->>ChildState: Read cursor_values
  alt Exactly one cursor value
    Note over ModelToComponentFactory: len(cursor_values) == 1
    ModelToComponentFactory->>ParentStateMgr: Construct from single cursor value
    ModelToComponentFactory-->>Caller: Return ParentStateMgr
  else Zero or multiple cursor values
    Note over ModelToComponentFactory: Do not construct from child state
    ModelToComponentFactory-->>Caller: Return None / alternate path
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers

• brianjlai
• tolik0
• pnilan

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly conveys that the pull request fixes the fallback logic for the parent state cursor, which matches the change narrowing the fallback to when there is exactly one cursor value. It is concise, clear, and directly reflects the main update in the code while avoiding unnecessary detail or ambiguity.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch maxi297/fix_fallback_for_parent_state

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py (1)

3868-3870: LGTM! The narrowed condition and explanatory comment improve safety.

The change to only construct a parent state when len(cursor_values) == 1 is a sensible defensive improvement. By restricting the fallback to cases where the child state matches the expected simple structure ({<cursor_field>: <cursor_value>}), you avoid attempting to migrate states with unexpected shapes. The added comment clearly documents this assumption.

One optional enhancement: When len(cursor_values) != 1, the code silently returns an empty ConnectorStateManager. Would it be helpful to log a debug message in cases where cursor_values exists but has more than one value? This could aid troubleshooting if users encounter unexpected state migration behavior, wdyt?

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 035264c and 718da45.

📒 Files selected for processing (1)

• airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)

• GitHub Check: Check: source-hardcoded-records
• GitHub Check: Check: source-intercom
• GitHub Check: Check: source-pokeapi
• GitHub Check: Check: source-shopify
• GitHub Check: Check: destination-motherduck
• GitHub Check: Pytest (All, Python 3.13, Ubuntu)
• GitHub Check: Pytest (All, Python 3.10, Ubuntu)
• GitHub Check: Pytest (All, Python 3.12, Ubuntu)
• GitHub Check: Pytest (All, Python 3.11, Ubuntu)
• GitHub Check: SDM Docker Image Build
• GitHub Check: Manifest Server Docker Image Build
• GitHub Check: Pytest (Fast)

[github-actions]

PyTest Results (Fast)

3 797 tests  ±0   3 785 ✅ ±0   6m 31s ⏱️ -1s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 718da45. ± Comparison against base commit 035264c.

[github-actions]

PyTest Results (Full)

3 800 tests  ±0   3 788 ✅ ±0   11m 2s ⏱️ +3s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 718da45. ± Comparison against base commit 035264c.