Remove remaining shaft-engine deprecated API calls

[MohabMohie]

Problem Statement

The full shaft-engine PR-gate job emits repeated removal warnings for Selenium HasBiDi#getBiDi / maybeGetBiDi, TerminalActions#isDockerizedTerminal, and Timeouts#dockerCommandTimeout from production and test callers.

Proposed Solution

Migrate each live caller to its supported replacement, then remove or advance the internal deprecated-call migration without changing public behavior.

Alternatives Considered

Leaving the warnings until the dependency removes the APIs avoids immediate edits, but makes the eventual upgrade abrupt and keeps every unrelated PR noisy.

Use Case & Impact

Keeps shaft-engine compatible with upcoming Selenium and internal API removals and restores warning signal quality.

Acceptance Criteria

• The named deprecated API warnings no longer appear in the shaft-engine compile/test job.
• Existing browser emulation and terminal/file behavior remains covered and green.
• Public API compatibility is preserved or follows deprecate-before-removal policy.

Proof Plan

• Run focused tests for browser emulation and terminal/file actions.
• Run the full shaft-engine unit-test job and inspect annotations.

Evidence: PR #4928 exact head a61ee5b068459e879eb21b0eab5d796e3a61c60d.
Duplicate searches on 2026-08-14 for maybeGetBiDi getBiDi deprecated and isDockerizedTerminal dockerCommandTimeout deprecated found no open issue.

[MohabMohie]

Implementation preflight receipt — 2026-08-14

Triage: public contract with many production/test callers; locally reversible, but the required Selenium API is an upstream published contract. Full executable-specification pass applies.

Live state

• Issue remains OPEN and actionable at SHAFT base e33185862c2c90f9c0803b2f1a968921a17f38fb; searches for deprecated HasBiDi getBiDi maybeGetBiDi Docker API found no duplicate SHAFT issue.
• PR test(infrastructure): stabilize mirror close assertion #4928 evidence head: a61ee5b068459e879eb21b0eab5d796e3a61c60d; merge: 45da2df80f88c671b553db998ebec0919f60329d.
• Native Memory returned no Remove remaining shaft-engine deprecated API calls #4930-specific solution. MemPalace returned older BiDi/Grid context only.
• Graphify G1-G4 receipt: shared cache resolved, but --check reported stale; the bounded query did not run; the read-only primary audit reported a manifest/revision mismatch. resolverOk=false queryOk=false auditOk=false. Explicit degraded mode is active; live rg below is authoritative and no refresh/shared-cache mutation will be attempted.
• Live rg found direct deprecated calls in production and fixtures beyond the ten annotations recorded on test(infrastructure): stabilize mirror close assertion #4928, so the root migration must cover all direct callers of the three named API families rather than merely moving the annotated lines.

Authoritative upstream research (accessed 2026-08-14)

• Selenium 4.47.0 is the current stable release and the version pinned by SHAFT.
• Selenium trunk aa36b38e696a0909e973bdf5e2f9031ffe842c4b: HasBiDi#getBiDi/maybeGetBiDi are removal-marked; getHandle() is the supported opaque-handle contract. Module delegates commands/subscriptions through that handle.
• Java Emulation has timezone/geolocation/etc. but no locale API and still sends through the deprecated raw BiDi accessor. Python and .NET already expose locale override.
• Upstream duplicate searches for Java setLocaleOverride found no implementation issue/PR. Open Selenium PR #17675 is an ADR about named convenience methods, not a Java locale implementation.
• Selenium CONTRIBUTING requires human review/ownership and disclosure for substantial AI assistance and forbids autonomous agents from opening issues/PRs, pushing commits, or posting review comments without direct human approval. No upstream write will occur before that gate.

Two-option design ruling

Selected — migrate at the root owners.

1. Upstream Selenium: make Java Emulation extend the supported Module, add SetLocaleOverrideParameters, setLocaleOverride, and context/user-context/clear tests.
2. After that contract ships in a stable Selenium release, SHAFT uses only public module APIs and tests them through HasBiDi#getHandle fixtures; live capability checks use session + negotiated webSocketUrl + supported module construction rather than the deprecated “already initialized” optional.
3. SHAFT keeps deprecated public Docker facades binary/source compatible, while production uses nondeprecated internal state/property owners and compatibility tests invoke old facades without direct compile-time calls.

