[Bug]: SDK: align public annotations with runtime behavior

Describe the bug

This consolidates 17 related SDK contract-audit reports into one issue. Sorry for the volume of individual reports. They are closed as superseded, not fixed; each linked report retains its reproduction, controls, environment, and pinned source references.

Public annotations sometimes accept inputs that the implementation rejects, exclude supported inputs, or describe a different return shape. This affects static checking and consumers deriving API contracts from those annotations. A few findings are runtime defects in handling explicitly supported input types rather than annotation-only corrections.

Findings

Optionality, defaults, and overloads

• #12782 — Table(log_mode=None) is admitted by LogMode | None but rejected by validation; omission and the three string modes work.
• #12783 — Artifact.add_file/add_dir(skip_cache=None) is admitted by bool | None but rejected by the shared non-nullable manifest field; boolean controls work.
• #12784 — RunEvent.metric(...).changes_by/increases_by/decreases_by overloads require both diff and frac, while the supported calling forms supply exactly one.
• #12795 — OpenAI fine-tuning WandbLogger.sync declares str but returns None on its already-synced, no-overwrite path.
• #12796 — wandb.controller().sweep_config omits None from its return annotation during the supported deferred-creation state.
• #12798 — Ultralytics add_wandb_callback(max_validation_batches=None) advertises None but validation reaches min(None, batch_count); the default-1 control succeeds.
• #12799 — Fabric WandbLogger(save_dir=None), including the dir alias, works but is excluded by the constructor annotation.

Container, value, and return types

• #12785 — plot.line_series advertises arbitrary outer Iterable values for xs, ys, and keys, but indexing/length operations reject ordinary iterators.
• #12786 — plot.pr_curve advertises one-dimensional probabilities while requiring two-dimensional input; the advertised general label iterable also rejects ordinary iterators.
• #12787 — BoundingBoxes2D.to_json/from_json annotate dictionaries where the existing artifact representation is a list of box dictionaries.
• #12789 — Video advertises TextIO, but its stream branch supports BytesIO and rejects text streams.
• #12790 — Trace.metadata/inputs/outputs property annotations restrict dictionary values to strings, although numeric and nested values are supported and returned unchanged.
• #12793 — RunQueue.template_variables, external_links, and access annotations disagree with the returned list, nested dictionary, and uppercase access value shown in upstream tests.
• #12794 — OpenAI fine-tuning WandbLogger.sync(**kwargs_wandb_init) annotates each forwarded value as a dictionary, rejecting documented scalar/list wandb.init options in static checking.
• #12797 — LaunchAgent.thread_ids and finish_thread_id annotate integers, while normal bookkeeping and cleanup exchange string queue-item IDs.

Runtime handling of supported inputs

• #12791 — Molecule(Path(...)) drops parent directories via .name; the equivalent full string path works.
• #12792 — Bokeh(Document(...)) accepts a valid nonempty document but leaves media unset and serializes no data/path; the equivalent model control works.

Expected behavior

Make public signatures, annotations, documentation, and supported runtime behavior agree. Preserve intentional defaults and existing serialization formats. Where an advertised input is rejected, the report does not assume that widening runtime acceptance is preferable to correcting the annotation, nor prescribe a shared meaning for None.

The checkboxes represent unresolved findings; closing the original reports is only consolidation.

Verification and environment

• W&B SDK: 0.30.0, with each finding also reproduced on or source-compared against main at 8f93d444.
• Python: 3.12.12 for the expanded audit; 3.13.5 for the original Table release reproduction.
• OS: macOS 26.1, arm64. Optional dependency versions and any compatibility accommodations are recorded in the individual reports.
• Checks used local/offline objects and disabled runs where applicable. Some service-dependent paths used simulated external collaborators, explicitly identified in their reports; these are not live-backend results.
• No authenticated W&B server operations or cloud jobs were performed. The full upstream test suite and hosted CI were not run; this is a bounded audit, not a claim of complete annotation coverage.

The separately existing paginator work in #12402 was identified during review and is not duplicated in this checklist.