Wave 4 trailing convergence items (non-prerequisite, pre/post-SDK)

[CameronBrooks11]

Tracking issue for the Wave-4 trailing convergence items enumerated in the epic #40 "Deferred" section. Per the 0G readiness review these are explicitly not Wave-5 prerequisites ("can land concurrently or after") — they're cross-provider consistency polish best folded opportunistically into each provider's Wave-5 migration.

Items

• logging → sim's Logger — ezo/bread adopt sim's structured logger. — resolved: lifted into the SDK (provider_sdk/logging.hpp).
• config toolkit + DeviceSpec unification — sim adopts ezo/bread's config-validation toolkit shape.
• ezo runtime_state shrink — reduce ezo's value-snapshot RuntimeState toward bread's contract.
• error-mapping → bread 1-stage (ezo) — collapse ezo's 2-stage error mapping. — resolved: call-path collapsed in ezo#70; read-path item dropped (verification correction).
• DeviceDiscoveryStrategy contract — define a static-vs-scan discovery seam. — descoped: kept provider-local, not lifted (audit verdict).

Why one tracking issue

These are individually small and share a theme (cross-provider hygiene). The device-dispatch architectural prerequisite (the part that did gate Wave 5) is complete; these trailing items improve consistency but don't block extraction. Fold each into the relevant provider's Wave-5 migration where it reduces friction.

Part of the provider-SDK epic #40. See also the Wave-5 design addendum (working note).

[CameronBrooks11]

