fix(cdk): require shared staging for file transfer

[devin-ai-integration]

Summary

Resolves https://github.com/airbytehq/oncall/issues/12635:

• https://github.com/airbytehq/oncall/issues/12635

This fixes file-transfer sources emitting local /tmp/airbyte-file-transfer file references when the shared staging directory is unavailable. File-transfer code paths now require AIRBYTE_STAGING_DIRECTORY or the default /staging/files directory to exist and raise an AirbyteTracedException system error instead of silently falling back to a source-local path; non-file-transfer local usage keeps the existing /tmp/airbyte-file-transfer fallback.

The PR also updates CDK standard-test connector instantiation so legacy file-based sources that require (catalog, config, state) constructor arguments can still run generated standard tests. That addresses the source-google-drive standard-test failure surfaced by this CDK branch, where the test harness previously instantiated the connector with zero arguments.

The change is not breaking per the connector/CDK checklist because it does not change stream schemas, specs/configs, streams, primary keys, cursors, or state format. It is a patch bug fix, with a changelog entry added for CDK 6.5.3.

Review & Testing Checklist for Human

• Verify the platform/runtime mounts /staging/files for file-transfer source and destination containers in production jobs.
• Consider whether any local connector development workflows rely on file transfer without setting AIRBYTE_STAGING_DIRECTORY; those should now set the env var to an existing local staging directory.
• For end-to-end confidence, retry a file-transfer sync that previously emitted a /tmp/airbyte-file-transfer/... reference and confirm it either uses /staging/files/... or fails early with the new traced exception if the mount is absent.

Notes

Declarative-First Evaluation: This is a Python CDK core file-transfer path fix, not a declarative connector behavior change. Declarative alternatives such as filters, transformations, paginators, stream slicing, or $ref overrides cannot enforce the shared staging-directory invariant before emitting file references.

Test Coverage: Added targeted unit tests for configured, missing, invalid, and file-transfer staging-directory behavior; added a file-transfer constructor regression test; updated existing declarative file-uploader tests to use an explicit staging directory; added standard-test coverage for legacy file-based connector instantiation.

Local validation:

• poetry run pytest unit_tests/ -x -q
• poetry run pytest unit_tests/test/test_standard_tests.py -q
• poetry run ruff check .
• poetry run ruff format --check .
• poetry run mypy --config-file mypy.ini airbyte_cdk

---

Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

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@devin/1779128158-fix-file-transfer-staging-dir#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 devin/1779128158-fix-file-transfer-staging-dir

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
• /prerelease - Triggers a prerelease publish with default arguments
• /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

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[github-actions]

PyTest Results (Fast)

4 076 tests  +3 483   4 065 ✅ +3 483   7m 55s ⏱️ + 4m 24s
    1 suites ±    0      11 💤 +    1 
    1 files   ±    0       0 ❌  -     1 

Results for commit bcfbfc6. ± Comparison against base commit 19a7083.

♻️ This comment has been updated with latest results.

[github-actions]

PyTest Results (Full)

4 079 tests  +10   4 067 ✅ +10   11m 13s ⏱️ +23s
    1 suites ± 0      12 💤 ± 0 
    1 files   ± 0       0 ❌ ± 0 

Results for commit bcfbfc6. ± Comparison against base commit 19a7083.

♻️ This comment has been updated with latest results.

[devin-ai-integration]

Removed the unused import and pushed the fix.

---

Devin session

[ynnirtkciuq]

/test