[Dobbes]

Summary

Scientists can connect through an Engine-like orchestration layer, inspect and select usable services, compute and export observations, close locally, and restore the original authorized work in another Python process using the existing Client APIs.

• Add versioned secret-free DeploymentProfile, typed bootstrap identity/service references, catalog and injectable selection policy.
• Support both existing origin-bound issued tokens and the inspected native Hub/ENGINE-certificate exchange (POST /api/v2/engines/auth-cert). Parse Java-properties encoding/escaping/continuations, enforce explicit Hub/service trust, and reject credential-bearing redirects.
• Provide bounded capability/status observation, explicit refresh/readiness, scoped peer initialization and latest pending advertisements. Keep selected Runtime endpoint/UUID bindings stable.
• Reacquire only through supported providers; principal/issuer changes require reconnection. Preserve mutation uncertainty without scientific replay and keep Connection.close() local-only.
• Preserve primary failures through Connection/bootstrap cleanup; close both bootstrap resources independently, sanitize cleanup diagnostics and test interruption/error paths.
• Add named connection functional suites and shared compute/GeoJSON/fresh-process workflows, preserving direct Client construction and the existing scientific validators.
• Persist the updated planning guide, public API/contracts/example, assumption ledger and exact-source verification records.

Example

from klab_client import DeploymentProfile, HubCertificateProvider, connect

profile = DeploymentProfile.load("deployment.json")
with connect(profile, credentials=HubCertificateProvider("/private/klab.cert")) as connection:
    connection.wait_ready(timeout=30)
    print(connection.catalog.summary())
    client = connection.client
    # Existing typed observe, Job, native export and saved-handle APIs.

The same workflow accepts IssuedTokenProvider; profile/environment references keep credential values outside profile files, saved handles and subprocess arguments. Authentication/group metadata is descriptive, not a client-side authorization grant.

Functional tests added

python-client/tests/functional/test_connection.py contains four live cases:

1. Certificate connect -> typed compute -> independent value/unit checks -> native GeoJSON -> local close -> fresh-process recovery.
2. The same workflow through the issued-token provider.
3. Owner reconnect, valid collaborator positive control, private-context denial and known expired TEST JWT rejection.
4. Actual required-service readiness.

The existing runner recognizes connection-onboarding, connection-recovery, connection-access and connection-readiness. Onboarding/recovery share the same combined two-provider scenario. Offline unit/local HTTP subprocess checks cover trust, redirects, ambiguity, expiry, identity changes, unknown capabilities, deterministic deadlines, cleanup faults and mutation non-replay.

Validation

Reviewed integration base: 9c7c371539ff31a05238cfc7355395ca05f21ace on feature/python-client.
Verified connection milestone: 1bb607ea08e5acdc86f294afa634cc16dead6cb1. The subsequent diagnostic-only correction is included on this PR branch and has separate validation below.

• 777 offline unit/integration tests passed per environment: Windows Python 3.12.7 and independently installed Linux Python 3.11, 3.12 and 3.13. Installed SDK file hashes matched the tested source.
• Existing coverage gate passed: unexcluded 100% lines/branches for required new modules and changed-code coverage. Deadline controls use module-local clocks rather than scheduler timing.
• Existing E9,F63,F7,F82 lint, sdist and wheel builds passed.
• Seven owned real-service checks passed with PYTHONOPTIMIZE=1, including the four new connection cases and three existing regressions. Independent fixture oracle: 20 cells at 123.25 m and 20 at 123250 mm; native GeoJSON identity and geographic corners checked independently.
• Parent connections close before recovery subprocesses; original handles are restored/exported without scientific resubmission. Explicit owned context/session cleanup, stopped JVMs/authority, closed ports and public-evidence secret scanning verified.
• Fresh read-only reviews reran the offline suite/coverage/lint and verified the committed executable manifest against the installed/live records. No remaining blocking/important finding was identified within this scope.

Executable source digest for that verified milestone: b11a45bc8fc1225e0469e833349122d858bdb6c1c4b4fbfdad3de8ede3d8d687.

JSON diagnostic refinement on this PR

The optional review note is addressed: invalid-JSON classification is limited to JSON decoding. A closing ValueError or TypeError after a valid response now produces a sanitized TransportError, while malformed JSON/encoding remains a ProtocolError.

Follow-up validation: 17 focused tests and 780 full offline tests passed on Windows Python 3.12.7, with existing coverage/lint gates passed. The earlier installed-interpreter/build/live results above describe the verified milestone; they were not rerun for this narrow diagnostic-only follow-up. Updated hosted checks run on the PR branch.

Evidence and reproduction:

• python-client/docs/connection-verification.md
• python-client/docs/results/bootstrap-cleanup-verification.json
• python-client/docs/connection-layer.md

Controlled acceptance used explicit compiled server candidate 244883d7b04f1eae2cc22e799575d33a9bdb2a43, pinned imod 608bef150ced0a109db98a5aad64ba4461beaa54, and published geospatial component 1.0-20260926.083046-222 (SHA-256 e7d470f69943e93ce48e9669bad6a41b618dfbe0e7bc748076e010583daef644). Source/class/model hashes are retained in the record.

Acceptance boundaries

• Actual Hub onboarding is Not run: no actual ENGINE certificate/deployment was supplied. The loopback controlled authority matches the inspected exchange contract and issues signed TEST credentials accepted by genuine services; it does not decrypt/validate production licenses or agreements.
• Hub route/DTO inspection includes authoritative legacy Hub source at ac41ff2074246eb310de015da8b780e2a00f3490; no refresh, browser-login or authenticated Engine-attachment endpoint is invented.
• This does not finish the separate server identity-sharing work tracked by Validate Python client integration with cross-service identity and shared-session permissions #89/Integrate develop cross-service identity and permissions with Python client foundation #90, global discovery/migration/replay, provider/worker execution or measured-provider accuracy. No Java-suite pass or numerical TIFF acceptance is claimed by this feature.
• The previously noted non-blocking EOF-close diagnostic issue is corrected by the JSON diagnostic refinement above.

Commits

• 440a14611 Add Engine-like Python connections and functional recovery
• d71a8a029 Preserve primary connection failures during cleanup
• 1bb607ea0 Harden bootstrap cleanup and deterministic deadline checks
• ec863f9ac Scope bootstrap JSON error classification to decoding