Rejected — local raw commands/reflection/suppression. This could clear the warning quickly and avoid waiting for Selenium, and is attractive for a small diff. It loses because raw BiDi access is precisely the contract Selenium is removing; suppressing the warning hides a real removal risk; and broadly changing warning flags weakens unrelated checks. Reflection is permitted only in focused compatibility tests for SHAFT’s retained deprecated public facades, never as production transport.

Observed RED

Command:
mvn -pl shaft-engine -am clean test-compile "-DskipTests" "-Dallure.automaticallyOpen=false" "-DheadlessExecution=true"

The build completed, but the requirement is RED because javac emitted the named removal warnings:

• production: TerminalActions:1013 dockerCommandTimeout; FileActions:254,297 isDockerizedTerminal; BrowserEmulationManager:175 getBiDi;
• test(infrastructure): stabilize mirror close assertion #4928’s recorded test annotations: FileActionsCoverageUnitTest:179 and BrowserEmulationNamespaceTest:83,131,155,156,195;
• live clean test compilation additionally exposes further direct calls in BrowserEmulationNamespaceTest, BrowserEmulationNamespaceTraceTest, AutomationCapabilityResolverUnitTest, BrowserPermissionsNamespaceTest, BidiConsoleLogSourceTest, TimeoutsTests, and TerminalActionsUnitTest.

Resolved caller matrix

Site	Effective cwd/path	Runtime/version/platform	Permissions/trust	Configuration precedence	Input existence
BrowserEmulationManager	shaft-engine production	Java 25 / Selenium 4.47 / local or grid	public Selenium module only	negotiated session capabilities	live driver + context required
AutomationCapabilityResolver	shaft-engine production	Java 25 / Selenium/Appium	read-only capability inspection	session then webSocketUrl	null/closed/unsupported return false
DriverFactoryHelper, BrowserActions	shaft-engine production	Java 25 / Selenium/Appium	observability attach only	SHAFT reporting flags after session	failed/unsupported BiDi degrades
FileActions	shaft-engine production	Java 25 / host, SSH, legacy Docker	retained public terminal object	constructor/session state	empty Docker name means false
TerminalActions	shaft-engine production	Java 25 / host, SSH, legacy Docker	internal formatting/execution	thread override > global > system/file default	legacy Docker config may exist
BrowserEmulationNamespaceTest, BrowserEmulationNamespaceTraceTest	shaft-engine tests	Java 25 / Mockito	no live socket	explicit mock handle/capabilities	covers null, closed, Selenium, Appium
BrowserPermissionsNamespaceTest, BidiConsoleLogSourceTest	shaft-engine tests	Java 25 / Mockito	no live socket	explicit mock handle/capabilities	covers supported/unsupported
AutomationCapabilityResolverUnitTest	shaft-engine tests	Java 25 / Mockito	no live socket	explicit session/capabilities	covers missing and present BiDi
FileActionsCoverageUnitTest, TerminalActionsUnitTest	shaft-engine tests	Java 25 / local mocks	no external Docker execution	constructor state	both Docker and non-Docker states
TimeoutsTests	shaft-engine tests	Java 25 / OWNER	thread-local property scope	thread override over configured default	default and programmatic override
Selenium Emulation + parameter class	upstream Java binding	Bazel hermetic Java	WebDriver BiDi wire	contexts or userContexts	locale nullable only for clearing
Selenium locale tests	upstream Java browser tests	Bazel / supported browser matrix	disposable browser/user context	explicit context targeting	set, user-context, clear

State/failure matrix

State	Immutable ownership	Preflight	Mutation order	Mixed state	Atomicity	Concurrency	Idempotency	Recovery	Fail-closed
supported live BiDi	Selenium Module/Handle	live session + URL	validate then send	module and classic driver coexist	one command	handle owns connection	repeated override replaces value	null clears	command exception propagates
unsupported/closed BiDi	SHAFT capability guard	null/session/type/URL checks	no send	Appium/native contexts handled	no mutation	per driver	repeated check stable	create supported session	unsupported exception/false
locale set/clear	Selenium Emulation	locale validation in SHAFT	validate, target contexts, send	prior locale may exist	one protocol command	browser context scoped	set replaces; null clears	clear restores browser default	invalid input rejected
legacy Docker caller	retained SHAFT façade	constructor state	inspect then format/execute	host/SSH/Docker modes exclusive by existing rules	existing command behavior	instance state	existing semantics	supported host/SSH path	no silent mode switch
missing upstream release	Selenium release owner	stable artifact check	no SHAFT dependency bump	trunk code cannot substitute for artifact	no SHAFT source mutation	independent upstream flow	recheck release	wait for stable release	#4930 stays open
AI contribution gate	human contributor	exact diff/tests/disclosure shown	approval before any upstream write	local prototype remains isolated	no remote partial state	one owned branch	approval applies to exact revision	revise and re-present	no issue/PR/push/comment

