v0.17.0 remaining work

[chris-colinsky]

Tracking issue. The session's task list is gone, so this is the durable index of what is left for v0.17.0.

Blocked on spec

The pin cannot move until proposals land. Released spec is still v0.112.0, which is our current pin.

• 0119 error-message byte cap + reserved metadata keys — Draft
• 0120 where a directive definition may live — Draft
• 0121 stable event names on the two mandated §6 diagnostics + the otel_observer directive — Draft
• 0122 extras surface as a named container + clause-(b) enumerations — Draft
• 0123 case-level subgraphs: declaration — Draft
• 0124 orphan provider span parent resolution — Draft
• 0125 invariant predicate vocabulary — under discussion, may not make this release

Once accepted: bump the pin, adopt, regenerate AGENTS.md, run the full suite (not just unit + conformance).

Landed since this issue was written

• Fix two branch dispatch key defects in the observers #276 two branch dispatch key defects in the observers
• Resolve orphan provider span parents structurally, wire 152/153 #277 orphan provider span parents resolved structurally, fixtures 152/153
• Key branch dispatch spans by depth, not the innermost scalar #283 branch dispatch spans keyed by depth, not the innermost scalar (closes Branch dispatch spans key off the innermost scalar branch_name, not the chain position #278)
• Key fan-out execution state by branch as well as fan-out lineage #284 fan-out execution state keyed by branch as well as fan-out lineage (closes Fan-out execution state collides across sibling parallel branches, returning silently wrong results #282, a silent data-corruption defect found by an adversarial review of Key branch dispatch spans by depth, not the innermost scalar #283)
• Recover the subgraph identity and caller metadata a short-circuiting wrapper loses #285 subgraph identity and caller metadata recovered for a short-circuiting wrapper (closes gaps 1 and 2 of Orphan-synthesized dispatch spans lose attributes when the wrapper short-circuits #279)
• Guard the detached instance root on the key it is stored under #286 detached instance root guarded on the key it is stored under — step 1 of the four-step Orphan-synthesized dispatch spans lose attributes when the wrapper short-circuits #279 gap-3 rework

None of the five touched CHANGELOG except #284 and #285, which is tracked below.

Actionable now

• Orphan-synthesized dispatch spans lose attributes when the wrapper short-circuits #279 gap 3 only — the detached-trace half. Gaps 1 and 2 shipped in Recover the subgraph identity and caller metadata a short-circuiting wrapper loses #285. An attempt at gap 3 was reverted after an adversarial review found four blockers; the issue carries them and an ordered four-step plan. Step 1 landed in Guard the detached instance root on the key it is stored under #286. Steps 2-4 are PARKED pending a spec answer on which lineage attribution a span synthesized from a provider event is entitled to (coord release-v0.17.0/47). Step 2 needs a fourth event-surface addition, and a subgraph node emits no event at its own namespace, so there is no local fix. A narrower option stays available: mirror only the detached fan-out arm, closing most of gap 3 with no event-surface change.
• Harden the orphan-fallback conformance driver and the handler-enumeration guard #280 harden the orphan-fallback driver and the handler-enumeration guard
• Fixture 119 the last conformance gap — needs YAML middleware: translation in adapter.py plus threading per_node_mw into add_parallel_branches_node
• CHANGELOG backfill — Fix two branch dispatch key defects in the observers #276, Resolve orphan provider span parents structurally, wire 152/153 #277 and Key branch dispatch spans by depth, not the innermost scalar #283 changed user-visible trace output and added no entry. Key fan-out execution state by branch as well as fan-out lineage #284, Recover the subgraph identity and caller metadata a short-circuiting wrapper loses #285 and Guard the detached instance root on the key it is stored under #286 all carry entries, so the list is still these three. A release bakes the changelog into the notes, so this gates the tag. Needs a fresh git log sweep from the previous tag rather than trusting that list of three
• Register the 4 shared drivers in _DRIVER_EXPECTED_KEYS, or derive it transitively. The guard is fail-open, so 4 shared drivers covering 17 fixtures are currently exempt
• Double-vs-adapter fidelity sweep for InMemoryLangfuseClient. Two known instances: usage omission spelled None in the double vs key-absence on the wire, and trace.id derivation. Correctness-of-evidence, not housekeeping

Deferred past this release, with reasons

• Give every dispatched branch a chain position — spec ruled on it (coord release-v0.17.0/40); the proposal lands after v0.17.0. Until then the scalar clauses in is_outermost_serial are load-bearing and must not be removed
• Checkpoint record under-describes fan-out lineage — the fan-out half is ours to build; the branch half needs a spec-governed record-format change, under discussion in coord 44
• Consolidate the remaining duplicated lineage logic across the two observers — wait for the chain-position change, which may simplify the shared rules
• conformance.toml note-style normalization — its own PR
• Langfuse set_trace_io deprecation — no clean non-deprecated path; needs spec

Release prep

• Reconcile stale pin claims in CHANGELOG and conformance.toml
• Docs sweep and examples review — both partly invalidated by the pin bump, so do them after
• Version bump 0.16.0 → 0.17.0, then the rc-first flow in RELEASING.md
• The batched spec review is gating: hold the tag for spec's response and fold any ruling into this release

[chris-colinsky]

Scope decision: cut off at 0124

0125 (invariant predicate vocabulary) is OUT of v0.17.0. The release adopts 0119 through 0124 and stops there. No further scope.

The 0125 discussion continues in the coord thread discuss-invariants-documentary-vs-asserted on its own clock — it settles how the invariants: surface expresses assertable-versus-documentary, which is a corpus-wide question and not something to land under a release deadline.

Nothing else in this issue changes. The actionable list and release prep stand as written.