docs: add deterministic Alpha.5 Python/pytest integration recipe

[astrogilda]

Closes #121.

Add a small Python/pytest recipe that learns and checks the same actual test command with checksum-selected ExecSurface Alpha.5. The unchanged synthetic fixture produces PASS (exit 0); setting its public write_extra boolean adds a native $WORKSPACE/drift.txt write and produces REVIEW (exit 10), while the same pytest assertion still passes and the selected baseline bytes remain unchanged. The runner preserves every command, stream, verdict and failure receipt in a fresh directory.

Files are limited to examples/python-pytest/: README, tiny fixture/test, hash-pinned pytest requirements and a standard-library runner. The recipe disables pytest plugin autoload/cache/bytecode writes and selects -s to avoid random output-capture scratch names. An earlier default-capture execution returned REVIEW for eight scratch-path/inode differences; that negative result informed this disclosed deterministic fixture selection. Linux x86_64/ptrace support, baseline-versus-policy roles and the distinction from independent validation remain explicit; findings link to #118.

Validation is deliberately separated by environment:

• The retained Alpha.5 execution on source 37a8d89ec931422a37171e742a198fb4966a5152 installed the exact hash-selected pytest 8.4.2 lock under Python 3.13.15. Doctor and learn exited 0; unchanged PASS exited 0 with zero findings; deliberate-write REVIEW exited 10 with native file-open/file-write findings; both pytest commands exited 0. The baseline bytes were unchanged. Binary SHA-256: 11d1f70d3e6bd6526eff4889b90cba4a0ad95ce09d489643e7f3b703e455f646.
• That source's retained Rust 1.90.0 checks passed format, strict clippy and the full workspace suite (139 passed, 3 ignored).
• The contribution is now based on current main 02ab758de6b26e8d2afed20839a0bde76624b105. All six recipe files are byte-identical to the reviewed execution. Changes between the two upstream bases affect other example documentation; Cargo, Rust source and tests are unchanged.
• In the current restricted environment, a clean hash-selected dependency installation and formatting pass. The recipe retains a doctor refusal (exit 2: tracee did not enter the expected initial stop) and stops before learn/check. The complete Rust suite reports 103 passed, 36 failed and 3 ignored across 20 targets; the failures are native tracing-readiness tests in this environment. Fresh strict clippy cannot start because /proc/self/exe is unavailable. These are retained limitations, not fresh PASS claims.
• Python compilation, Ruff and diff checks pass. A separate Codex agent reviewed the six selected files, failure retention, deterministic command and baseline/policy behavior with no blocking findings.

Existing Rust observer, normalization, baseline and built-in policy semantics remain unchanged. A PASS is the selected observed fixture comparison. This recipe does not establish independent external security validation, authority/custody, or wider platform support.

[aetherxeg-source]

Manual technical review completed against the current ExecSurface Alpha.5 contracts. The contribution stays within examples/python-pytest/, preserves the existing observer/policy semantics, retains negative/failure evidence, checks the selected target outcome and built-in policy source, verifies the deliberate native file-write finding, and confirms the learned baseline is not rewritten during drift checks. I found no blocking code or documentation issue in the submitted patch. The remaining gate is CI: GitHub currently reports the workflow as action_required for this external contribution, so this should not be merged until the repository CI is explicitly allowed to run and completes successfully.

[aetherxeg-source]

The submitted files themselves still have no blocking review finding, but the evidence gate is now stale: this branch is 9 commits behind current main (013f26ee5d0e395e555635e5dc03f222dde07268), and those intervening commits materially changed the qualification/consumer workflows and current public-status documentation. Please sync/rebase the branch onto current main and let a fresh CI run execute against the resulting head. This is an evidence-freshness requirement, not a request to change the recipe design. Once the branch is current and CI is green, I see no remaining manual blocker in the six submitted recipe files.

[aetherxeg-source]

Maintainer triage — preserve positive/negative findings; align publication state

