feat(attachments): recognize HWP and HWPX parser boundaries

[seonghobae]

Product boundary

Naruon owns the email-attachment recognition contract feeding search, context synthesis, evidence provenance, and user-facing document state. This slice admits Korean HWP/HWPX attachments into deterministic deferred states without parsing HWPX XML inline, converting HWP binaries, running OCR/VLM, fetching external resources, or calling an LLM provider.

• HWPX / OWPML: hwpx_xml_package_pending
• HWP binary: hwp_conversion_pending
• validated source bytes are retained as bounded base64 deferred-recognition payloads;
• malformed PDF/HWPX/HWP payloads fail closed before later workers;
• decode_deferred_attachment_payload() remains compatible with the PDF worker while validating expected parser families.

Current stack authority

• protected root: develop@042b0c70531b229af3acbd0421a2f23098d848b3
• direct parent PR: fix(test): install Starlette TestClient dependency #1565 fix(test): install Starlette TestClient dependency
• parent head/base branch: codex/starlette-testclient-dependency@52dfc863d1a5d6e4e80b6366f719dd09f2aa6172
• current branch: feat/hwp-hwpx-attachment-recognition
• current exact head: 5cf957708098d17b6d843353309d86b0b232fcd7
• lifecycle: open / Draft / mergeable / exact-head hosted evidence incomplete

The prior 50a4102c... source head remains the last test/import-style repair point. The current head is its ordinary direct child: compare 50a4102c... → 5cf95770... is ahead 1 / behind 0 and changes only docs/doctoring/hwp-hwpx-attachment-recognition.md (+13/-4). That intervening documentation delta is adopted as valid lineage rather than treated as a race. Predecessor checks/reviews do not transfer.

Current review repairs

HWPX import/worker contract

Fresh review verified a real boundary mismatch: _is_hwpx_payload() admitted a package when it had either a manifest or a section, but recognize_hwpx() requires at least one canonical Contents/sectionN.xml and otherwise fails with HWPX package has no section XML.

• RED 44a268b988f9a3092368bd774a26582647e319a9 adds a manifest-only HWPX package that must fail import admission. The predecessor implementation would accept it because has_manifest was true.
• causal fix 4281904b438ac50c2d6c40d14207119c383227a8 requires at least one section at import admission, aligning queue admission with the recognizer without parsing XML inline.
• the corresponding review thread was resolved only after the fix.

HWPX test import-style finding

• 50a4102c698f28209db68f92e36b52df158eeaf0 imports the recognition module once as hwpx_module and derives local aliases, preserving module-level monkeypatch targets while removing mixed import styles.
• the corresponding code-quality thread was resolved after the repair.

All other reviewed HWPX/HWP admission controls remain in scope: exact HWPX mimetype, bounded ZIP metadata, aggregate member-name limits, HWP OLE + HWP Document File identity, unsupported expected-type rejection, and .hwpx/.owpml generic-MIME handling.

Evidence boundary

Repository-owned workflow evidence observed on predecessor heads is not exact-head merge evidence for 5cf95770.... This PR targets a non-default parent branch, and the canonical repair for stacked-base activation remains Draft #1562. Do not duplicate that workflow change here and do not manufacture a dummy source commit to wake CI.

Historical formal reviews are dismissed/comment-only and no qualifying independent post-last-push approval applies to the current head. Local/source-order receipts remain development evidence only.

Verification and merge boundary

Keep Draft until #1565 is resolved in normal ancestry, the unchanged final head has every applicable repository and organization-required check terminal-success, valid review findings/threads remain resolved, and a qualifying independent non-author post-last-push approval exists. After #1562 is protected-integrated, regenerate stacked-base evidence on the unchanged then-current head; predecessor, parent, status-only, model-only, skipped, absent, cancelled, or failed evidence does not transfer.

No force-push, destructive rebase, self-approval, admin bypass, gate weakening, dummy/no-op requeue commit, or source duplication of the #1562 CI owner repair.

[coderabbitai]

Important

Approval pending

CodeRabbit has no unresolved comments, but it has not reviewed the latest commit.

Use the checkbox below to review the latest commit. CodeRabbit will approve the changes if it finds no blocking issues.

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The attachment parser now recognizes HWPX and HWP files, validates bounded family signatures, preserves valid payloads for deferred processing, and rejects invalid payloads. Tests cover parser registration, ZIP and OLE boundaries, decoder behavior, fallback handling, and documentation records.

Changes

