Separate named uploads from custom fields

[kvz]

Why: the shared fields option serialized named upload IOs into signed JSON and duplicated custom metadata as form fields, coercing typed values or producing bracketed keys.

Add uploads: {name => io} to Assembly options and create!. Named files become multipart parts; fields stays entirely in signed JSON with its numbers, booleans, arrays, objects, and null intact. Keep positional file_N uploads and create!(fields: metadata) overrides. Legacy IO entries in fields continue uploading throughout v4 with a deprecation warning and a documented migration path.

Preserve original stream positions when retrying rate-limited uploads and raise a clear IOError for streams that cannot be replayed. Document upload precedence, reserved names, and caller-owned file handles. Add an Unreleased changelog entry; no version bump or release.

The repository's Ruby 3.1 test bundle uses JSON 2 for the separate, preexisting MultiJson compatibility issue in #89. The runtime gemspec is unchanged, and compatible JSON 3 applications on newer Rubies remain supported. The README includes the Ruby 3.1 application workaround; #89 remains open for the runtime dependency fix.

Validation:

• Test-first: 16 new regressions, including real encoded multipart bodies, binary File bytes, exact typed JSON, HMACs, legacy calls, precedence, and retry behavior.
• Ruby 3.1: full suite and Standard Ruby pass, 140 tests / 354 assertions; optional Node parity and live upload skipped locally.
• Ruby 4.0 with JSON 3: full suite and Standard Ruby pass, 140 tests / 364 assertions, including Node signature parity; only the optional live upload skipped locally. An explicit JSON >= 3 consumer bundle also resolves and passes the full suite.
• Council: four rounds; the final two had no important, related findings worth fixing. Round 4 reported no issues. The P3 warning-control suggestion was declined to keep the repo's visible deprecation convention.
• GitHub CI: all five supported Ruby matrix jobs and the live end-to-end upload job passed.
• Signed commit fef2891 is GitHub-verified, with no co-author trailer. git diff --check passes.

After release, Content can upgrade its pinned gem and generate assembly(uploads: named_files, fields: metadata).create!, removing the 4.0.0 create!(fields: metadata) workaround while retaining binary File handles, cleanup, and the real-gem sweep.

Closes #88.

_{🤖 Claimed by kvz on framework1/ruby-sdk since 2026-10-18 · resume: codex resume 01a14e1d-ce02-76b1-81f0-5014b90ba94d}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.96970% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 98.89%. Comparing base (79535b2) to head (fef2891).

Files with missing lines	Patch %	Lines
lib/transloadit/assembly.rb	96.96%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #90      +/-   ##
==========================================
- Coverage   99.40%   98.89%   -0.51%     
==========================================
  Files           9        9              
  Lines         336      363      +27     
  Branches       38       46       +8     
==========================================
+ Hits          334      359      +25     
  Misses          1        1              
- Partials        1        3       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.