fix(converter): cap doc_name length to avoid Windows path-length errors

[sebastianbraun25]

Note

This PR was created in collaboration between a human and AI: implementation, tests, and
PR text were created by an AI assistant under the guidance and review of the human author.

Problem

openkb add can fail on Windows with OSError [WinError 206] ("The filename or extension is too long") when ingesting a source file with a long filename. The sanitized wiki name (doc_name, derived from the original filename's stem) is used unmodified and unbounded in length as a directory/file name component, and appears twice within the per-add staging tree (.openkb/staging/add-{doc_name}-{uuid8}/wiki/sources/images/{doc_name}/). Combined with an already-nested KB path, the total path length can exceed Windows' ~260-char limit.

Root Cause

_sanitize_stem() in openkb/converter.py only replaces disallowed characters, never bounds length. doc_name (its return value) is used unmodified in cli.py::_staging_dir_for (staging directory name) and converter.py::convert_document (wiki/sources/images/{doc_name}/), so an overlong original filename appears twice in the same path. openkb/url_ingest.py's _sanitize_filename already caps stems at 80 chars (_MAX_FILENAME_STEM) for URL-derived downloads, but that cap wasn't shared with the local-file ingest path.

Solution / Changes

• openkb/converter.py: _sanitize_stem() now caps the cleaned stem at _MAX_STEM_LEN = 40 chars (conservative, since doc_name can appear twice in the staging path) and appends a deterministic 8-hex-char SHA256 digest of the full cleaned stem when truncated, e.g. bulkQuery_result_...-a1b2c3d4. Hashing the full stem (not just the truncated prefix) avoids silent collisions between different overlong names sharing the same prefix.
  • Unlike url_ingest.py's counter-based _unique_path (collisions resolved by an on-disk existence check), converter.py's existing collision handling (_name_taken + resolve_doc_name/resolve_doc_name_from_key) is registry-based, so a deterministic hash suffix (not an incremental counter) is used here.
  • _staging_dir_for (cli.py) and resolve_doc_name/resolve_doc_name_from_key (converter.py) already call _sanitize_stem(), so both the staging directory and the images directory are fixed by this single change — no other call sites needed updates.
  • The existing collision suffix mechanism (-{sha256(path_key)[:8]}) is unchanged and can stack with the new truncation suffix (max length 40+1+8+1+8 = 58 chars — still well within filesystem limits).
• tests/test_converter.py: new TestSanitizeStem class covering truncation + hash-suffix format, determinism (same input → same output), and no silent collision between different overlong stems sharing the same 40-char prefix. Existing tests are unaffected (their stems are well under 40 chars).

Issues

• Resolves #252