fix(multipart): honor declared part encodings

[samzong]

Summary

Closes #133.
Closes #135.

• Multipart parts now follow the declared schema instead of treating every non-file field as a string. Binary strings, type: file and empty {} schemas become file parts. Strings, numbers, integers and booleans become typed text parts. Objects become one JSON text part. Arrays of scalars or files become repeated parts with the same name.
• encoding.<property>.contentType is honored per part. A list or wildcard is resolved against the sniffed media type of each file. Invalid elements and header-breaking text are dropped at codegen. File parts always send Content-Type. Text parts send it only when the selected type is not exactly text/plain.
• OpenAPI binary parts without an encoding default to application/octet-stream. Swagger 2 type: file keeps the previous extension-based guess.
• A $ref property, a single-allOf wrapper around a $ref, and an allOf of object body schemas are resolved and merged into one set of part flags. Reference resolution is bounded and cycle-safe. An unresolved or cyclic reference is reported as unsupported and never becomes a file part.
• Optional properties that cannot be represented (an array of objects, an array of arrays, oneOf/anyOf only, an unresolved reference) are omitted. They are listed in the catalog as body.unsupported_fields and in the generated Skill reference.
• Codegen fails, naming the operation, in three cases:
  • a required property cannot be represented;
  • a required object body has no supported part;
  • the top-level multipart schema is not an object.
• Multipart commands no longer register the JSON body builder flags --file, --set and --set-str.
• Content-Disposition names and filenames escape \, ", CR and LF, matching the current Go mime/multipart rule. Unsupported property names and part content types are escaped in generated Skill Markdown.

Verification

• make check passed.

• go test -race ./pkg/runtime/... ./internal/codegen/... ./internal/lathecmd/... passed.

• Wire tests parse real multipart requests. They cover typed text parts, repeated array parts, JSON object parts, and declared, wildcard and listed part content types. They also check that a missing required file fails before auth, that --set is rejected, and that Content-Disposition escapes CR/LF.

• Codegen tests cover:

  • Swagger 2 and OpenAPI 3 part shapes;
  • $ref, allOf and merged bodies;
  • missing references for a property and for array items, reported in unsupported_fields;
  • required unsupported properties and unrepresentable bodies failing codegen;
  • Skill rendering of unsupported properties and part content types.

• In a scratch copy of the petstore example, a local server received:

  • image/png for a .png file declared as image/png, image/jpeg;
  • image/gif for a .gif file and application/octet-stream for a .txt file declared as image/*;
  • application/json for an object part;
  • repeated parts for an array.

  A missing required file exited with code 2, and --dry-run omitted the multipart body.

• A scratch petstore regeneration built, and __lathe verify --json returned ok: true.

• An independent review exercised the staged diff over several rounds. Its findings were fixed and re-verified.

Not verified: interoperability with server frameworks other than Go net/http multipart parsing.

Compatibility

• runtime.SchemaVersion 22 and runtime.CatalogSchemaVersion 29. Regenerate downstream CLIs.
• The catalog adds flags[].content_type for multipart flags and body.unsupported_fields.
• After regeneration, multipart flags change type to match the schema (for example int64, bool or repeatable values). Multipart commands lose --file, --set and --set-str.
• Specs that previously generated a multipart command with a required unsupported property, or with a non-object multipart schema, now fail codegen. Ignore that command in an overlay or fix the spec.
• OpenAPI 3 binary parts without an encoding now send application/octet-stream instead of a type guessed from the file extension.

Checklist

• Tests or focused verification cover the changed surface.
• User-facing behavior changes are documented.
• Generated output under internal/generated/, .cache/, and ad-hoc skills/<cli-name>/ directories is not committed.
• Commits are signed off when this is ready to merge.

[codspeed]

Merging this PR will improve performance by 76.36%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 21 improved benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	BenchmarkBuildFlat	2.2 ms	1 ms	×2.1
⚡	yaml	4.9 ms	2.5 ms	+93.62%
⚡	BenchmarkFormatTableInferredColumns	1,102.2 µs	611.3 µs	+80.3%
⚡	large	2.2 ms	1.2 ms	+79.58%
⚡	large	1,552.8 µs	870.3 µs	+78.43%
⚡	json-large	3.4 ms	1.9 ms	+78.02%
⚡	yaml-large	14.3 ms	8.1 ms	+77.62%
⚡	table	710.6 µs	403.2 µs	+76.23%
⚡	miss	3.4 ms	2 ms	+76.13%
⚡	hit	3.5 ms	2 ms	+75.77%
⚡	small	137.2 µs	78.9 µs	+73.79%
⚡	small	114 µs	65.7 µs	+73.41%
⚡	BenchmarkCatalogJSON	2.8 ms	1.6 ms	+72.78%
⚡	large	2.3 ms	1.3 ms	+72.56%
⚡	json	1,216.5 µs	705.5 µs	+72.42%
⚡	BenchmarkParseNormalize	7.1 ms	4.1 ms	+72.36%
⚡	large	1,542 µs	896.3 µs	+72.04%
⚡	BenchmarkFindCatalogCommand	7.8 µs	4.6 µs	+70.31%
⚡	small	178.8 µs	105.8 µs	+69.04%
⚡	json-small	241.3 µs	145.3 µs	+66.12%
...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing fix/multipart-part-encoding (e2390bc) with main (acb5b7f)}