Add generated TUS protocol contract canary

[kvz]

Experimental Status

Experimental work: this PR is part of an exploratory contract/generated docs and SDK effort, and is intentionally kept as a Draft while the approach is validated.

Why: this is the Java companion canary for the API2 contract generator work. API2 owns the TUS protocol contract; this PR proves tus-java-client can consume generated protocol facts and contract-owned scenarios without duplicating wire knowledge in the Java repo.

What changed:

• add generated TusProtocol.DEFAULT_PROTOCOL_VERSION from the API2 TUS wire contract
• source TusClient.TUS_VERSION from that generated constant
• add a generated protocol contract fixture for operations, headers, responses, wire versions, and high-level feature facts
• add checked-in API2 devdock examples for custom request headers, request IDs, upload body headers, creation-with-upload, deferred length, relative Location resolution, PATCH method override, file URL storage, retry state transitions, detailed create-upload errors, start-option validation, abort upload, parallel concat, protocol version selection, and node path input sources
• add generated runtime constants for location/metadata/upload-length/upload-offset/upload-body content headers, content type, retry/detailed-error/start-option messages, detailed-error templates, option defaults, concatenation header values, and protocol compatibility versions
• add TusClient.createUploadWithData(TusUpload, int) for Creation With Upload
• add TusURLFileStore as a persistent file-backed TusURLStore
• add TusExecutor retry hooks and retry-attempt reset support while preserving the existing default retry behavior
• add public TusDetailedError, TusResponseException, and TusRequestException so callers can inspect response/request failures with original request context
• add public TusStartOptions and TusClient.validateStartOptions(...) so callers can validate typed start options before issuing any request
• add TusClient.abortUpload() / TusClient.abortUpload(TusUploader, boolean) plus TusUploader.abort() / TusUploader.isAborted() so Java can abort in-flight uploads and optionally terminate stored URLs
• add TusClient.createPartialUpload(...) and TusClient.concatenateUploads(...) so Java can prove TUS concatenation with public SDK APIs
• add TusClient.setProtocol(...) / TusClient.getProtocol() so Java can select generated client protocol modes such as tus-v1 and ietf-draft-05
• add Api2DevdockTusNodePathInputSource, which proves the contract-owned node-path-reference scenario through Java's existing TusUpload(File) source primitive
• keep protocol knowledge in the API2 contract/generated runtime; checked-in examples read scenario shape and use public Java SDK APIs

Latest update:

• API2 QA now routes tusNodePathInputSource to Java as the twenty-fourth TUS Java checked proof
• Java/tus now has no remaining unproved generated protocol feature IDs in API2 dry-run output
• shared example/conformance helpers now accept any scenario input source with contract content, so node-path-reference uses the same validation path as blob

Validation:

• ./gradlew check --rerun-tasks
• git diff --check
• direct Java node-path proof with contract-projected scenario JSON
• API2 generator: node api2/bin/cli.ts contracts sdks --no-motd --target tus --platform java --sdk-root ../tus-java-client --compare-existing
• API2 dry-run: node api2/bin/cli.ts contracts sdks qa --no-motd --target tus --platform java --dry-run
• API2 focused command test: core/bin/devdock.ts exec tstrun cmds/ContractsCommand.vitest.ts -vv --max-time-per-test 420
• API2 repo check: yarn check
• API2 clone-based live wrapper passed with all twenty-three Java TUS scenarios before this slice. The latest twenty-four-scenario live wrapper was attempted twice but did not reach tests because API2's UploaderProcess did not emit its ready pattern within 120s; this is recorded on the API2 side for follow-up.

Companion PRs (tus org only)

• tus-js-client: Mark protocol versions as generated tus-js-client#872
• tus-go-client: Add generated TUS protocol canary tus-go-client#6
• tus-py-client: Add generated TUS protocol canary tus-py-client#114
• tus-android-client: Add generated TUS protocol contract canary tus-android-client#167

Notes

Local/API2 clone-based validation is the strongest signal because it exercises the generated contract path and live devdock API2/tusd stack. The latest direct Java conformance proof passed; the latest clone-based live proof is blocked by API2 uploader readiness before any example runs.