files implementation

Internal ownership

This section is for maintainers of the plugin. It describes which module owns each behavior; end users do not need it.

index.mjs registers the tools and the session-spawn replay hook. It owns path authorization, host/managed selection, result path metadata and mutation ordering. Helpers import their concrete dependencies directly; they do not register tools or widen access.

• lib/editCore.mjs owns exact and opt-in fuzzy edit planning, BOM/line-ending preservation, and the existing display-diff and unified-patch caps.
• lib/documents.mjs owns PDF page selection, bounded Poppler execution and notebook rendering. The Read handler supplies the resolved read cap, PDF page cap and image support, then decides whether the visible result authorizes mutation.
• lib/readState.mjs owns the single bounded session/file map, whole-file SHA-256 baselines, range deduplication, history replay, and streamed text snapshots. Read, Write, Edit and the spawn hook use this same module instance. Replay retains distinct host paths and managed:<projectId>\0<path> keys; missing sessions keep the existing inert guard behavior. State is capped at 64 sessions and 512 files per session. Host text reads retain the selected page while hashing and counting the complete file through 64 KiB chunks; managed reads consume the existing provider's chunk stream.
• lib/search.mjs owns Glob matching/traversal and the ripgrep wrappers, including stable paging, the host type-name cache and transport-failure classification. It preserves the five-second timeout, 500-column result bound and shared traversal cap. Missing-path messages stay with the tool handlers.
• lib/imageFormats.mjs owns the frozen magic-byte parser, classification probe and inline image limits shared by Read and document rendering.
• lib/toolResults.mjs owns Files' result metadata wrappers over elowen-plugin-shared/toolResult, preserving successful results, actionable refusals and error shapes.

Tests import helpers from their owning modules. The plugin entry exports only register; there are no compatibility re-exports or additional public plugin seams.