Thank you for the deterministic pytest PASS→REVIEW recipe and especially for recording default-capture nondeterminism instead of hiding it. There was no blocking defect in the six submitted fixture files during the last manual review, but the branch is behind current main and the public default is now ExecSurface stable v1.0.0.

Please preserve the historical Alpha.5 run receipts and binary hash. Before merge, choose one explicit scope: historical Alpha.5 research example with immutable pin and archival labeling, or current v1.0.0 user-facing recipe, which requires exact-v1 binary selection, a fresh real Linux x86_64 run proving unchanged PASS and deliberate native file-write REVIEW, and explicit target command exit success. Do not merely rename v0.1.0-alpha.5 to v1.0.0 without executing the new release.

Also sync the PR branch with current main and get CI on the exact new head. If the historical pin is retained, fix the first-run installation link so it points to the immutable Alpha.5 release rather than today's stable README start-here.

We are keeping this PR open for a verified contribution; there is no assumption that contributor work alone constitutes independent product validation.

[astrogilda]

@aetherxeg-source, thanks for reviewing the scope. I've kept it as a historical Alpha.5 example, and the README now says so. The install link points at the immutable v0.1.0-alpha.5 release, and the run receipts and binary hash are unchanged. The branch is synced with main at dd31abd, and its CI run is waiting for your approval to start.

[aetherxeg-source]

Maintainer security preflight — updated PR #128

Thank you for updating the branch and preserving the historical Alpha.5 boundary. I rechecked the exact PR head dd31abdd067a2b53eaa940d49f67fda8a2784091 against current main (2935458e0d194f1ada10db87db626ce41b471334). The change is limited to six files under examples/python-pytest/; it does not alter repository workflows, Rust product code, release control, or permissions.

The blocked CI run is 37888741886 (action_required, not a passing test). The applicable pull_request CI uses contents: read, persist-credentials: false, and format/clippy/test/lockfile checks. The proposed example uses a synthetic public fixture. This is a favorable preflight for an authorized maintainer to approve the restricted CI run, not a statement that it has been approved or executed.

Merge gate stays closed until that exact-head CI completes successfully and the historical Alpha.5 receipts remain clearly scoped. Standard Rust CI does not by itself establish that this Python recipe has been freshly exercised against ExecSurface v1.0.0; no such claim should be added.

No further broadening of the PR is requested. Thanks for retaining the negative evidence and documentation boundaries.

[aetherxeg-source]

Maintainer decision on exact head dd31abdd067a2b53eaa940d49f67fda8a2784091:

• The contributor has addressed the earlier scope/freshness request by synchronizing with current main and explicitly classifying the recipe as a historical, immutable Alpha.5 example; the original receipts and negative nondeterminism finding are retained.
• The changes are limited to six examples/python-pytest/ files, without modifications to product code or privileged workflows.
• Approved GitHub Actions CI run #37888741886, attempt 2 is SUCCESS at this exact head: format, strict clippy, Rust test suite, and lockfile integrity all passed.
• The five ExecSurface — ERROR sections in the GitHub job summary are expected fail-closed fixture results from r4_action_custody tests (five negative tests, one PASS), not failed CI steps. Their parent-summary leakage is tracked separately in draft PR #187. This does not change the contributor's source or evidence.

Scope of this approval: historically pinned documentation/fixture contribution only. It is not a fresh execution of the Python example against stable v1.0.0, nor independent product validation or an authorization to auto-merge. Release and security claims remain unchanged.

[aetherxeg-source]

Thank you @astrogilda for the reproducible Python/pytest contribution and for retaining both the expected PASS→REVIEW results and the earlier negative nondeterminism findings. This PR has now been merged after exact-head hosted CI #37888741886 succeeded.

For clarity to new users: ExecSurface's supported public release is v1.0.0, with @v1 for the stable GitHub Action. The historical Alpha.5 recipe remains exactly identified as historical; its binary pin and receipts were not relabeled as fresh v1 execution. The examples index links to the new v1 consumer example while preserving your historical contribution and credit. A future Python-specific v1 reproduction should use the actual published v1 binary and retain independent PASS/REVIEW evidence. Thanks again.