Acceptance-to-proof map

Criterion or invariant	Positive proof	Negative or mutation proof	Command
no named deprecated direct calls	clean compile contains zero warnings for the three API families	live rg rejects any production/test direct call	clean Maven test-compile + rg -n
public SHAFT API retained	reflection invokes retained methods and observes same state/value	API signature/binary inspection fails if removed	focused terminal/property tests + javap
BiDi behavior preserved	focused emulation, permission, console, trace, capability tests pass	missing handle/URL/closed session cases reject	focused TestNG selector
locale becomes supported upstream	context and user-context set/clear tests pass	deleting class/method makes compile/test RED	targeted Selenium Bazel tests
no warning suppression/raw transport	diff contains no new SuppressWarnings("removal") or SHAFT raw Command	structural search fails on either	rg plus diff audit
stable dependency only	Maven resolves released Selenium and convergence passes	snapshot/prerelease coordinate rejected	reactor version/dependency validation + Maven verify
test execution is real	Surefire/TestNG XML counts are nonzero and green	absent/zero reports fail verdict	report-file count script

Proof plan after the upstream gate/release

• Upstream: targeted Bazel emulation tests and Java build, isolated output base.
• SHAFT: focused emulation/permissions/trace/console/capability/file/terminal/timeout tests; clean test-compile; affected package/verify with -Dallure.automaticallyOpen=false; inspect Surefire/TestNG/Allure report counts.
• Independent exact-revision adversarial review before PR delivery. Remove remaining shaft-engine deprecated API calls #4930 remains open until a stable Selenium release is consumed and every named warning is absent.

[MohabMohie]

Research correction — existing upstream root owner

A broader live upstream search after the receipt found an architectural dependency that changes the selected upstream action:

• Selenium PR #17777, OPEN at exact head c72ff7f3c049f9d87e070bc51b47c7d75f64ef32, already implements the Java BiDi code generator.
• Its stated output covers all 14 BiDi domains and all schema commands through generated classes extending Module/the supported Handle seam. The PR specifically lists generated emulation parameter coverage; the schema includes emulation.setLocaleOverride.
• Therefore, once #17777 merges and appears in a stable Selenium release, SHAFT can use the generated typed org.openqa.selenium.bidi.protocol.module.Emulation and locale parameters without raw HasBiDi#getBiDi/maybeGetBiDi.

Revised ruling: do not open a manual handwritten Java locale issue/PR. That would duplicate and potentially conflict with #17777’s generator-owned API. Track #17777 to merge and stable release, then perform the SHAFT migration. The local handwritten prototype is rejected, uncommitted, and unpushed.

This correction supersedes only the receipt’s proposed manual upstream locale contribution. Its SHAFT warning RED, caller/state matrices, public-compatibility constraints, and proof plan remain valid. #4930 stays open while the supported upstream API is unreleased.

[MohabMohie]

External dependency status

Selenium #17777 is not user-owned: it comes from pujagani/selenium:java-bidi-codegen. At exact head c72ff7f3c049f9d87e070bc51b47c7d75f64ef32 it is OPEN/BLOCKED. Current required failures are:

• Test / All RBE tests
• Format / Check Format
• Fork format instructions

Its Java browser tests on Windows/macOS and Java remote test on macOS are green. SHAFT cannot modify or push the contributor’s branch, and Selenium’s AI contribution policy forbids an autonomous comment without direct human approval.

Result: #4930 is externally blocked under the approved “stable supported upstream contract first” design. No SHAFT implementation commit or upstream write has been made; the isolated SHAFT branch remains clean.

[MohabMohie]

Supported-path correction — blocker refuted, revised implementation ruling

Live Selenium 4.47.0 bytecode and official API documentation establish a supported seam that the earlier receipt missed:

