Isolate vendor-specific tracing from domain logic behind adapter boundaries

[coderabbitai]

Background

Raised during review of PR #303 by @leynos.

Domain functions in src/wrap/inline/ and src/wrap/tokenize/ currently import and use the vendor-specific tracing framework directly (#[tracing::instrument], debug!, trace!, tracing::enabled!). This couples infrastructure concerns to domain logic, making the domain harder to test without a tracing subscriber and harder to migrate to a different observability backend in the future.

Required work

1. Define domain-level event types — e.g. enum ClassificationEvent — that capture the observable outcomes of classification and parsing decisions without referencing any external crate.
2. Refactor classification functions (classify_fragment_kind, parse_link_or_image, find_footnote_end, the footnote predicate helpers) to accept an optional observer (e.g. a callback or a trait object implementing an Observer trait) and emit domain events through it, rather than emitting tracing calls inline.
3. Implement a tracing-backed adapter that translates ClassificationEvent values into the appropriate debug!/trace! calls. Wire this adapter at the library boundary so existing instrumented behaviour is preserved.
4. Remove direct tracing imports from all domain modules; retain the dependency only in the adapter layer and in [dev-dependencies] for tests.

Acceptance criteria

• No use tracing:: import appears inside domain modules (src/wrap/inline/, src/wrap/tokenize/).
• Domain functions can be called without any tracing subscriber installed and without any enabled! guard (all guards move to the adapter).
• Existing traced-event tests continue to pass via the adapter.
• Linters and tests pass under make test.

References

• PR Add observability for inline wrapping token classification (#296) #303
• Issue Add observability infrastructure for inline-wrapping token classification #296

[coderabbitai]

🔗 Related PRs

leynos/tei-rapporteur#79 - Use named validation BDD scenarios (#34) [closed]
leynos/actix-v2a#30 - Update documentation after the SSE module lands (1.2.2) [merged]
leynos/ortho-config#327 - Accept Cargo orthohelp dispatch (#326) [merged]
#295 - Couple opening brackets with following inline code spans (#293) [merged]
#301 - Keep GFM footnote references with preceding code and link spans (#299) [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.}

---

🧪 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]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Introduce a domain-owned Observer trait and Event enum in src/wrap/observer.rs to decouple observability from infrastructure.
• Refactor the five instrumented functions to accept Option<&mut dyn Observer> and emit domain events rather than calling tracing directly.
• Implement TracingObserver in src/wrap/tracing_adapter.rs to translate events back into debug!/trace! calls, preserving existing instrumented behaviour.
• Wire the adapter at the wrap_text boundary and update tests to exercise the full path, leaving domain modules free of any tracing imports.

Design Choices

Design Choice 1: Observer threading strategy

Options Considered:

1. Option<&mut dyn Observer> parameter on each instrumented function — explicit, zero-cost when None.
2. Thread-local / global observer registry — avoids signature changes but introduces hidden coupling.
3. Generic O: Observer parameter — monomorphises but complicates dynamic dispatch.

Chosen Option: 1

Rationale: Explicit optional trait object parameter. It keeps the domain free of hidden state and aligns with the existing pattern of passing data explicitly through function arguments.

Design Choice 2: Event representation

Options Considered:

1. Single enum Event<'a> with variants for each observable outcome, plus a single observe(&mut self, event: Event<'_>) method on the trait.
2. Multiple methods on the trait, one per event type (e.g., on_footnote_parsed, on_fragment_classified).

Chosen Option: 1

Rationale: Single enum plus single method. It is more extensible (new variants require no trait changes) and matches the ticket's explicit "enum ClassificationEvent" example.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Define Observer Abstraction

Introduce the domain-level observer trait and event enum. Place these types at the adapter boundary so domain modules can depend on them without importing external crates.

Task 1: Create observer module with trait and event enum

Define the abstraction that domain functions will emit events through.

