Detect unsupported Notability containers (#148)

[kiki830621]

Refs #148

Summary

• classify legacy Session.plist and modern FlatBuffers noteBundle from bounded ZIP metadata only
• recognize .ntb for HTML/PDF and reject unsupported modern containers before converter/output creation with a stable Traditional Chinese diagnostic
• fail closed for unsafe unknown .ntb without logging its path, while preserving existing unknown .note diagnostics
• document the exact legacy/modern support boundary
• isolate the detector in a lightweight package-scoped target shared by CLI and tests

Metadata safety boundary

• bounded EOCD tail read (65,557 bytes), canonical parser-choice alignment, classic single-disk only
• maximum 16 MiB central directory, 4,096 entries, and 4,096 UTF-8 path bytes
• exact central-directory record/count/size validation, disk-zero requirement, and ZIP64 rejection
• complete ZIPFoundation iteration count required before trusting a marker

Verification

• NotabilityContainerDetectionTests: 17/17 pass
• legacy Note HTML/PDF: 2 pass, 1 existing single-page fixture skip
• full root suite with verified prerequisite PR Restore clean-clone WordToMD dependency #165 temporarily overlaid: 48 XCTest (0 failures, 4 fixture/environment skips) + 26 Swift Testing (0 failures)
• spectra validate detect-notability-ntb-container --strict
• swift package describe --type json
• git diff --check
• five independent review roles completed; all blocking findings were reproduced, corrected, and re-reviewed to PASS

No real Notability payload, title, identifier, audio, thumbnail, or private fixture is included.

Depends on PR #165 for clean-clone root dependency resolution; that prerequisite is not included in this branch.

[kiki830621]

Verify — PASS

Candidate

• Branch: idd/148-ntb-container-detection
• Head: 7cdb880
• PR: Detect unsupported Notability containers (#148) #169
• Verified tag: idd-148-verified
• PR closingIssuesReferences: empty

Requirement coverage

• Modern .ntb and renamed .note containers are classified from ZIP entry metadata and rejected before converter/output creation with the exact generation diagnostic.
• Legacy Session.plist keeps precedence and existing .note HTML/PDF behavior.
• Unknown .ntb fails locally with a fixed diagnostic that contains no input path; unknown .note preserves the established parser path.
• README and CONVERSIONS distinguish supported legacy .note from detected-but-unsupported modern .ntb without claiming FlatBuffers replay or asset extraction.
• No real/private Notability payload or fixture is committed.

Verification findings resolved

Independent reviewers found and the candidate corrected these blocking cases:

1. ZIPFoundation 0.9.20 could scan an entire missing-EOCD file and follow an unbounded ZIP64 count.
2. Its iterator could end silently after a damaged local header, hiding a later legacy marker.
3. A ZIP comment could contain an aligned forged EOCD count.
4. The independent parser and ZIPFoundation could choose different EOCD signatures and different central directories.
5. Cross-disk central entries and ZIP64 records without classic EOCD sentinels were not initially rejected.
6. Linking the full executable target into XCTest destabilized unrelated Word tests; the detector was moved to a lightweight package-scoped target.

The final detector now bounds EOCD/CD/entry/path work, aligns EOCD choice with the dependency parser, independently validates exact central-directory records/count/size/disk/ZIP64 constraints, and requires a complete dependency iteration before trusting any marker.

Test evidence

• swift test --filter NotabilityContainerDetectionTests — 17 tests, 0 failures.
• swift test --filter 'NoteHTMLConvertTests|NotePDFConvertTests' — 3 tests, 0 failures, 1 existing single-page fixture skip.
• Full root suite with verified prerequisite bug: clean clone baseline regressed through ignored word-to-md-swift path dependency #164 temporarily overlaid — 48 XCTest, 0 failures, 4 fixture/environment skips; 26 Swift Testing, 0 failures. Overlay aborted afterward and is not in note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note #148.
• spectra validate detect-notability-ntb-container --strict — valid.
• swift package describe --type json — pass; ZIPFoundation remains 0.9.20 at the existing resolved revision.
• git diff --check origin/main...HEAD — pass.
• Privacy/secret scan of changed source, tests, specs, and docs — pass.

Independent review

• Requirements coverage: PASS.
• Regression/dependency review: PASS.
• Security/privacy devil's advocate: initial finding corrected; re-review PASS.
• Parser/contract reviewer: three adversarial rounds; all findings corrected; final PASS.
• Fresh overall quality reviewer: PASS.
• Root verifier: PASS.

The available reviewer harness was Codex-family only, so this run does not claim true cross-model diversity.

Residue / prerequisite

• Full FlatBuffers parsing, handwriting/timeline replay, and asset extraction remain intentionally out of scope.
• PR Detect unsupported Notability containers (#148) #169 depends on clean-clone prerequisite PR Restore clean-clone WordToMD dependency #165; Restore clean-clone WordToMD dependency #165 is not included in this branch.

Verdict: PASS — verified-gated, ready for human review; not merged and issue remains open.