[yujiyokoo]

Summary

The Python SDK spec (#1341) depends on two facts about the engine that nobody had checked. This PR checks both, with a probe for each, and records the results in languages/python/docs/gate-facts/. Both facts hold. No SDK code changes, and the normal wheel build is unchanged.

The engine is the Rust crate stack-encrypt. The engine encrypts and decrypts. The extension is the Rust code compiled into the Python package. Python calls the extension, and the extension calls the engine.

• Fact 1: the extension can read the record the engine returns after decrypting, and find each field's type. The extension needs only the engine's public API.
• Fact 2: a Ctrl-C (KeyboardInterrupt) during an engine call is raised only after the call finishes. Also, a request object (Pending) that is dropped early wipes the plaintext it contains.

Changes

• crates/core/tests/gate_frame_reader.rs: the probe for fact 1. A reader written outside the engine walks a record and records each field's type.
• crates/engine/src/lib.rs and crates/engine/Cargo.toml: the probe for fact 2. A function that blocks with Python's global interpreter lock (GIL) released, behind a new cargo feature, gate-probe. The feature is off by default, so the function is not in a normal wheel.
• tests/test_gate_keyboard_interrupt.py: sends Ctrl-C during that call. The tests skip themselves when the feature is not built.
• docs/gate-facts/frame-reader.md and docs/gate-facts/keyboard-interrupt.md: the findings, how to run each probe again, and what was not tested.
• Cargo.lock: one line, for tokio as an optional dependency of the probe feature.

Verification

All of this was run on macOS 14 (arm64) with Python 3.14.7:

• cargo test --locked -p stackencrypt-core --test gate_frame_reader: 2 passed.
• The Ctrl-C probe, built with --features gate-probe: 2 passed. Ctrl-C was sent 0.2 seconds into a 1-second call. The interrupt was raised after 1.01 seconds. As a control, the same signal interrupted a plain Python time.sleep(1.0) after 0.21 seconds.
• mise run test: 4 passed and 2 skipped. The 2 skipped tests are the probe tests, in a normal build.
• mise run test:cargo and cargo fmt --check: both pass.
• cargo clippy -D warnings, with and without the probe feature: passes.
• pnpm run test:scripts on Node 22: 83 of 83 test files pass.

Not tested:

• Linux and Windows were not run for the Ctrl-C probe.
• The Ctrl-C probe blocks on a tokio sleep, not on a real engine call.
• The wipe in fact 2 comes from reading the source. Nothing was run for it.
• CI has not run on this branch yet.

Related

Closes #1384. Refs #1341 (the spec). Stacked on #1406.

Review notes

Start with the two files in docs/gate-facts/. Each one says what was checked, how, and what was not.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: eeab4bd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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