# kcode-doc-extraction Specification
## Purpose
The crate converts one complete in-memory document into normalized bounded
text. Callers provide bytes, a filename, and a media type. The crate detects a
supported format, enforces byte and character limits, extracts locally, and
returns typed metadata and errors through one synchronous API.
Supported formats are:
- searchable PDF;
- Microsoft Word 97-2003 binary DOC;
- Microsoft Word Open XML DOCX;
- XLSX, XLS, XLSB, and ODS workbooks;
- CSV, TSV, plain text, Markdown, JSON, YAML, and XML.
## Format selection
Filename extension detection is case-insensitive and takes precedence over
media-type fallback. DOC is selected by `.doc` or, when no supported extension
is present, `application/msword`.
Detection is deterministic rather than content-sniffing. A DOCX ZIP archive
named `.doc` is handled as legacy DOC and fails if it is not valid Word binary
input.
## Extraction behavior
All formats use the same pre-parse byte limit, text normalization, empty-text
check, Unicode-character limit, and returned metadata path.
Legacy DOC extraction uses the exact crates.io `unword` 0.2.0 parser. It calls
`parse_doc_with_options(bytes, true)`, preserving readable body text and visible
field results while omitting field instructions. Nonempty parser-returned
textboxes are appended once in returned order under `Text box:` markers.
Separate field metadata is ignored. Heading styles recognized by the parser may
appear as Markdown headings.
DOC extraction does not promise visual layout, object-position fidelity,
complete Word-format coverage, or exact formatting preservation.
## Resource and failure boundary
The input byte limit is enforced before parser work and the returned character
limit after common normalization. Legacy DOC parser errors and ordinary
unwinding panics are converted to sanitized `ExtractionFailed` errors. Raw
document bytes and parser diagnostics are not included in public errors.
This baseline does not isolate process aborts, out-of-memory failures,
pathological CPU use, or bugs below the unwind boundary. Strongly hostile DOC
processing requires later process-level memory, CPU, timeout, and crash
isolation plus broader mutation or fuzz testing.
## Non-goals
The crate performs no OCR, network access, filesystem access, persistence,
multipart parsing, HTTP mapping, shell execution, or subprocess conversion. It
does not execute macros or fields, follow external links, load linked images,
or extract embedded OLE objects.
RTF, OpenDocument text, Pages, PowerPoint, and implicit LibreOffice or antiword
fallbacks are outside this release. Async callers must run extraction on an
appropriate blocking worker.