• Create src/wrap/observer.rs containing:
  • pub enum Event<'a> with variants mirroring current tracing calls: FootnoteReferenceParsed, LinkOrImageParsed, FootnoteEndNotFound, FootnoteLabelRecognized, FootnoteRefChecked, FragmentClassified.
  • Each variant carries the structured fields currently passed to debug!/trace! (e.g., token: &'a str, is_image: bool, kind, reason).
  • pub trait Observer { fn observe(&mut self, event: Event<'_>); } as the single observation method.
• Declare the module in src/wrap.rs with pub(crate) visibility so it is accessible to domain modules but not exported from the crate.

Task 2: Provide a no-op observer implementation

Supply a default observer that discards events, useful when callers do not require observation.

• Add pub struct NoOpObserver; implementing Observer with an empty observe body.
• Place this in src/wrap/observer.rs alongside the trait.

🤖 Prompt for AI agents

Implement the domain-level observer abstraction in a new module, providing the
trait, event enum, and a no-op implementation.

- Create `src/wrap/observer.rs` with the following:
- Define `pub enum Event<'a>` with variants mirroring all current tracing
call-sites: `FootnoteReferenceParsed`, `LinkOrImageParsed`,
`FootnoteEndNotFound`, `FootnoteLabelRecognized`, `FootnoteRefChecked`,
`FragmentClassified`
- Each variant must carry the structured fields currently passed to
`debug!`/`trace!` macros (e.g., `token: &'a str`, `is_image: bool`, `kind`,
`reason`)
- Define `pub trait Observer { fn observe(&mut self, event: Event<'_>); }` as
the single observation method
- Define `pub struct NoOpObserver;` and implement `Observer` for it with an
empty `observe` body
- In `src/wrap.rs`, declare the module with `pub(crate)` visibility so domain
modules can access it without exporting it from the crate

Phase 2: Refactor Domain Functions to Emit Events

Modify instrumented functions to accept an optional observer and emit domain events instead of calling tracing directly. Remove all #[tracing::instrument] attributes and tracing::* imports from domain modules.

Task 1: Refactor parsing helpers in tokenize module

Update parse_link_or_image and find_footnote_end to use the observer.

• In src/wrap/tokenize/parsing.rs:
  • Add parameter observer: Option<&mut dyn Observer> to parse_link_or_image and find_footnote_end.
  • Replace each if tracing::enabled!(...) { debug!/trace!(...) } block with if let Some(obs) = observer.as_deref_mut() { obs.observe(Event::...); }.
  • Remove #[tracing::instrument] attributes from both functions.
  • Remove use tracing::{debug, trace}; import.

Task 2: Refactor predicate helpers in inline module

Update looks_like_footnote_ref and ends_with_footnote_ref to emit events.

• In src/wrap/inline/predicates.rs:
  • Add parameter observer: Option<&mut dyn Observer> to both functions.
  • After computing the boolean result, emit Event::FootnoteRefChecked { token, result } via the observer.
  • Remove #[tracing::instrument] attributes.
  • Remove any tracing imports (currently only the attribute path is used).

Task 3: Refactor fragment classification in inline module

Update classify_fragment and log_fragment_classification to use the observer.

• In src/wrap/inline/fragment.rs:
  • Inline log_fragment_classification into the classification flow or convert it to accept observer: Option<&mut dyn Observer>.
  • Replace the if tracing::enabled!(DEBUG) { debug!(...) } block with an observer call emitting Event::FragmentClassified { ... }.
  • Remove use tracing::debug; import.
  • Update InlineFragment::new to accept and forward the observer.

Task 4: Thread observer through internal call sites

Propagate the observer parameter up through callers so events flow from domain functions to the adapter boundary.

• In src/wrap/tokenize/mod.rs:
  • Update segment_inline signature to accept observer: Option<&mut dyn Observer>.
  • Pass the observer to parse_link_or_image calls.
• In src/wrap/inline.rs:
  • Update build_fragments to accept and forward the observer to InlineFragment::new.
  • Update determine_token_span calls to predicate helpers (looks_like_footnote_ref) to pass the observer.
  • Update wrap_preserving_code to accept the observer and pass it to segment_inline and build_fragments.
• In src/wrap/inline/span_helpers.rs:
  • Update try_couple_footnote_reference to accept and forward the observer to looks_like_footnote_ref.

🤖 Prompt for AI agents

Refactor all instrumented domain functions across `src/wrap/tokenize/` and
`src/wrap/inline/` to accept an optional observer and emit domain events,
removing all direct `tracing` usage.

**`src/wrap/tokenize/parsing.rs`**
- Add `observer: Option<&mut dyn Observer>` parameter to `parse_link_or_image`
and `find_footnote_end`
- Replace every `if tracing::enabled!(...) { debug!/trace!(...) }` block with
`if let Some(obs) = observer.as_deref_mut() { obs.observe(Event::...); }`
- Remove `#[tracing::instrument]` attributes from both functions
- Remove `use tracing::{debug, trace};` import

**`src/wrap/inline/predicates.rs`**
- Add `observer: Option<&mut dyn Observer>` parameter to
`looks_like_footnote_ref` and `ends_with_footnote_ref`
- After computing the boolean result, emit `Event::FootnoteRefChecked { token,
result }` via the observer
- Remove `#[tracing::instrument]` attributes and any `tracing` imports

**`src/wrap/inline/fragment.rs`**
- Inline `log_fragment_classification` into the classification flow or convert
it to accept `observer: Option<&mut dyn Observer>`
- Replace the `if tracing::enabled!(DEBUG) { debug!(...) }` block with an
observer call emitting `Event::FragmentClassified { ... }`
- Remove `use tracing::debug;` import
- Update `InlineFragment::new` to accept and forward the observer

**Thread the observer upward through callers:**
- In `src/wrap/tokenize/mod.rs`: update `segment_inline` to accept `observer:
Option<&mut dyn Observer>` and pass it to `parse_link_or_image` calls
- In `src/wrap/inline.rs`: update `build_fragments` and `wrap_preserving_code`
to accept and forward the observer; pass it to `segment_inline`,
`build_fragments`, `InlineFragment::new`, and `looks_like_footnote_ref`
call-sites
- In `src/wrap/inline/span_helpers.rs`: update `try_couple_footnote_reference`
to accept and forward the observer to `looks_like_footnote_ref`

Phase 3: Implement Tracing Adapter and Wire at Boundary

Create the adapter that translates domain events into tracing calls and wire it at the top-level entry point so existing behaviour is preserved.

Task 1: Implement TracingObserver adapter

Translate domain events to tracing instrumentation.

• Create src/wrap/tracing_adapter.rs containing:
  • use tracing::{debug, trace}; and the tracing::enabled! guards.
  • pub struct TracingObserver; implementing Observer.
  • In observe, match on Event variants and emit the corresponding debug!/trace! calls with the same structured fields currently used.
  • Preserve the tracing::enabled! guards so allocations are still avoided when the level is disabled.
• Declare the module in src/wrap.rs.

Task 2: Wire adapter at library boundary

Instantiate and pass the TracingObserver from the public API entry point.

• In src/wrap.rs or src/wrap/paragraph.rs (wherever wrap_preserving_code is invoked):
  • Instantiate TracingObserver and pass Some(&mut observer) down the call chain.
• Confirm that the existing behaviour (tracing events emitted at DEBUG/TRACE levels) is preserved when a tracing subscriber is installed.

Task 3: Update existing tracing tests to exercise adapter path

Ensure the tracing_tests modules continue to pass via the adapter.

• In src/wrap/tokenize/parsing.rs, src/wrap/inline/predicates.rs, src/wrap/inline/fragment.rs:
  • Update test helpers to instantiate TracingObserver and pass it to the refactored functions.
  • Verify logs_contain(...) assertions still pass, confirming the adapter emits the expected tracing events.
• Move the tracing_test import (and any use tracing::* needed solely for tests) into #[cfg(test)] blocks or the adapter module so domain modules remain tracing-free in production builds.

Task 4: Final cleanup and verification

Remove residual tracing artefacts from domain modules and run full test suite.

• Audit src/wrap/inline/ and src/wrap/tokenize/ for any remaining use tracing:: imports; remove them.
• Run make test to confirm all linters and tests pass.
• Confirm acceptance criteria:
  • No use tracing:: in domain modules.
  • Domain functions callable without a tracing subscriber.
  • Existing traced-event tests pass.

🤖 Prompt for AI agents

Create the `TracingObserver` adapter that translates domain `Event` variants
into `tracing` macro calls, wire it at the library boundary, update tests to
exercise the full path, and perform final cleanup.

**`src/wrap/tracing_adapter.rs`** (new file)
- Add `use tracing::{debug, trace};` and use `tracing::enabled!` guards
- Define `pub struct TracingObserver;` implementing `Observer`
- In the `observe` method, match on every `Event` variant and emit the
corresponding `debug!`/`trace!` call with the same structured fields that were
previously used at each call-site
- Preserve `tracing::enabled!` guards to avoid unnecessary allocations when the
level is disabled
- Declare the module in `src/wrap.rs`

**Wire at the library boundary**
- In `src/wrap.rs` or `src/wrap/paragraph.rs` (wherever `wrap_preserving_code`
is invoked), instantiate `TracingObserver` and pass `Some(&mut observer)` down
the call chain
- Verify the existing behaviour (tracing events emitted at DEBUG/TRACE levels)
is preserved when a tracing subscriber is installed

**Update tests**
- In test modules within `src/wrap/tokenize/parsing.rs`,
`src/wrap/inline/predicates.rs`, and `src/wrap/inline/fragment.rs`, update test
helpers to instantiate `TracingObserver` and pass it to the refactored functions
- Verify all `logs_contain(...)` assertions still pass
- Move the `tracing_test` import and any `use tracing::*` required only for
tests into `#[cfg(test)]` blocks or the adapter module

**Final cleanup**
- Audit `src/wrap/inline/` and `src/wrap/tokenize/` for any remaining `use
tracing::` imports and remove them
- Run `make test` to confirm all linters and tests pass
- Confirm: no `use tracing::` in domain modules; domain functions are callable
without a tracing subscriber; all existing traced-event tests pass

Research

The tracing dependency is confined to three files within the wrap subsystem: src/wrap/tokenize/parsing.rs, src/wrap/inline/fragment.rs, and src/wrap/inline/predicates.rs. These files use #[tracing::instrument] attributes, debug!/trace! macros, and tracing::enabled! guards. The instrumented functions form a call chain originating from wrap_preserving_code (which calls segment_inline → parse_link_or_image → find_footnote_end) and InlineFragment::new (which calls classify_fragment → predicate helpers). No trait definitions or abstraction layers exist in the codebase currently; the tracing dependency is always compiled in as there are no Cargo features defined.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the domain-level observer abstraction in a new module, providing the
trait, event enum, and a no-op implementation.

- Create `src/wrap/observer.rs` with the following:
- Define `pub enum Event<'a>` with variants mirroring all current tracing
call-sites: `FootnoteReferenceParsed`, `LinkOrImageParsed`,
`FootnoteEndNotFound`, `FootnoteLabelRecognized`, `FootnoteRefChecked`,
`FragmentClassified`
- Each variant must carry the structured fields currently passed to
`debug!`/`trace!` macros (e.g., `token: &'a str`, `is_image: bool`, `kind`,
`reason`)
- Define `pub trait Observer { fn observe(&mut self, event: Event<'_>); }` as
the single observation method
- Define `pub struct NoOpObserver;` and implement `Observer` for it with an
empty `observe` body
- In `src/wrap.rs`, declare the module with `pub(crate)` visibility so domain
modules can access it without exporting it from the crate
===============================================================================

Task: 2

Refactor all instrumented domain functions across `src/wrap/tokenize/` and
`src/wrap/inline/` to accept an optional observer and emit domain events,
removing all direct `tracing` usage.

**`src/wrap/tokenize/parsing.rs`**
- Add `observer: Option<&mut dyn Observer>` parameter to `parse_link_or_image`
and `find_footnote_end`
- Replace every `if tracing::enabled!(...) { debug!/trace!(...) }` block with
`if let Some(obs) = observer.as_deref_mut() { obs.observe(Event::...); }`
- Remove `#[tracing::instrument]` attributes from both functions
- Remove `use tracing::{debug, trace};` import

**`src/wrap/inline/predicates.rs`**
- Add `observer: Option<&mut dyn Observer>` parameter to
`looks_like_footnote_ref` and `ends_with_footnote_ref`
- After computing the boolean result, emit `Event::FootnoteRefChecked { token,
result }` via the observer
- Remove `#[tracing::instrument]` attributes and any `tracing` imports

**`src/wrap/inline/fragment.rs`**
- Inline `log_fragment_classification` into the classification flow or convert
it to accept `observer: Option<&mut dyn Observer>`
- Replace the `if tracing::enabled!(DEBUG) { debug!(...) }` block with an
observer call emitting `Event::FragmentClassified { ... }`
- Remove `use tracing::debug;` import
- Update `InlineFragment::new` to accept and forward the observer

**Thread the observer upward through callers:**
- In `src/wrap/tokenize/mod.rs`: update `segment_inline` to accept `observer:
Option<&mut dyn Observer>` and pass it to `parse_link_or_image` calls
- In `src/wrap/inline.rs`: update `build_fragments` and `wrap_preserving_code`
to accept and forward the observer; pass it to `segment_inline`,
`build_fragments`, `InlineFragment::new`, and `looks_like_footnote_ref`
call-sites
- In `src/wrap/inline/span_helpers.rs`: update `try_couple_footnote_reference`
to accept and forward the observer to `looks_like_footnote_ref`
===============================================================================

Task: 3

Create the `TracingObserver` adapter that translates domain `Event` variants
into `tracing` macro calls, wire it at the library boundary, update tests to
exercise the full path, and perform final cleanup.

**`src/wrap/tracing_adapter.rs`** (new file)
- Add `use tracing::{debug, trace};` and use `tracing::enabled!` guards
- Define `pub struct TracingObserver;` implementing `Observer`
- In the `observe` method, match on every `Event` variant and emit the
corresponding `debug!`/`trace!` call with the same structured fields that were
previously used at each call-site
- Preserve `tracing::enabled!` guards to avoid unnecessary allocations when the
level is disabled
- Declare the module in `src/wrap.rs`

**Wire at the library boundary**
- In `src/wrap.rs` or `src/wrap/paragraph.rs` (wherever `wrap_preserving_code`
is invoked), instantiate `TracingObserver` and pass `Some(&mut observer)` down
the call chain
- Verify the existing behaviour (tracing events emitted at DEBUG/TRACE levels)
is preserved when a tracing subscriber is installed

**Update tests**
- In test modules within `src/wrap/tokenize/parsing.rs`,
`src/wrap/inline/predicates.rs`, and `src/wrap/inline/fragment.rs`, update test
helpers to instantiate `TracingObserver` and pass it to the refactored functions
- Verify all `logs_contain(...)` assertions still pass
- Move the `tracing_test` import and any `use tracing::*` required only for
tests into `#[cfg(test)]` blocks or the adapter module

**Final cleanup**
- Audit `src/wrap/inline/` and `src/wrap/tokenize/` for any remaining `use
tracing::` imports and remove them
- Run `make test` to confirm all linters and tests pass
- Confirm: no `use tracing::` in domain modules; domain functions are callable
without a tracing subscriber; all existing traced-event tests pass

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!