refactor(codec)!: location/read/redact handler API

[martsokha]

Summary

Ground-up redesign of the codec around locations as the cross-boundary identifier. Handlers no longer yield content tuples; they expose cheap identity (locations()), on-demand typed reads (read(&L)), and direct batch redaction (redact(Redactions<L, R>)).

Earlier commits on this branch landed Redactions<S, R> as a grouped, overlap-aware collection. This PR builds on that to remove the rest of the Span-based reading/editing pipeline.

Shape

Types

• Located<L> { source: ContentSource, location: L } — handlers tag every location they emit with their ContentSource, so provenance travels alongside identity without polluting the location's PartialEq.
• LocationStream<'a, L> — replaces SpanStream<'a, Id, Data>. Cheap to enumerate; no payload allocation.
• Span<L, D> { source, location, data } — same name and shape as before, but not on handler traits. Codec utility for callers that want enumerate-with-content.

Handler capability traits (TextHandler / ImageHandler / AudioHandler)

trait TextHandler: Handler {
    fn locations(&self) -> LocationStream<'_, TextLocation>;
    async fn read(&self, loc: &TextLocation) -> Option<TextData>;
    async fn redact(&mut self, redactions: Redactions<TextLocation, TextRedaction>) -> Result<()>;
}

The *Transform blanket-impl traits and edit_* methods are gone. Byte-level replacement logic lives in pub(crate) helpers under transform/text/apply.rs and transform/image/apply.rs; handlers walk the Redactions collection and call the helper on the affected slice of their internal model.

ContentHandle surface

• text_locations() / image_locations() / audio_locations() — typed streams per modality.
• read_text(&TextLocation) / read_image(&ImageLocation) / read_audio(&AudioLocation) — typed per-modality fetches. Replaces the unsound value_at(&Location) -> Option<String> that returned String even for image/audio locations.
• apply_text_redactions / apply_image_redactions / apply_audio_redactions — unchanged from the caller's perspective.

Layout changes

• handler/tabular/ folded into handler/text/ — CsvHandler and XlsxHandler implement TextHandler; there is no TabularHandler capability trait. Tabular redaction is a transform-layer concern, not a handler modality.
• document/span.rs deleted, then reintroduced — but only as a codec utility (Span<L, D>), never on trait signatures.
• transform/{text,image,audio,tabular}/transform.rs (the blanket-impl files) deleted. Replaced by apply.rs helpers.

Engine

• Document gains collect_text/image/audio_locations + read_text/image/audio + a narrower value_at(&Location) -> Option<String> (text and audio only).
• EntityRecognitionOp, PatternRecognitionOp, VisualExtractionOp, and ValidationOp walk locations() and build Vec<Span<L, D>> work lists via Span::from_located + read_*.
• RedactionApplicator switches from value_at(&Location) to read_text(loc).into_inner() — typed, no enum dispatch.
• Document::apply_tabular_redactions dropped; nothing in the engine drove it after TabularTransform's removal.

Style sweeps (workspace-wide)

Two parallel mechanical sweeps in the last commit:

1. Rustdoc reference links — 83 inline [\Foo`](crate::path)forms across 51 files moved to bottom-of-docblock[`Foo`]: crate::path` reference style.
2. Inline imports — use statements inside function bodies, impl scopes, and cfg-gated inner blocks hoisted to top-of-file (with cfg-attr wrapping where needed). 14+ production sites; test-module-top and macro-body uses left alone.

Commit walkthrough

• `refactor(codec)!: reshape handler API around locations and read/redact` — new types, traits, ContentHandle surface. Crate intentionally doesn't compile (concrete handlers not yet migrated).
• `refactor(codec): migrate concrete handlers to location/read/redact API` — all 11 concrete handlers + transform helpers. Codec builds, 87/87 codec tests pass.
• `refactor(engine): switch to location/read/redact codec API` — engine call sites switched over. Workspace builds.
• `refactor(codec, engine): reintroduce Span<L, D> for engine work lists` — replaces `(Location, Data)` tuples in engine ops with the named struct.
• `style(workspace): rustdoc refs at bottom, no inline imports` — mechanical sweeps.

Test plan

• `cargo check --workspace --all-features` clean
• `cargo clippy --workspace --all-features -- -D warnings` clean
• `cargo test --workspace --all-features` — all green
• `cargo doc --workspace --no-deps --all-features` — no new warnings (only pre-existing nvisy_server lib/bin output collision, unrelated)

🤖 Generated with Claude Code