Attachment recognition

Layer / File(s)	Summary
Format contracts and parser registration backend/services/attachment_parser.py, docs/doctoring/..., docs/plans/...	Adds HWPX and HWP parser descriptors, content types, signatures, statuses, resource limits, and recognition-boundary documentation.
Deferred payload validation and decoding backend/services/attachment_parser.py	Validates PDF, HWPX, and HWP payloads with family-specific checks. Adds explicit content-type validation to decode_deferred_attachment_payload().
Recognition regression coverage and shipped-state records backend/tests/test_attachment_parser.py, backend/tests/test_attachment_parser_hwp_signature.py, backend/tests/test_attachment_parser_hwpx_bounds.py, docs/doctoring/...	Tests valid and invalid HWPX/HWP payloads, ZIP limits, OLE signatures, decoder failures, MIME fallback, and parser fallback behavior. Adds checklist and shipped-state records.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: 🟡 Moderate · up to 52bbc

The deferred decoder can currently accept unsupported expected content types without validating the attachment family, which could admit arbitrary bytes into downstream processing. This bounded correctness and safety issue should be fixed before merging.

Sequence Diagram(s)

sequenceDiagram
  participant EmailImport
  participant parse_email_attachment
  participant PayloadValidators
  participant DeferredWorker
  EmailImport->>parse_email_attachment: attachment and content type
  parse_email_attachment->>PayloadValidators: validate family-specific signature
  PayloadValidators-->>parse_email_attachment: valid payload or error code
  parse_email_attachment-->>EmailImport: pending status and base64 payload
  DeferredWorker->>decode_deferred_attachment_payload: payload and expected content type
  decode_deferred_attachment_payload-->>DeferredWorker: validated source bytes

Loading

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding HWP and HWPX attachment parser recognition boundaries.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/hwp-hwpx-attachment-recognition

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@opencode-agent review current exact head d6ecf95b58301752c448b78aac1fe111a8f0186f. Review the complete HWP/HWPX attachment-recognition diff and publish a formal GitHub review verdict anchored to this SHA. All repository CI, security, dependency, and container workflows are terminal-success; verify signature/MIME/extension admission, malformed-package rejection, bounded deferred payloads, and backward compatibility with the existing PDF worker boundary.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

@coderabbitai review

Please review the unchanged exact current head 70683266b93233dae62faec6cbd4df118be41383 (normal merge of live develop@dd8d1519). Predecessor c8585193 evidence does not transfer. Local HWP/HWPX admission tests: 35 passed. Independent non-author APPROVE is still required; this comment is not an approval.

[coderabbitai]

@seonghobae I will review pull request #1353 at exact head 70683266b93233dae62faec6cbd4df118be41383. I will assess the current diff independently of predecessor-head evidence.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Stale review: all review-thread comments on this PR are resolved and the reviewer's cited commit predates the current head, which passes all non-metadata-gate required checks (verified via gh pr checks and the reviewThreads GraphQL query — 0 unresolved threads). Dismissing as superseded per AGENTS.md stale-review guidance.

[coderabbitai]

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding HWP and HWPX attachment parser-boundary recognition.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Please independently review the complete exact current head 4f3e95d against protected develop at 81c1056. Re-read the full diff and current Checks, distinguish resolved predecessor findings from current source defects, and publish a current-head substantive verdict.

[seonghobae]

@coderabbitai review

Please re-run the review for the exact current head 4f3e95daf0d00e43a9907f7afecbb5f9c91907e1. The previous current-head CodeRabbit comment reports only Review failed with no source finding. Do not reuse predecessor evidence; publish a fresh verdict for this SHA.

[coderabbitai]

@seonghobae I will review pull request #1353 at exact head 4f3e95daf0d00e43a9907f7afecbb5f9c91907e1. I will assess the current diff independently and will not reuse predecessor evidence.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

@opencode-agent @cwl-noema-review

Please independently review the complete current PR diff at exact head dd501dae0fc03d813f4a65aa21318cc89d1a193c and publish a formal same-head verdict. The change now includes the worker path for bounded HWPX Contents/sectionN.xml paragraph extraction and graph landing, plus explicit HWP converter-unavailable pending behavior. Verify ZIP/XML resource bounds, entity rejection, MIME/extension admission, provenance, PDF compatibility, and all changed docs/tests. Do not transfer predecessor approvals or findings; a qualifying non-author approval remains required.

[devin-ai-integration]

Devin Review found 1 new potential issue.