Engine Session

The current bridge can locate the configured ACT checkout, stage another branch head of an ACT git remote and switch imports to it, import it, probe its commit and runtime, report the pinned baseline capabilities, and run Gurobi's own license check in a fresh process. It does not create session handles or manage workers, queues, HTTP connections, or user sessions. The workbench owns worker lifecycle. Follow the repository rules and engine_bridge scope.

For project navigation, see engine_bridge flow and choose a development task.

Change Guide

Goal	Required edits	Conditional / reused path
Change checkout discovery or diagnostics	session.py, test_engine_session.py	Existing EngineInfo consumers need no change if fields/semantics remain compatible.
Change branch staging or import switching	checkouts.py (git), act_code_root / act_imports in session.py, tests	Which remotes are offered and which checkout is active belong to visual_bench/engine.
Call a new ACT function from an adapter	Add it to that capability's requirements in parity.py with the keyword parameters and positional count the adapter passes	test_pinned_baseline_passes_every_api_check must stay green; the workbench then gates the feature on the result.
Advertise a capability	Prove the native ACT path, then update _BASELINE_CAPABILITIES, its parity.py requirements and the owning adapter/test	Update workbench gating only if availability/contract changes, not just because a capability label is added.
Query optional fuzz control support inside an adapter	Public capability_available(name) in parity.py, exported by __init__.py	Cached by capability and active checkout path; full probe still reports each requirement and its diagnostic.
Change Gurobi probing	probe_gurobi in session.py, probe tests	License storage/upload policy belongs to visual_bench/engine.
Add process-local handles	ES-02 backlog and ACT lifecycle prerequisite	No current handle API exists; keep worker supervision in verification.

Flow Diagram

Arrows name requests, returned data, or persistence handoffs. Only implemented paths are shown.

Block	Code / contract	Handoff
Probe	session.py: probe, probe_gurobi; contracts.py: EngineInfo, SolverStatus	Workbench engine maps status and gating.
Branch staging	checkouts.py: list_branches, fetch_checkout → Checkout	visual_bench/engine selects the staged path through ACT_CODE_ROOT and a service restart.
API parity	parity.py: requirements, check_api → ApiCheck; called by probe	A capability is available only when every ACT symbol its adapter calls resolves with compatible parameters; failures add an api_mismatch warning. probe_isolated runs the same probe in a fresh interpreter for a checkout this process must not import.
Import setup	session.py: act_root (baseline assets), act_code_root (imported code), act_imports	model_spec, execution, inspection and events reuse it internally.

Validation

Run the focused real-ACT tests:

.venv/bin/python -m pytest engine_bridge/engine_session

The tests use the pinned catalog and real ACT checkout. test_probe_missing_act_is_a_deterministic_error uses a temporary path only for the missing-environment branch. Gurobi tests are skipped when gurobipy is not installed. No test result is implied by this guide.

Acceptance evidence for the stable current slice is ES-01 and ES-04 below. ES-02 and ES-03 remain planned.

Reference and Backlog

Current files and operation details

Current Files and Usage

File	Current responsibility
session.py	act_root, act_imports, probe, probe_gurobi, and the baseline capability table
parity.py	Per-capability ACT API requirements, check_api, and cached capability_available; interface checks, not numerical semantics
checkouts.py	list_branches (git ls-remote), fetch_checkout: shallow clone of one branch head to <engines_root>/<url hash>/<commit>, reused per commit, with the baseline's git-ignored data/ and literature/ linked in
init.py	Re-exports act_code_root, act_imports, act_root, fetch_checkout, list_branches, probe, probe_isolated, and probe_gurobi
test_engine_session.py	Real pinned-commit probe, missing ACT, version mismatch, Gurobi license rejection, branch staging, isolated probe and API checks against a synthetic git remote (engine_bridge/testing.py: fake_act_remote, not ACT), every API check passing on the pinned baseline, and missing-symbol/parameter/arity detection

Import callers are model_spec, execution, inspection and events through act_imports, plus visual_bench/engine through probe and probe_gurobi. The bridge types are EngineInfo, Capability, Diagnostic, SolverStatus, and BridgeError in ../contracts.py.

Operation Notes

observe.propagation is optional on older ACT checkouts. Its requirements include observe, emit, RecordKey, LayerBounds, Relaxation, DualBackward, SpecBound, and the existing verify_once requirements. Only checkouts satisfying all of them advertise availability; verification otherwise keeps the existing recorded interval-state fallback. The observation API is checked independently of the solver/domain capability needed to start a run.

fuzz.control is independently optional on the pinned baseline. Requirements cover the public fuzz option registry, control methods, start/step/change/end records, observer registration, live validation, and the ACTFuzzer(control=...) parameter. A failed check leaves existing fuzz execution available through the legacy adapter. Native acceptance is ACT_CODE_ROOT=/data1/guanqin/ACT-wt/act-gui-match .venv/bin/python -m pytest engine_bridge/execution/test_fuzz_control.py. The 2026-11-06 full-suite counts and existing baseline incompatibilities are recorded in execution validation; the per-checkout cache regression passed in both runs.

