tech-debt-backlog §§7.21–7.24: hybrid-bridge cleanup + 2026-06-05 triage

[jascal]

Summary

Files the 2026-06-05 feedback triage for the seven-day window ending 2026-06-05 (5 new items, §§7.21–7.25), then resolves the four hybrid-bridge follow-ups from the 2026-05-30 PR #99 review log.

Three of the four were silently addressed inside PR #99 itself but never checked off in tasks.md; this PR records that and closes the loop with annotated check marks. The fourth (§7.23) needed a one-line cleanup.

• §7.21 (friendly preflight for register_foreign_runner) — already shipped in PR demo(hybrid-bridge): classical Orca ↔ quantum q-orca over the cross-tool bridge #99: run_demo.py:86-91 checks hasattr(machine, "register_foreign_runner") and raises SystemExit with the README pointer + the orca-runtime-python >= 0.1.28 pin. Marked done with a note that the hasattr target was adjusted (attribute lives on the OrcaMachine instance, not the runtime_python module) from what the spec'd fix originally sketched.
• §7.22 (2.348 vs 2.346 docstring typo) — already reconciled in PR demo(hybrid-bridge): classical Orca ↔ quantum q-orca over the cross-tool bridge #99's "address review nits" commit; both run_demo.py:48 and README.md:60 carry 2.346, which is the correct value (2·asin(√0.85) ≈ 2.3462).
• §7.23 (repo-escaping doc link) — drops the misleading HTML comment on examples/hybrid-bridge/README.md:10 that pointed raw-markdown readers at ../../../orca-lang/docs/cross-tool-invoke-and-returns.md, a path only valid for one specific side-by-side checkout layout. The canonical upstream GitHub URL on the preceding line is now the single source of truth.
• §7.24 (unguarded TARGET input) — already shipped in PR demo(hybrid-bridge): classical Orca ↔ quantum q-orca over the cross-tool bridge #99: run_demo.py:93-100 parses TARGET as a float (with a diagnostic that names the offending value) and enforces 0.0 < TARGET < 1.0. The accepted range was tightened from the originally-spec'd (0, 2π) to (0, 1) because TARGET is a target P(1) — a probability — not an angle; the GAIN≈Newton clamp downstream operates on θ ∈ (0.01, π−0.01), so the probability guard at the entry point is the correct boundary check.

§7.25 (sweep the pre-existing ruff errors across tests/) is left open for a dedicated half-day pass.

Test plan

• .venv/bin/pytest -q — full suite green (1274 passed, 8 skipped)
• .venv/bin/pytest -q -k "hybrid or bridge" — all 10 hybrid-bridge / bridge tests pass
• CI green on the PR

[jascal]

Code Review — Claude Sonnet 4.6

Thorough, well-reasoned bookkeeping PR. It files the 2026-06-05 feedback triage (§§7.21–7.25) and closes the four hybrid-bridge follow-ups from the PR #99 review log, with one actual code change (the §7.23 README cleanup). I verified every substantive claim in the triage against the tree at examples/hybrid-bridge/run_demo.py and examples/hybrid-bridge/README.md — they hold up.

Verification of the triage claims

• §7.21 (preflight for register_foreign_runner) — ✅ Confirmed. run_demo.py:86-91 does if not hasattr(machine, "register_foreign_runner") → raise SystemExit(...), and the message names both the missing attribute and the orca-runtime-python >= 0.1.28 pin. The note correctly explains why the hasattr target moved from the originally-spec'd runtime_python module to the OrcaMachine instance — the actual call site is machine.register_foreign_runner(...) at run_demo.py:121, so checking the instance is the right preflight.
• §7.22 (2.348 vs 2.346) — ✅ Value is correct: 2·asin(√0.85) = 2.3462, so 2.346 is right. Both copies agree. One nit: the citation says the value lives at README.md:60, but grep -n "2.346" puts it at README.md:59 (line 60 is machine's 'target' context field). The run_demo.py:48 reference is spot-on. Given this whole document is built on precise file:line citations, the off-by-one is worth fixing for the next reader who jumps to the line.
• §7.23 (repo-escaping doc link) — ✅ The diff cleanly drops the <!-- ... ../../../orca-lang/docs/... --> HTML comment and leaves the canonical GitHub URL on the preceding line as the single source of truth. Good call — that relative path only resolved for one specific side-by-side checkout and was invisible-but-wrong on the GitHub web UI anyway.
• §7.24 (unguarded TARGET) — ✅ Confirmed at run_demo.py:93-100: parses to float (rejecting non-numeric with a diagnostic that echoes the offending value) and enforces 0.0 < TARGET < 1.0. The reasoning for tightening (0, 2π) → (0, 1) is sound and worth restating: TARGET is a target P(1), so θ* = 2·asin(√target) ∈ (0, π) for target ∈ (0, 1), which is exactly the band the downstream clamp min(π−0.01, max(0.01, …)) at run_demo.py:72 operates in. Validating the probability at the entry point is the correct boundary.

Lint / tests (branch checked out)

• .venv/bin/pytest -q → 1274 passed, 8 skipped in ~22s — matches the test plan exactly.
• .venv/bin/ruff check . → 18 errors, all in tests/ (test_compiler.py ×9, test_noise_model_section.py ×5, test_verifier.py ×2, test_qpc_convergence.py ×1, test_examples.py ×1). None touch the two files this PR modifies, so the PR introduces zero new lint. This is exactly the pre-existing surface that §7.25 leaves open as a tracked tech-debt item — consistent and correctly scoped out.

What looks good

• The triage doesn't just check boxes — it records what actually shipped vs. what was spec'd and why they diverged (§7.21's attribute relocation, §7.24's range tightening). That's the right altitude for a debt log; future readers won't have to re-derive the rationale.
• Honest about its own limits: the "Caveat on this run" note about the egress proxy blocking api.github.com and the unenumerable #100/#111 nits is exactly the kind of provenance future-you will thank present-you for.
• Leaving §7.25 unchecked rather than hand-waving it closed is the right move.

Minor / optional

1. README.md:60 → :59 in the §7.22 citation (and the same reference in the PR description) — small, but this doc trades on line precision.
2. Removing the HTML comment leaves two consecutive blank lines between the [bridge-doc]: link and ## What it does (markdownlint MD012). Purely cosmetic, not a blocker.
3. Out of scope but adjacent: the README version table at README.md:69 pins orca-runtime-python as "post-PR #13" while the §7.21 error message says >= 0.1.28. Not contradictory, but a future reader reconciling the two would have to do some archaeology — perhaps a candidate for a later traceability nit if you're tracking that surface.

Verdict

No blockers. Claims verified, tests green, no new lint, change is minimal and well-justified. Recommend merge after the trivial README.md:59 citation fix (or merge as-is — it's a comment in a debt log, not load-bearing).

This review was posted automatically by Claude Sonnet 4.6.