• HasBiDi#getHandle() is the nondeprecated replacement.
• org.openqa.selenium.bidi.Module(WebDriver) calls getHandle(); its protected final send(Command) delegates through that opaque handle.
• RemoteWebDriver#getHandle() fails with BiDiException when no negotiated BiDi connection exists.
• Selenium's official warning page describes low-level BiDi classes as an escape hatch when high-level coverage is missing. Existing upstream PR [java][bidi] Add BiDi code generator SeleniumHQ/selenium#17777 remains the long-term typed root owner, so SHAFT will not duplicate it.

Revised two-option ruling

Selected: use a private SHAFT locale module extending Selenium's nondeprecated Module seam to preserve the exact existing emulation.setLocaleOverride method and context/clear parameters; replace readiness probes with getHandle() under the existing fail-closed checks. Replace Docker-state calls with their exact existing owners (dockerName internally and getDockerName() across classes). Add a nondeprecated timeout accessor mapped to the existing dockerCommandTimeout key so units, defaults, source precedence, and compatibility remain unchanged while the deprecated façade stays callable.

Rejected: wait for #17777. That provides a stronger typed API and remains the preferred eventual replacement, but it is externally blocked and unnecessary for removing SHAFT's dependency on APIs Selenium marked for removal. A raw getBiDi() call, reflection in production, suppression, or substituting shellSessionTimeout would respectively retain the removal risk, hide it, or change seconds to minutes.

Exact RED retained and narrowed

mvn -pl shaft-engine -am clean test-compile "-DskipTests" "-Dallure.automaticallyOpen=false" "-DheadlessExecution=true"

Observed RED remains the named removal warnings listed in the implementation receipt. Live javap additionally proves Handle.send is package-private while Module.send is the supported protected bridge, so direct handle transport cannot compile outside Selenium. The GREEN gate is the same clean compile with zero warnings for getBiDi, maybeGetBiDi, isDockerizedTerminal, or dockerCommandTimeout, plus focused behavior tests and nonzero report counts.

This supersedes the external-blocker conclusion; it does not authorize an upstream write or weaken the existing caller/state/acceptance matrices.

[MohabMohie]

GREEN receipt — supported replacements verified

Integrated this worktree with fresh origin/main at 656a3218571efd58f7b327846881843894955b89 before retaining any implementation commit.

• RED: TimeoutsTests#dockerCommandTimeoutHasSupportedCompatibilityAccessor produced 1 test / 1 failure because no supported Docker timeout accessor existed (Surefire recorded the failure even though the repository's configured testFailureIgnore printed a reactor success).
• Selenium 4.47 API proof: HasBiDi#getHandle() is non-deprecated, and Selenium's supported Module(WebDriver) constructor delegates commands through that opaque handle. A small SHAFT-owned emulation module therefore preserves the existing raw locale override without recreating upstream transport APIs.
• GREEN focused affected flow: BrowserEmulationNamespaceTest,BrowserEmulationNamespaceTraceTest,BrowserPermissionsNamespaceTest,BidiConsoleLogSourceTest,AutomationCapabilityResolverUnitTest,FileActionsCoverageUnitTest,TerminalActionsUnitTest,TimeoutsTests => final TEST-TestSuite.xml reports 157 tests, 0 failures, 0 errors, 0 skipped. The narrow run used -Dshaft.trace.includeNetwork=false; the dedicated trace companion remains included and passed all 35 of its cases.
• GREEN clean warning scan: mvn -pl shaft-engine -am clean test-compile -DskipTests -Dallure.automaticallyOpen=false -DheadlessExecution=true exited 0. It emitted 17 unrelated baseline warning lines and 0 named removal-warning lines for getBiDi, maybeGetBiDi, isDockerizedTerminal, or dockerCommandTimeout.
• GREEN affected package: mvn -pl shaft-engine -am package -DskipTests -Dallure.automaticallyOpen=false -DheadlessExecution=true => all 3 reactor modules SUCCESS.
• Live source scan: direct invocations of the four deprecated methods in shaft-engine/src/main/java and shaft-engine/src/test/java = 0. Deprecated SHAFT declarations remain for public compatibility; supported replacements map to the same state/property key.

Graphify remains in explicit degraded mode: its checkout/revision evidence is stale and concurrent refresh would contend with other worktrees. No refresh was attempted; current files plus targeted rg supplied authoritative ownership/caller evidence. No Selenium upstream issue or duplicate was created; Selenium #17777 remains the existing long-term typed-API owner.