Pre-Wave-5 consistency audit (2026-06-24) — sequencing verdicts for these items (full pass: #49):

• logging → sim's Logger — confirmed net-new migration (ezo 14 + bread 31 call-sites; sim already runs the target at 54 sites). Fold into each provider's Wave-5 migration; parameterize the env-var name + macro prefix in the SDK.
• config toolkit + DeviceSpec unification — confirmed: ezo≡bread share a byte-identical validation toolkit sim lacks (converge sim toward ezo/bread). The DeviceSpec shape decision (typed-address vs sim's opaque map<string,YAML::Node>) is now a hard Tier-0 gate → Wave-5 design freeze: SDK DeviceSpec shape, quality hook, default_signal_ids contract (G3/G5/P5) #48 (G3). Tightening sim's root validation is a deliberate schema change — flag in CHANGELOG.
• ezo runtime_state shrink — confirmed toward bread's lean contract (move proto descriptors + per-call telemetry out of the snapshot; make snapshot() a pure const copy). During ezo's migration.
• error-mapping → bread 1-stage (ezo) — confirmed; promoted to a pre-extraction item (ezo P2, Wave-5 pre-extraction prep: enum relocation, 1-stage error mapping, handler delegation (P1/P2/P3) anolis-provider-ezo#70) because the lifted handler can't hold an internal i2c::StatusCode.
• DeviceDiscoveryStrategy contract — audit verdict: keep provider-local, do not lift. Discovery is inherently device-specific (ezo I2C identity vs bread CRUMBS scan vs sim factory); the SDK owns only the RuntimeState/startup-report data contract, not the discovery logic. Recommend marking this item defer/provider-local.

[CameronBrooks11]

Interim-doable subset (2026-06-25, while Wave-5 SDK extraction is on hold)

Since the SDK extraction is paused, landing the convergence items now is legitimate "reduce-future-reconciliation" work — EXCEPT the logging item. From a fresh C++-core audit:

• ezo runtime_state shrink — INTERIM-DOABLE (M). src/core/runtime_state.hpp:80-90 + snapshot() (runtime_state.cpp:418-433) deep-copies every device's two protobuf messages + signal vectors under the global mutex on every handler call. Shrink toward bread's leaner contract / shared_ptr<const>.
• ezo read-path error-map → 1-stage — INTERIM-DOABLE (M). The call path collapsed in ezo#70 Stage 1, but the read path still goes ezo_result_t → i2c::StatusCode (sample_helpers.cpp:16-35) → proto (handlers.cpp:65-84). Converge to bread's direct mapping (adapter_helpers.hpp:188-215).
• sim DeviceSpec/config-toolkit adoption — INTERIM-DOABLE (M) but lower urgency (coordinates with the SDK's shared config layer).
• logging → sim Logger — DEFER to Wave-5. Adopting sim's header now = migrating twice (sim → SDK). Also: sim's "canonical" Logger is NOT actually structured — it's plaintext-to-stderr and discards the __FILE__/__LINE__ the macro captures. Decide/fix that BEFORE any provider adopts it verbatim.
• DeviceDiscoveryStrategy stays provider-local (prior audit verdict).

The runtime_state shrink + read-path error-map are queued in the 2-week interim hardening plan.

[CameronBrooks11]

Verification correction — read-path item should be reworded or dropped

Verified against current ezo code (post-ezo#70): the read and call error-mapping paths are symmetric, not asymmetric. Both convert i2c::StatusCode → proto Status::Code at the adapter boundary — read_device_signals (handlers.cpp:427) and execute_safe_call (handlers.cpp:279) — and the handler never sees i2c::StatusCode on either path. There is no "call collapsed, read still 2-stage" gap; ezo#70 already made them the same shape.

The only residual is that i2c::StatusCode persists as the i2c/session transport vocabulary (status_from_ezo_result) on both paths equally; eliminating it means making all 7 device adapters emit proto directly — a larger cross-adapter refactor, not an interim asymmetry fix. Recommend: drop the read-path item (already done by ezo#70) or rescope it as that larger both-paths change.

Item 2 (ezo runtime_state deep-copy under the global mutex, runtime_state.cpp:418-433) — CONFIRMED exactly; stays interim-doable.

[CameronBrooks11]

ezo runtime_state shrink — deferring to Wave 5 (per this issue's "can land concurrently or after... folded opportunistically into each provider's Wave-5 migration").

Assessment during the interim-hardening pass (anolishq/.github#84 Phase 2): ezo's snapshot() deep-copies active_devices (each holding a proto capabilities + a mutating sample.signals) under the global mutex per call, and the read/call handlers only need one device (snapshot() then find_device()). A targeted snapshot_device(id) would avoid copying all devices — but:

• The read path is dominated by the I2C round-trip; the snapshot copy is marginal beside it (not a measured bottleneck).
• It's a concurrency-sensitive refactor (copy-then-use-pointer lifetime), and ezo's runtime is reworked in the Wave-5 ezo→SDK migration anyway (including the D1 residual — killing the internal double-only SignalSample). Doing it now means doing it twice.

So this folds into Wave 5 step 5 (ezo migration) rather than a speculative interim refactor. The other #44 items (logging→sim Logger, config-toolkit/DeviceSpec unification, error-map) likewise stay Wave-5-folded; the read/call error-map symmetry was already achieved in ezo#70.

[CameronBrooks11]

Annotation from Phase-D.1 planning (2026-06-25)

The config toolkit + DeviceSpec unification item is now pinned by the G3 decision (locked in the Wave-5 addendum "Phase D.1"):

• The SDK DeviceSpec spine is {id, label, type, extra} (composition). ezo/bread keep their typed numeric-address + cross-device dup-id/dup-address/range validation in their own config records; sim's free-form device schema lands in the opaque extra subtree, validated sim-side.
• So this item converges sim toward ezo/bread's validation toolkit shape without forcing a typed address into the shared spine (which would break sim) — fold it into sim's migration, not a prerequisite.

[CameronBrooks11]

Triage update: ticked the resolved/descoped items — logging (lifted to the SDK provider_sdk/logging.hpp), error-mapping (call-path collapsed in ezo#70; read-path item dropped per the verification correction above), and DeviceDiscoveryStrategy (kept provider-local per the audit verdict).

Still genuinely open, so not closing: config-toolkit / DeviceSpec unification and the ezo runtime_state shrink (documented-as-deferred in ezo#84, not yet implemented).