events.bab_nodes and verify.bab.options are optional as well and need ACT with act.pipeline.gui.bab_gui. Their requirements check verify_bab_batched before bab_gui, because importing bab_gui first is circular on ACT 22693fb. events.bab_nodes adds the on_progress parameter, act_gui.observe, BaBWave and BaBTerminal; without it BaB records only the final summary. verify.bab.options adds bab_options, bab_run_config and act_gui.validate_changes; without it the run form offers no BaB settings and BaB runs with ACT's pipeline.yaml settings.

Change the ACT probe or capability list

Edit session.py:

• act_root() resolves ACT_ROOT, defaulting to /data1/guanqin/ACT. It stays the baseline: catalog nets, data/ and literature/ are read from it.
• act_code_root() is ACT_CODE_ROOT when set (a staged branch), else act_root(); act_imports() and probe() use it.
• act_imports() verifies the checkout and imports ACT, raising BridgeError with act_missing or act_import_failed. A process imports ACT from one checkout only: ACT registers ONNX converters in global third-party registries, so re-importing it from another checkout in the same process fails. Switching therefore means a new process.
• _BASELINE_CAPABILITIES is the source for advertised support. Keep each source tied to a real ACT call or an explicit missing hook.
• probe(expected_commit, root) returns EngineInfo with commit, Python, torch, CUDA, capabilities, and diagnostics. A commit mismatch is a warning, not a failed probe. A missing or unimportable checkout is an error.
• probe_gurobi(license_file) starts a separate Python process and returns SolverStatus. It reports Gurobi's result, never a credential value, and does not claim that current methods use Gurobi.

Update test_engine_session.py with a real baseline expectation when ACT changes. Then inspect visual_bench/engine/service.py, which maps EngineInfo to the Engine tab and calls require_engine() before bridge work.

Add an ACT-dependent bridge capability

First establish the native ACT call and its semantics. Then update _BASELINE_CAPABILITIES, the owning bridge module, its parity test, and the workbench service mapping. If the capability needs a new ACT hook, retain the task's ACT dependency in docs/plan.md. Do not advertise a capability because a UI control exists.

Add resource handles

This is planned work, not a current API. It requires ES-01, then ES-02 and ACT-02. Add process ownership, close behavior, and post-close diagnostics only when ACT exposes a safe lifecycle. Do not move worker startup or restart policy into this module.

Task evidence, design constraints and future capabilities

Task Evidence

ID	Deliverable	Depends on	Completion evidence
ES-01	Implement version/capability probe	BASE-01	Against the pinned baseline, every advertised capability has a known support source or verified sample; missing ACT and version mismatch produce deterministic diagnostics.
ES-02	Implement explicit resource handles	ES-01	Open/use/close has a defined lifecycle; crossing a process boundary does not transfer native solver/GPU objects.
ES-04	Probe optional solver licenses (Gurobi)	ES-01	probe_gurobi(license_file) starts a Gurobi environment in a fresh process and returns Gurobi's own verdict as licensed, restricted, invalid, or not_installed, without credential values; a host-bound license for another host reports invalid with Gurobi's HostID message (test_engine_session.py).
ES-05	Stage and probe an ACT branch head	ES-01	list_branches and fetch_checkout stage a branch head as a reusable per-commit checkout linked to baseline assets; unknown branches raise branch_not_found; ACT_CODE_ROOT makes a fresh process import it; probe_isolated probes it without importing it here (test_engine_session.py, synthetic remote).
ES-06	Check ACT API parity per capability	ES-01	Every capability with adapter calls lists its ACT requirements in parity.py; probe reports one ApiCheck each and downgrades a capability with a failed check to unsupported with the reason; all checks pass on the pinned baseline; a missing symbol, keyword parameter or positional arity is detected (test_engine_session.py). Checks cover interfaces only; numerical parity stays with the native parity tests.
ES-03	Validate cleanup and compatibility regression	ES-02	Repeated close and post-close access produce deterministic diagnostics with no leaked resources; ES-01 incompatibility diagnostics hold across every declared engine combination.
ES-07	Gate optional public fuzz controls by API parity	ES-06, ACT-08	fuzz.control is unavailable on the pinned baseline and available only when all public symbols and the control constructor argument match. test_engine_session.py retains mandatory baseline checks and tests capability caching per checkout; EXE-07 exercises the native API.

Boundaries and Cross-Module Changes

Changes to this module normally pass through existing callers without edits when the public functions and frozen contract fields remain compatible. A changed capability affects visual_bench/engine and any service that gates on it. A changed EngineInfo or SolverStatus requires updates to the workbench schemas and their tests, but engine_bridge must not import those schemas. ACT version changes require the adapter, parity tests, and capability source to move together.

The original design target was a process-local session facade with explicit openSession and closeSession operations. That API is not implemented. Add it only with ES-02 and ACT-02 evidence. Split internal files only when lifecycle logic has independent evolution or size. Do not create a provider registry or another process manager for this task.