Property-based coverage for the structured logging hook (cuprum/adapters/logging_adapter.py)

[leynos]

Overview

Add property-based coverage for the structured logging hook in
cuprum/adapters/logging_adapter.py, closing the last gap left by issue #78.

Background

Issue #78 is titled "Hypothesis stateful tests for metrics/tracing/logging
hooks", but its body scopes the work to cuprum/adapters/metrics_adapter.py.
Taking the title at its word, the three adapters now stand as follows:

Adapter	Randomised event-sequence coverage
tracing_adapter.py	cuprum/unittests/test_tracing_span_stateful.py (pre-existing)
metrics_adapter.py	cuprum/unittests/test_metrics_adapter_stateful.py (added in #247)
logging_adapter.py	none

So only the logging hook is outstanding.

Why a state machine is the wrong shape here

RuleBasedStateMachine earns its keep in the other two adapters because both
hold an active map keyed by ExecId — TracingHook._active_spans and the
metrics collector's in-flight state — and the interesting bugs are drain and
correlation bugs across interleaved sequences.

structured_logging_hook has no such state. It is a pure per-event function:
it maps a phase to a level, builds an extra mapping, formats a message, and
emits exactly one record. There is no map to drain and no cross-event
correlation to break, so a state machine would generate interleavings that
cannot distinguish any two implementations.

@given over generated ExecEvent values (and short sequences) is the shape
that actually tests the behaviour.

Proposed properties

• One record per event. Every event emits exactly one LogRecord; no
  phase is silently dropped.
• Level mapping is total. The level_map in logging_adapter.py:108
  covers every phase the event model can produce, and an unmapped phase falls
  back to the documented default rather than raising.
• Field namespacing. Every attribute _build_extra attaches is
  cuprum_-prefixed, so records cannot collide with LogRecord's reserved
  attribute names — this is the failure mode that would surface as a
  KeyError at emit time deep in a user's logging configuration.
• JSON round-trip. For any event, JsonLoggingFormatter.format produces
  a string that json.loads accepts, and _json_serializable leaves no value
  that json.dumps would reject.
• Message formatting is total. _format_message produces a non-empty
  string for every phase, including events with absent optional fields.

Benefit

The JSON round-trip and field-namespacing properties are the valuable ones:
both fail only for specific event shapes that hand-written tests are unlikely
to enumerate, and both fail inside the user's logging stack rather than in
cuprum, which makes them expensive to diagnose in the field.

Cost trade-off

Low. The event strategies already exist in
cuprum/unittests/test_metrics_adapter_stateful.py and can be shared.

Recommended order

After the current property-test tranche lands. No production refactor is
needed first — unlike the metrics work, the logging reducers are already pure.

---

Raised from PR #247, which closes the
metrics portion of #78.

[coderabbitai]

🔗 Related PRs

#144 - Fix Command-Query Separation violations (#118) [merged]
#149 - Guard TracingHook against recycled-PID span orphaning (#122) [merged]
#154 - De-duplicate adapter event projection and collector base (#114) [merged]
#225 - Property tests for benchmark comparison and folded ranking reducers (#76, #77) [merged]
#227 - Direct tests for the Unix write loop, error taxonomy, and stream handle (#85, #104) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

Delivered in #247 rather than as separate work.

The Linked Issues check on #247 kept flagging that #78's title covers logging, so closing the gap there was cheaper than continuing to defer it. cuprum/unittests/test_logging_adapter_properties.py implements the five properties specified here:

• one record per event, so no phase is silently dropped;
• each phase logs at its configured level, with an unknown phase falling back rather than raising;
• every attached field is cuprum_-prefixed, so it cannot shadow a reserved LogRecord attribute;
• _format_message is total, returning a namespaced non-empty string for any phase;
• records survive JsonLoggingFormatter and round-trip through json.loads.

The shape argument in this issue held up: these are @given properties, not a state machine, because structured_logging_hook carries nothing between events.

One correction to what I wrote here. This issue predicted the field-namespacing and JSON round-trip properties would be "the valuable ones". They were, but not for the reason given — both were vacuous as first written and passed against a deliberately broken formatter. ExecEvent.tags is typed Mapping[str, object], and generating only string values never exercised _json_serializable or default=str at all. Mutation testing caught that; reading the tests did not.