note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note

[kiki830621]

Problem

Notability 的現行筆記容器是 .ntb（實測 app 版本 16.8.1），而 note-core-swift
的 NoteParser 只認舊的 plist-based .note。拿現在的 Notability 匯出檔跑
note-to-html，一定失敗。

實跑（macdoc 0.5.0）：

$ macdoc convert --to html --css light <note-bundle> --output out.html
Error: 找不到 Session.plist，可能不是 Notability 筆記檔

錯誤訊息本身是對的（檔案裡確實沒有 Session.plist），但它會把使用者導向錯誤的結論
——「這不是 Notability 檔案」。實際上它就是 Notability 檔案，只是新世代容器。

Type

feature

Expected

note-to-html 能吃現行 Notability 版本匯出的筆記；或者，若本專案決定不支援新容器，
錯誤訊息要明講「偵測到新版 .ntb 容器，目前僅支援舊版 .note」而不是暗示檔案不對。

Actual

Parser 從頭到尾找 plist，對新容器沒有任何解析路徑，錯誤訊息把格式世代問題誤報成
「不是 Notability 筆記檔」。

兩種容器的差異（實測）

	目前支援的 .note	現行 .ntb
外層	zip	zip（PK\x03\x04，compression method=store）
文件本體	Session.plist	noteBundle — FlatBuffers
手寫索引	HandwritingIndex/index.plist	index/ios/HandwritingIndex.fb — FlatBuffers
錄音索引	Recordings/library.plist	index/ios/RecordingIndex.fb — FlatBuffers
錄音檔	Recordings/*.m4a	assets/<sha512>.mp4（AAC；bundle 內字串標為 audio/mp4）
其他	—	version（內容為 1）、manifest.json（{"appVersion":"16.8.1"}）、thumbnail.png

unzip -l 的實際條目（一則含兩段錄音的筆記）：

        1  version
   826824  noteBundle
 14539950  assets/<sha512-a>.mp4
  5014938  assets/<sha512-b>.mp4
       29  manifest.json
    11816  index/ios/HandwritingIndex.fb
       88  index/ios/RecordingIndex.fb
   900385  thumbnail.png

FlatBuffers 表頭（前 12–16 bytes）：

noteBundle                     18000000 14003400 20000000 00001c00
index/ios/HandwritingIndex.fb  10000000 0c001400 13001200
index/ios/RecordingIndex.fb    10000000 0c001200 11001000

三個檔都是無 file_identifier 的 FlatBuffers root table。manifest.json 只有
appVersion，沒有 schema 版本欄位——所以格式判定要靠容器內的條目結構
（有無 noteBundle / Session.plist），不能靠 manifest.json。

已知可行的部分（不必等 parser）

assets/*.mp4 是未加密的標準 AAC，ffprobe 直接讀得到 duration，
unzip 拆出來即可用。所以「從新容器取回錄音」today 就做得到，
缺的是筆跡與時間軸——也就是 note-to-html 的互動重播本體。

一則實測筆記的兩段錄音：3600.02 秒與 1234.14 秒，皆 codec_name=aac。

Impact

• 只要使用者用的是現行 Notability，note-to-html / note-to-pdf 就完全不可用。
  CONVERSIONS.md 標示 Note (.note) → HTML ✅ implemented，對這些使用者是過期的承諾。
• 目前的錯誤訊息會讓人往「檔案壞了 / 拿錯檔」方向排錯，而不是「格式世代不符」。
• 影響面隨時間單調變大：新版本只會越來越多，舊 .note 只會越來越少。

Open questions（需要確認才好定範圍）

1. 現行 Notability 是否仍提供 .note 匯出？ 若分享選單裡還有舊格式，
   本 issue 降級為「錯誤訊息要講清楚 + 文件註明版本前提」；若已完全汰換，
   那就是真正的功能缺口。這題會實質改變優先級，應先回答再開工。
2. Notability 的 FlatBuffers schema 未公開，需要逆向。要不要做，取決於 (1)。
3. 若決定支援：是否先落地「只抽 assets/ 錄音 + thumbnail.png」的降級路徑，
   讓使用者至少拿得回音訊與預覽圖，筆跡重播留待 schema 逆向完成？

建議的分階段做法

階段	內容	成本
0	容器偵測 + 精確錯誤訊息（認出 noteBundle 就說「新版 .ntb，尚未支援」）；CONVERSIONS.md 註明支援的是舊格式	小
1	降級路徑：抽 assets/* 錄音與 thumbnail.png，不解析筆跡	中
2	逆向 FlatBuffers schema，完整支援筆跡 + 音訊同步重播	大

階段 0 不論 open question 的答案是什麼都值得做——現在的錯誤訊息本身就是誤導。

---

實測環境：macdoc 0.5.0、macOS 26.x、Notability 16.8.1 匯出檔。
測試檔為私人會議筆記，未附上；上方所有結構資訊皆為容器層 metadata，不含筆記內容。

Clarity Surface（idd-clarify run 2026-08-11T06:51:55Z）

Type	Source	Suggested canonical	Status
ambiguity	"Notability 的現行筆記容器是 .ntb"	本文對此的信心與下方 Open question 1（「需要確認」）不一致。「現行」是從單一匯出樣本推得，未驗證 .ntb 是唯一/預設格式，亦未確認 16.8.1 是最新版（該值來自 manifest.json 的 appVersion，即寫檔當下的 app 版本）。建議把 Problem 段改為「至少自 16.8.1 起，匯出得到的是 .ntb」	surfaced
missing-context	"Notability 的 FlatBuffers schema 未公開，需要逆向"	未查證是否已有社群逆向成果（如既有 .ntb parser / 公開 schema）。此點直接決定階段 2 的成本量級，開工前應先搜尋	surfaced

掃描依 terminology library（statistics/ML 領域）無 terminology 命中，屬預期——本 issue 是檔案格式領域。
上述兩列均為作者自身斷言的信心校準，非第三方用語問題。
\n---\n\n## Current Status

Phase: verified
Last updated: 2026-08-24 by idd-all / idd-verify

Key Decisions

• Delivery uses the issue's phase-0 fallback: detect modern FlatBuffers containers and fail loudly; it does not claim full .ntb conversion.
• Classification reads bounded ZIP metadata only, requires a canonical classic single-disk central directory, and fails closed on parser ambiguity, ZIP64, cross-disk, over-limit, or incomplete enumeration.
• Modern .ntb and renamed .note fail before converter/output creation; unsafe unknown .ntb uses a fixed path-free diagnostic, while unknown .note preserves the existing parser behavior.
• The detector is isolated in a lightweight package-scoped target shared by CLI and tests.

Scope Changes

• Added verification-driven metadata safety bounds and dependency-parser alignment beyond the initial phase-0 proposal.
• FlatBuffers schema reversal, handwriting/timeline replay, audio extraction, and thumbnail extraction remain out of scope.

Blocking

• Merge ordering only: prerequisite PR Restore clean-clone WordToMD dependency #165 should land before PR Detect unsupported Notability containers (#148) #169 so clean-clone root dependency resolution is available.

Tasks

• Implement synthetic metadata-only RED/GREEN fixtures for .ntb and renamed .note.
• Classify legacy Session.plist, modern noteBundle, and unknown containers without reading payloads.
• Gate .note/.ntb HTML and PDF routes before converter/output creation.
• Bound and independently validate EOCD, central-directory records, entry/path counts, disk, ZIP64, and complete enumeration.
• Reject unsafe unknown .ntb locally without leaking its path; preserve unknown .note diagnostics.
• Keep detector tests in a lightweight shared target rather than the executable target.
• Qualify README and CONVERSIONS support claims.
• Pass focused, legacy regression, full root, Spectra strict, manifest, privacy, and diff checks.
• Complete independent requirements, regression, security, parser-contract, and quality reviews.

Commits

• 6a5663b feat: detect unsupported Notability containers (note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note #148)
• 7cdb880 feat: harden Notability container preflight (note-to-html 不支援 Notability 現行的 .ntb 容器（FlatBuffers），只認舊的 plist-based .note #148)

Pull Request

• Detect unsupported Notability containers (#148) #169 — open, mergeable, verified; no auto-close reference.

[kiki830621]

Diagnosis

Type

feature（phase-0 compatibility boundary）

Root Cause / Analysis

目前 MacDoc.Convert 只接 .note → html/pdf，並直接交給遠端 NoteToHTML／NoteToPDF。底層 NoteCore.NoteParser 會解開 ZIP 後尋找舊格式的 Session.plist；找不到時一律回報「可能不是 Notability 筆記檔」。

Issue 已提供足夠、且不含私人內容的容器 metadata：新版匯出檔以 ZIP 包住 top-level noteBundle、version、manifest.json 與 FlatBuffers indexes。階段 0 可以只讀 ZIP entries 判斷世代，不需解析 noteBundle，也不需接觸私人 fixture。

Strategy

• 以 Spectra 固定 phase-0 契約：辨識 .ntb／含 noteBundle 的新版容器，精確 fail-loud；舊 .note 行為不變。
• 在 MacDocCLI 直接使用既有 resolver 已採用的 ZIPFoundation，只列 entry names、不解壓 payload。
• 先補 synthetic ZIP 的 compiled CLI RED：.ntb → html 與偽裝成 .note 的新版容器都必須回同一精確正體中文診斷，且不得建立 output。
• 更新 README／CONVERSIONS，將 ✅ 明確限定為 plist-based legacy .note，把 .ntb 標成 detected-but-not-supported。
• 跑 note package／CLI focused／root tests、Spectra validate、privacy scan與 diff-check。

Scope Boundary

本輪只交付 issue Expected 的替代分支：「若不支援新容器，錯誤訊息需明講偵測到新版 .ntb、目前只支援舊 .note」。不做 FlatBuffers schema 逆向、筆跡／時間軸解析、assets錄音抽取，也不聲稱已支援 Notability 16.8.1 的互動重播。

Conflict Class

C_shared_module_coord — 會修改 root Package.swift、MacDoc+Convert.swift 與 CONVERSIONS.md；使用獨立 idd/148-ntb-container-detection worktree，避免和其他 CLI／manifest issue碰撞。

Complexity

Spectra。雖然演算法小，但公開 CLI 錯誤契約、根 dependency、測試與兩份使用者文件分散在至少五個檔案，符合跨檔 hard gate。

Risks

• 只靠副檔名會漏掉 .ntb 被改名為 .note；因此判斷必須看 ZIP entries。
• 不得讀取或記錄 noteBundle、音訊、manifest內容；錯誤只提固定 entry名稱與格式世代。
• 容器不是 ZIP或 entries不符合新版形狀時，應保留既有 parser診斷，不可把所有損毀檔誤報成 .ntb。

Residue

完整 .ntb FlatBuffers schema、音訊降級匯出與互動重播仍需要公開／可分享 fixture、schema證據與另一次範圍決策；phase 0 不會掩蓋這個缺口。

[kiki830621]

Diagnosis (canonical routing correction)

Type

feature

Root Cause / Analysis

The existing diagnosis and implementation remain authoritative: #148 adds a public unsupported-container detection/error contract across dependency, CLI, tests, and user docs. The implementation branch exists; this correction only repairs machine-consumed routing fields before verification.

Impact

• Shared root Package.swift, MacDoc+Convert.swift, CONVERSIONS.md, and note-container dependency surface.

Strategy

• Preserve the implemented candidate on idd/148-ntb-container-detection.
• Run strict validation and IDD verify; fix blocking findings before PR.

Conflict Class

C_shared_module_coord

Shared resource: root package graph and convert-router/error contract.

Complexity

Spectra

Published CLI error behavior plus coordinated dependency/tests/docs contract.

Risks

See prior diagnosis; this comment changes routing syntax only.

Residue

(none beyond the prior diagnosis)

[kiki830621]

Implementation Complete

Summary

• 辨識 .note／.ntb ZIP metadata 中的 legacy Session.plist 與 modern FlatBuffers noteBundle，不解壓或讀取 payload。
• .note 與 .ntb 的 HTML/PDF 路由都在 converter 與輸出建立前預檢；modern 容器使用固定正體中文診斷拒絕。
• README 與 CONVERSIONS 已明確區分可轉換的舊版 .note 與僅可辨識、尚不可轉換的現代 .ntb。
• 偵測器位於輕量 NotabilityContainerDetection target，CLI 與測試共用，不把整個 executable target 鏈入 XCTest。

Verification-driven hardening

• EOCD 搜尋限制為 ZIP 規格尾端 65,557 bytes；不再讓 ZIPFoundation 對缺少 EOCD 的檔案從尾端掃到檔首。
• 只接受 classic single-disk ZIP，最多檢查 4,096 entries、每個路徑最多 4,096 UTF-8 bytes；ZIP64／超限輸入回到 unknown。
• 將實際列舉數與 EOCD entry count 比對，避免 ZIPFoundation iterator 遇損毀 local header 靜默提前結束後誤判 modern 或漏掉 legacy precedence。
• 無法安全分類的 .ntb 會在本機用固定、不含路徑的訊息拒絕；既有 unknown .note 仍交給 legacy parser 保留原診斷。

Scope

• 未實作 FlatBuffers schema、手寫／時間軸重播、錄音或縮圖抽取。
• 未加入任何真實 Notability 檔案、標題、識別碼、音訊、縮圖或私人 payload；測試只建立固定 synthetic metadata。

Commits

• 6a5663b — 初始 phase-0 容器偵測、路由、測試與文件。
• 09e8dac — 主線同步後的安全邊界、完整列舉檢查與輕量 target。

Checklist

• Synthetic metadata-only RED／GREEN acceptance
• .ntb → HTML/PDF 與改名 .note 的精確診斷、空 stdout、無輸出
• legacy .note HTML/PDF 回歸
• bounded EOCD／entry／path 與損毀 iterator 回歸
• README／CONVERSIONS 支援邊界
• Spectra strict validation、manifest describe、privacy scan、diff check

Implementation branch: idd/148-ntb-container-detection

[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.