diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a734cee6..b8e8131a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -60,8 +60,12 @@ jobs:
         run: python3 tools/governance/check_architecture.py
       - name: Verify maintained documentation
         run: python3 tools/governance/check_documentation.py
+      - name: Verify Phase 2 compatibility manifest
+        run: python3 tools/compatibility/check_contract_manifest.py
       - name: Run governance tests
-        run: python3 -m unittest discover -s tools/governance/tests -p 'test_*.py'
+        run: |
+          python3 -m unittest discover -s tools/governance/tests -p 'test_*.py'
+          python3 -m unittest discover -s tools/compatibility/tests -p 'test_*.py'
       - name: Verify PR policy
         if: github.event_name == 'pull_request'
         run: python3 tools/governance/check_pr_policy.py --event-path "$GITHUB_EVENT_PATH"
@@ -207,6 +211,8 @@ jobs:
       - run: moon update
       - name: Build CLI
         run: moon build --target native --package ZSeanYves/markitdown/cli
+      - name: Run Phase 2 local compatibility lab
+        run: python3 tools/compatibility/run_contract_lab.py --cli ./_build/native/debug/build/cli/cli.exe
       - name: Install optional dependencies
         run: |
           for profile in ${{ matrix.profiles }}; do
@@ -257,6 +263,13 @@ jobs:
         run: |
           moon build --target native --release --package ZSeanYves/markitdown/cli
           moon build --target native --release --package ZSeanYves/markitdown/internal/bench_runner
+      - name: Run Phase 2 upstream corpus comparison
+        run: |
+          python3 tools/compatibility/fetch_upstream_corpus.py
+          python3 tools/compatibility/run_contract_lab.py \
+            --cli ./_build/native/release/build/cli/cli.exe \
+            --upstream ./env/.venv-markitdown-bench/bin/markitdown \
+            --upstream-corpus ./.tmp/compatibility/upstream-v0.1.7
       - name: Doctor
         run: _build/native/release/build/internal/bench_runner/bench_runner.exe doctor
       - name: Run benchmark
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a9546c34..c7cffe20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+### Phase 2 compatibility laboratory
+
+- Added a pinned MarkItDown `v0.1.7` contract manifest with Tier A/B/C format
+  coverage, input-kind and hint dimensions, fixture hashes, and explicit
+  reference-only gaps for XLS, binary Outlook MSG, and RSS/URI converters.
+- Added a blocking difference taxonomy and structural compatibility runner;
+  unclassified differences cannot silently update goldens.
+- Added native executable checks for OMML preservation diagnostics, PPTX cached
+  chart lowering and chart fallback/SVG asset policy, plus XML, IPYNB, ZIP and
+  EPUB contract representatives.
+- Added exact upstream v0.1.7 fixture retrieval with SHA-256 verification,
+  strict reviewed structural-difference fields, CP932 CSV decoding, bounded
+  native stdin input (`-` with explicit `--format`), and a CI upstream corpus
+  comparison gate.
+
 ### Documentation and evidence governance
 
 - Rebuilt the documentation entry points around `docs/README.md`; removed the
diff --git a/docs/README.md b/docs/README.md
index 1ec9c509..55ae5756 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,6 +24,8 @@ instead of browsing files by name.
 - [Optional-enhancement architecture](./architecture/optional-enhancement-architecture.md)
 - [Benchmark architecture](./architecture/benchmark-architecture.md)
 - [Compatibility matrix](./compatibility-matrix.md)
+- [Phase 2 compatibility lab](./phase-2-compatibility-lab.md): pinned upstream
+  corpus, structural comparator, and executable semantic gates.
 - [Dependency register](./dependency-register.md)
 - [Maintenance and evolution plan](./project-maintenance-plan.md)
 
diff --git a/docs/adr/0005-phase-2-compatibility-lab.md b/docs/adr/0005-phase-2-compatibility-lab.md
new file mode 100644
index 00000000..a8e69f85
--- /dev/null
+++ b/docs/adr/0005-phase-2-compatibility-lab.md
@@ -0,0 +1,54 @@
+# ADR 0005: Official Compatibility Laboratory and Capability Tiers
+
+- Status: accepted
+- Date: 2026-08-08
+- Owners: @ZSeanYves
+- Related: Phase 2 of `docs/project-maintenance-plan.md`
+
+## Context
+
+Phase 0-1 froze the MarkItDown `v0.1.7` reference and created a stable API,
+but compatibility evidence was split between local fixtures and the external
+quality lab. There was no repository-owned manifest that required input-kind,
+hint, mode, structural fields, and an explicit difference decision for each
+case. In particular, the upstream fixes for DOCX equations, PPTX charts and
+SVG-only pictures could not be audited as one contract.
+
+## Decision
+
+Create `tools/compatibility/` as the Phase 2 compatibility laboratory.
+
+- Pin the upstream tag and commit in `contract-manifest.json`.
+- Use deterministic project-owned equivalents for local executable cases and
+  record the upstream test filename, source kind, license and fixture hash.
+- Keep XLS/BIFF, binary Outlook MSG and RSS/URI converters reference-only and
+  explicitly unsupported in the core capability manifest.
+- Compare headings, paragraphs, tables, links, assets, math and diagnostics as
+  separate fields. A structural difference must have one of the five reviewed
+  categories in `difference-categories.json`; no automatic golden updates.
+- Run local cases in every declared mode, and run the upstream `0.1.7` CLI when
+  its managed benchmark environment is installed. The local native integration
+  tests cover Path/Bytes/Reader and MIME/extension/no-hint detection.
+
+## Consequences
+
+The Phase 2 lab can report semantic compatibility without requiring byte-for-
+byte Markdown identity. Existing project enhancements such as provenance and
+diagnostic sections remain independently testable. Some local equivalents are
+classified `undefined_behavior` until a direct upstream fixture or explicit
+contract decision is available; they cannot be silently promoted to stable
+goldens.
+
+## Verification and rollback
+
+```bash
+python3 tools/compatibility/check_contract_manifest.py
+python3 -m unittest discover -s tools/compatibility/tests -p 'test_*.py'
+moon check --target all --warn-list +73 --deny-warn
+moon test --target native --package ZSeanYves/markitdown/internal/integration_tests --filter 'phase2*'
+python3 tools/compatibility/run_contract_lab.py --cli ./_build/native/release/build/cli/cli.exe
+```
+
+Rollback removes the Phase 2 CI steps and compatibility directory while
+preserving the Phase 0-1 API and architecture gates. No product package imports
+the laboratory.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 57fe3943..7488a84f 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -13,3 +13,5 @@ decision. Link the ADR from the implementation PR and the maintenance plan.
   consolidate the package graph after the Phase 0-1 audit.
 - `0004-normalize-source-root.md`: make `src/` the only MoonBit source root
   without changing published package names.
+- `0005-phase-2-compatibility-lab.md`: establish the pinned contract corpus,
+  structural diff taxonomy, and capability-tier evidence gate.
diff --git a/docs/compatibility-matrix.md b/docs/compatibility-matrix.md
index 8e30549b..96d8b4c7 100644
--- a/docs/compatibility-matrix.md
+++ b/docs/compatibility-matrix.md
@@ -1,9 +1,11 @@
 # Compatibility Matrix
 
-This is the Phase 0 compatibility contract. The official comparison target is
+This is the compatibility contract carried from Phase 0 into the Phase 2
+official compatibility laboratory. The official comparison target is
 Microsoft MarkItDown `v0.1.7` at commit
 `fd239d5d2be43d9b68329730206b9312c7d5a388`. The upstream tag and local fixture
-hashes are recorded in `tools/governance/phase0-baseline.json`.
+hashes are recorded in `tools/governance/phase0-baseline.json`; the Phase 2
+case dimensions and difference taxonomy are recorded in `tools/compatibility/`.
 
 ## Compatibility axes
 
@@ -52,7 +54,7 @@ must state which of the three axes they cover.
 - A golden update must include a structured old/new diff and an explanation.
   A PR that only changes golden files is rejected by policy.
 
-## Required upstream checks
+## Required Upstream Checks
 
 For each upstream release, rerun:
 
@@ -63,8 +65,13 @@ For each upstream release, rerun:
 5. HTML/CSV encoding/JSON/RSS XML/IPYNB/ZIP/EPUB vectors;
 6. CLI output, exit codes, assets, diagnostics and no-network behavior.
 
-Differences are classified as `bug`, `upstream-feature-gap`, `intentional-
-enhancement`, or `undefined`. Only classified differences may be baselined.
+Differences are classified as `bug`, `upstream_feature_missing`,
+`expected_enhancement`, `undefined_behavior`, or `unsupported_by_design`.
+Only classified differences may be baselined. The machine-readable manifest
+rejects any missing classification.
+
+The executable Phase 2 representative lab is documented in
+[`phase-2-compatibility-lab.md`](./phase-2-compatibility-lab.md).
 
 ## Reproduction
 
diff --git a/docs/phase-2-compatibility-lab.md b/docs/phase-2-compatibility-lab.md
new file mode 100644
index 00000000..06fa4a0d
--- /dev/null
+++ b/docs/phase-2-compatibility-lab.md
@@ -0,0 +1,63 @@
+# Phase 2 Compatibility Lab
+
+Phase 2 turns compatibility from a narrative claim into a reviewed, repeatable
+contract. The reference is Microsoft MarkItDown `v0.1.7` at commit
+`fd239d5d2be43d9b68329730206b9312c7d5a388`. The reference repository is MIT
+licensed; its binary test files are not copied into this repository. Instead,
+the project stores deterministic local equivalents where redistribution and
+provenance are clear, and records the exact upstream file name for audit.
+
+The machine-readable contract lives in
+`tools/compatibility/contract-manifest.json`. Each case specifies a format
+tier, local fixture or reference-only status, SHA-256 when local, input kinds,
+hint dimensions, modes, structural signals, and one reviewed difference
+category.
+
+The only accepted categories are defined in
+`tools/compatibility/difference-categories.json`: `bug`,
+`upstream_feature_missing`, `expected_enhancement`, `undefined_behavior`, and
+`unsupported_by_design`. An unclassified difference cannot update a golden and
+fails the manifest gate.
+
+## Current Results
+
+The local executable lab runs 15 representative cases across DOCX,
+PPTX, XLSX, PDF, HTML, CSV, JSON, XML, IPYNB, ZIP, and EPUB. The checked cases
+cover OMML preservation diagnostics, cached PPTX chart lowering, chart
+fallback behavior, SVG asset policy, and non-empty conversion for the remaining
+formats. The native run executes 28 local mode cases. A second invocation can
+fetch the 17 exact upstream v0.1.7 binary fixtures (15 executable plus two
+reference-only web fixtures), compare the same structural fields against the
+official CLI, and currently passes 15/15 executable upstream samples.
+
+Three upstream scenarios remain explicit reference-only gaps:
+
+| Scenario | Product status | Stable behavior |
+| --- | --- | --- |
+| Legacy XLS/BIFF | unsupported | capability status `Unsupported`; no parser alias; follow-up [#155](https://github.com/ZSeanYves/markitdown/issues/155) |
+| Binary Outlook MSG | unsupported | `msg` is RFC822/EML-only; binary input is not claimed compatible; follow-up [#156](https://github.com/ZSeanYves/markitdown/issues/156) |
+| RSS/Atom and URI/web converters | unsupported in core | no network access; capability status `Unsupported`; follow-up [#157](https://github.com/ZSeanYves/markitdown/issues/157) |
+
+These are intentionally not represented by an EML alias or a network fallback.
+They remain in the manifest so an accidental capability expansion is visible.
+Reference-only web fixture hashes are retained for provenance, and are never
+executed as network converters.
+
+Run the gates from a clean checkout:
+
+```bash
+python3 tools/compatibility/check_contract_manifest.py
+python3 tools/compatibility/fetch_upstream_corpus.py
+moon build --target native --release --package ZSeanYves/markitdown/cli
+python3 tools/compatibility/run_contract_lab.py \
+  --cli ./_build/native/release/build/cli/cli.exe
+python3 tools/compatibility/run_contract_lab.py \
+  --cli ./_build/native/release/build/cli/cli.exe \
+  --upstream ./env/.venv-markitdown-bench/bin/markitdown \
+  --upstream-corpus ./.tmp/compatibility/upstream-v0.1.7
+```
+
+The lab is a semantic gate, not a byte-for-byte promise. Markdown structure is
+compared by field, while project provenance, diagnostics, source maps, and
+asset metadata are checked independently. A changed expected output requires a
+classified difference and a written decision in the same PR.
diff --git a/docs/project-maintenance-plan.md b/docs/project-maintenance-plan.md
index afc17253..916ad2e9 100644
--- a/docs/project-maintenance-plan.md
+++ b/docs/project-maintenance-plan.md
@@ -1,6 +1,6 @@
 # MoonBit MarkItDown 项目维护与演进计划
 
-**文档状态：** 已接受；Phase 0-1.6 已实施，作为 Phase 2-6 工作基线
+**文档状态：** 已接受；Phase 0-2 已实施，作为 Phase 3-6 工作基线
 **版本：** 1.0  
 **编制日期：** 2026-08-05  
 **适用范围：** `ZSeanYves/markitdown` 主模块、CLI、格式读取器、转换管线、native FFI、质量实验室、发布物和外部依赖
@@ -89,9 +89,9 @@
 
 Phase 1 已将包从 108 收敛到 68，将 `pub(all)` 从 223 收敛到 210，
 其中可构造/可变记录从 32 降到 22；`src/` 已成为唯一源码根目录。
-公共面和包数量不再列为开放阻断项。当前工作重点是：
+公共面和包数量不再列为开放阻断项。Phase 2 已通过兼容实验室关闭本节的兼容证据缺口，后续重点是：
 
-1. **兼容证据仍需系统化。** 本地 contract fixture 覆盖不均，缺少 XLS、二进制 MSG、RSS/网页特化能力等上游场景的明确状态。
+1. **Phase 2 已关闭兼容证据阻断。** `contract-manifest.json` 固定 upstream v0.1.7，15 个原始 fixture 与 28 个本地模式案例均由 CI 重跑；XLS、二进制 MSG、RSS/网页特化能力保留为明确 unsupported 缺口。
 2. **self baseline 需要同指纹批准。** 2026-08-07 新测量覆盖 53 行，但现有 approved baseline 的 MoonBit、quality-lab、Python/runtime、OS/runner 指纹不同，不能据此宣称回归或提升。
 3. **native 安全链仍需加强。** macOS/Linux native 全量链接和运行已经阻断 CI；ASan/UBSan、长期 fuzz 和子进程失败回收仍属于后续安全出口。
 4. **候选依赖仍缺替换证据。** 社区包必须先经过 adapter、双跑、规范、安全、许可证、性能和退出计划，不能按下载量直接替换。
@@ -253,7 +253,8 @@ flowchart LR
 | Phase 1 | 完成 | `api` façade、私有 Input、typed error/code、CLI 退出码、Path/Text/Bytes/Reader、Markdown/Debug/RAG、能力/来源投影、0.8 golden、迁移文档、ADR 和架构依赖门禁 |
 | Phase 1.5 | 完成 | `src/` 唯一 MoonBit source root、逻辑包名保持、benchmark runner/集成测试内部化、根目录与物理路径治理门禁 |
 | Phase 1.6 | 完成 | 文档生命周期和索引、README/CHANGELOG 全面复核、陈旧文档删除、链接/性能主张 CI 门禁、MarkItDown 0.1.7 正式性能重跑 |
-| Phase 2-6 | 未开始 | 必须从本文件对应阶段入口继续，不得跳过兼容、性能、安全或发布验收门 |
+| Phase 2 | 完成 | `tools/compatibility/` 固定 upstream corpus、结构化差分、OMML/PPTX 回归、stdin、能力分级和 CI 门禁 |
+| Phase 3-6 | 未开始 | 必须从本文件对应阶段入口继续，不得跳过依赖、安全、性能或发布验收门 |
 
 ### 阶段 0：基线冻结与治理启动（第 0-2 周）
 
diff --git a/src/cli/cli.mbt b/src/cli/cli.mbt
index ab8a4d91..65ffe00b 100644
--- a/src/cli/cli.mbt
+++ b/src/cli/cli.mbt
@@ -31,6 +31,18 @@ pub fn run_cli_with_image_ocr_provider(
   )
 }
 
+///|
+fn cli_input_source(opts : CliOptions) -> @input.InputSource {
+  if opts.input == "-" {
+    @input.input_from_bytes(
+      cli_read_stdin(512 * 1024 * 1024),
+      source_name="stdin." + cli_requested_format_label(opts),
+    )
+  } else {
+    @input.input_from_path(opts.input)
+  }
+}
+
 ///|
 fn run_cli_with_image_ocr_provider_impl(
   opts : CliOptions,
@@ -92,7 +104,7 @@ fn run_cli_with_image_ocr_provider_and_pdf_rasterizer(
   }
   let execution = match
     @convert.convert_input_with_provenance_and_image_ocr_provider_and_pdf_rasterizer(
-      @input.input_from_path(opts.input),
+      cli_input_source(opts),
       convert_options,
       image_ocr_provider,
       pdf_rasterizer,
@@ -179,7 +191,7 @@ fn cli_convert_to_atomic_stream_file(
   )
   let result = match
     @convert.convert_input_to_sink_unbuffered(
-      @input.input_from_path(opts.input),
+      cli_input_source(opts),
       convert_options,
       sink,
     ) {
diff --git a/src/cli/cli_parse.mbt b/src/cli/cli_parse.mbt
index 322b10fd..1e9fdc96 100644
--- a/src/cli/cli_parse.mbt
+++ b/src/cli/cli_parse.mbt
@@ -7,7 +7,7 @@ fn cli_requested_format(opts : CliOptions) -> @input.DetectedFormat {
         Some(label) => @input.parse_detected_format(label)
         None => {
           let detector = @input.default_format_detector()
-          let detected = (detector.detect)(@input.input_from_path(opts.input))
+          let detected = (detector.detect)(cli_input_source(opts))
           detected.format
         }
       }
@@ -38,7 +38,13 @@ fn cli_requested_format_from_input(
         Some(label) => @input.parse_detected_format(label)
         None => {
           let detector = @input.default_format_detector()
-          let detected = (detector.detect)(@input.input_from_path(input_path))
+          let detected = (detector.detect)(
+            if input_path == "-" {
+              @input.input_from_bytes(Bytes::new(0), source_name="stdin.bin")
+            } else {
+              @input.input_from_path(input_path)
+            },
+          )
           detected.format
         }
       }
@@ -340,7 +346,7 @@ fn parse_cli_options_from_index(
       i += 2
       continue
     }
-    if arg.has_prefix("-") {
+    if arg.has_prefix("-") && arg != "-" {
       return Err("unsupported option: " + arg)
     }
     positionals.push(arg)
@@ -363,6 +369,9 @@ fn parse_cli_options_from_index(
     Ok(value) => value
     Err(msg) => return Err(msg)
   }
+  if effective_positionals[0] == "-" && explicit_format is None {
+    return Err("stdin input requires an explicit --format")
+  }
   let requested_format = cli_requested_format_from_input(
     effective_positionals[0],
     explicit_format,
diff --git a/src/cli/cli_stdin_wbtest.mbt b/src/cli/cli_stdin_wbtest.mbt
new file mode 100644
index 00000000..a53d9d35
--- /dev/null
+++ b/src/cli/cli_stdin_wbtest.mbt
@@ -0,0 +1,7 @@
+///|
+#cfg(target="native")
+test "main cli routes dash input through the stdin source" {
+  let source = cli_input_source(cli_options("-", None, Some(Txt), Markdown))
+  assert_true(@input.input_path(source) is None)
+  assert_true(@input.input_bytes(source) is Some(_))
+}
diff --git a/src/cli/moon.pkg b/src/cli/moon.pkg
index fc43b4e8..ec2a2f39 100644
--- a/src/cli/moon.pkg
+++ b/src/cli/moon.pkg
@@ -26,5 +26,13 @@ pkgtype(kind: "executable")
 
 options(
   "preferred-target": "native",
-  "native-stub": [ "stderr_native_stub.c", "atomic_file_sink_native_stub.c" ],
+  "native-stub": [
+    "stderr_native_stub.c",
+    "atomic_file_sink_native_stub.c",
+    "stdin_native_stub.c",
+  ],
+  targets: {
+    "stdin_native.mbt": [ "native" ],
+    "stdin_portable.mbt": [ "wasm", "wasm-gc", "js" ],
+  },
 )
diff --git a/src/cli/stdin_native.mbt b/src/cli/stdin_native.mbt
new file mode 100644
index 00000000..285d773b
--- /dev/null
+++ b/src/cli/stdin_native.mbt
@@ -0,0 +1,8 @@
+///|
+#cfg(target="native")
+extern "C" fn cli_read_stdin_ffi(max_bytes : Int) -> Bytes = "markitdown_cli_read_stdin"
+
+///|
+fn cli_read_stdin(max_bytes : Int) -> Bytes {
+  cli_read_stdin_ffi(max_bytes)
+}
diff --git a/src/cli/stdin_native_stub.c b/src/cli/stdin_native_stub.c
new file mode 100644
index 00000000..4fc5abf2
--- /dev/null
+++ b/src/cli/stdin_native_stub.c
@@ -0,0 +1,32 @@
+#include <stdio.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+#include "moonbit.h"
+
+MOONBIT_FFI_EXPORT
+moonbit_bytes_t markitdown_cli_read_stdin(int32_t max_bytes) {
+  if (max_bytes <= 0) return moonbit_make_bytes_raw(0);
+  int32_t capacity = max_bytes < 65536 ? max_bytes : 65536;
+  unsigned char *buffer = (unsigned char *)malloc((size_t)capacity);
+  if (buffer == NULL) return moonbit_make_bytes_raw(0);
+  int32_t length = 0;
+  while (length < max_bytes) {
+    if (length == capacity) {
+      int32_t next = capacity > max_bytes / 2 ? max_bytes : capacity * 2;
+      unsigned char *grown = (unsigned char *)realloc(buffer, (size_t)next);
+      if (grown == NULL) break;
+      buffer = grown;
+      capacity = next;
+    }
+    size_t read = fread(buffer + length, 1, (size_t)(capacity - length), stdin);
+    length += (int32_t)read;
+    if (read == 0) break;
+  }
+  moonbit_bytes_t output = moonbit_make_bytes_raw(length);
+  if (length > 0) {
+    memcpy(output, buffer, (size_t)length);
+  }
+  free(buffer);
+  return output;
+}
diff --git a/src/cli/stdin_portable.mbt b/src/cli/stdin_portable.mbt
new file mode 100644
index 00000000..9535b6c0
--- /dev/null
+++ b/src/cli/stdin_portable.mbt
@@ -0,0 +1,5 @@
+///|
+#cfg(not(target="native"))
+fn cli_read_stdin(_max_bytes : Int) -> Bytes {
+  Bytes::new(0)
+}
diff --git a/src/cli/stdin_wbtest.mbt b/src/cli/stdin_wbtest.mbt
new file mode 100644
index 00000000..404436b8
--- /dev/null
+++ b/src/cli/stdin_wbtest.mbt
@@ -0,0 +1,4 @@
+///|
+test "stdin reader returns an empty payload for a zero-byte probe" {
+  assert_eq(cli_read_stdin(0).length(), 0)
+}
diff --git a/src/formats/html/lower_doc.mbt b/src/formats/html/lower_doc.mbt
index 4cff3830..eeacb43e 100644
--- a/src/formats/html/lower_doc.mbt
+++ b/src/formats/html/lower_doc.mbt
@@ -14,15 +14,52 @@ fn lower_html_document(
     lowering_index,
     top_blocks,
   )
+  let blocks = if lowered.blocks.length() == 0 {
+    match html_conservative_empty_output_fallback(semantic, source) {
+      Some(block) => [block]
+      None => lowered.blocks
+    }
+  } else {
+    lowered.blocks
+  }
   @core.document_with_assets(
     @core.document_with_metadata(
-      @core.document_with_blocks(@core.empty_document_ir(), lowered.blocks),
+      @core.document_with_blocks(@core.empty_document_ir(), blocks),
       lowered.metadata,
     ),
     lowered.assets,
   )
 }
 
+///|
+/// Preserve meaningful source text when aggressive scope/noise filtering would
+/// otherwise make a valid HTML document appear empty. The result is deliberately
+/// a paragraph so the loss is visible and the diagnostic layer can classify it.
+fn html_conservative_empty_output_fallback(
+  semantic : @dhtml.HtmlSemanticDocument,
+  source : @input.InputSource,
+) -> @core.CoreBlock? {
+  let mut candidate : @dhtml.HtmlBlockFact? = None
+  for block in semantic.blocks {
+    if block.text_preview.trim() == "" {
+      continue
+    }
+    match candidate {
+      None => candidate = Some(block)
+      Some(existing) if block.text_preview.length() >
+        existing.text_preview.length() => candidate = Some(block)
+      _ => ()
+    }
+  }
+  candidate.map(fn(block) {
+    @core.make_block(
+      Paragraph,
+      block.text_preview.trim().to_owned(),
+      source_ref=html_block_source_ref(source, block),
+    )
+  })
+}
+
 ///|
 priv struct HtmlLoweringResult {
   blocks : Array[@core.CoreBlock]
diff --git a/src/formats/html/lower_stream_wbtest.mbt b/src/formats/html/lower_stream_wbtest.mbt
index d5a2cf16..2cc72bf4 100644
--- a/src/formats/html/lower_stream_wbtest.mbt
+++ b/src/formats/html/lower_stream_wbtest.mbt
@@ -229,6 +229,25 @@ test "HTML DOM route lowers semantic notes tables figures noise and unsupported
   assert_true(result.diagnostics.pass_trace.contains("parse:html_parser"))
 }
 
+///|
+test "HTML DOM route preserves text when selected scope is filtered" {
+  let html = "<html><body><main class='nav'><article><p>fallback content</p></article></main></body></html>"
+  let source = @input.input_from_text_with_format(
+    html,
+    "filtered.html",
+    Some(Html),
+  )
+  match html_document_to_ir(source, html) {
+    Ok((document, _diagnostics)) => {
+      assert_true(document.blocks.length() > 0)
+      assert_true(
+        document.blocks.any(block => block.text.contains("fallback content")),
+      )
+    }
+    Err(error) => fail(error)
+  }
+}
+
 ///|
 test "HTML source helper paths trim inlines render lists and classify local images" {
   assert_true(
diff --git a/src/formats/shared/delimited_prepare.mbt b/src/formats/shared/delimited_prepare.mbt
index f7b6318d..44d7ad84 100644
--- a/src/formats/shared/delimited_prepare.mbt
+++ b/src/formats/shared/delimited_prepare.mbt
@@ -31,7 +31,11 @@ fn prepare_delimited_document_from_source(
 ) -> Result[PreparedDelimitedDocument, String] {
   let text_payload = match @sourceio.read_source_text_with_utf16_bom(source) {
     Ok(payload) => payload
-    Err(err) => return Err(err)
+    Err(_) =>
+      match @sourceio.read_source_text_with_cp932_fallback(source) {
+        Ok(payload) => payload
+        Err(err) => return Err(err)
+      }
   }
   let parsed = if is_tsv {
     try
diff --git a/src/formats/shared/delimited_text_wbtest.mbt b/src/formats/shared/delimited_text_wbtest.mbt
index 3cfb8831..90e91de8 100644
--- a/src/formats/shared/delimited_text_wbtest.mbt
+++ b/src/formats/shared/delimited_text_wbtest.mbt
@@ -85,3 +85,25 @@ test "Delimited parser helpers classify errors and expose streaming capability"
   assert_true(capability.supports_streaming)
   assert_true(capability.produces_tables)
 }
+
+///|
+test "Delimited parser decodes UTF16 BOM before legacy byte fallback" {
+  let bytes = Bytes::from_array(
+    [
+      0xFF, 0xFE, 0x6E, 0, 0x61, 0, 0x6D, 0, 0x65, 0, 0x09, 0, 0x76, 0, 0x61, 0,
+      0x6C, 0, 0x75, 0, 0x65, 0, 0x0A, 0, 0x41, 0, 0x09, 0, 0x31, 0,
+    ].map(Int::to_byte),
+  )
+  let source = @input.input_from_bytes_with_format(
+    bytes,
+    "utf16.tsv",
+    Some(Tsv),
+  )
+  let result = (tsv_parser().parse)(source, @parser.new_parse_context(Tsv)).unwrap()
+  let events = result.event_stream.unwrap()
+  assert_eq(events[0].text, "name")
+  assert_eq(events[1].text, "value")
+  assert_true(
+    !result.diagnostics.degraded_features.contains("csv_raw_fallback"),
+  )
+}
diff --git a/src/internal/integration_tests/phase2_compatibility_test.mbt b/src/internal/integration_tests/phase2_compatibility_test.mbt
new file mode 100644
index 00000000..2aae0da9
--- /dev/null
+++ b/src/internal/integration_tests/phase2_compatibility_test.mbt
@@ -0,0 +1,101 @@
+///|
+test "phase2 representative cases preserve path bytes reader and hint contracts" {
+  let fixtures : Array[(String, @input.DetectedFormat, String)] = [
+    (
+      "samples/fixtures/contracts/docx/docx_advanced_synthetic.docx",
+      Docx,
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ),
+    (
+      "samples/fixtures/contracts/pptx/pptx_chart_cache_synthetic.pptx",
+      Pptx,
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ),
+    (
+      "samples/fixtures/contracts/xlsx/sheet_simple.xlsx",
+      Xlsx,
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ),
+    ("samples/fixtures/contracts/pdf/text_simple.pdf", Pdf, "application/pdf"),
+    ("samples/fixtures/contracts/html/html_entities.html", Html, "text/html"),
+    ("samples/fixtures/contracts/csv/csv_basic.csv", Csv, "text/csv"),
+    (
+      "samples/fixtures/contracts/json/json_object_basic.json",
+      Json,
+      "application/json",
+    ),
+    ("samples/fixtures/contracts/xml/xml_basic.xml", Xml, "application/xml"),
+    (
+      "samples/fixtures/contracts/ipynb/ipynb_markdown_basic.ipynb",
+      Ipynb,
+      "application/x-ipynb+json",
+    ),
+    (
+      "samples/fixtures/contracts/zip/zip_basic_structured.zip",
+      Zip,
+      "application/zip",
+    ),
+    (
+      "samples/fixtures/contracts/epub/epub_basic_package.epub",
+      Epub,
+      "application/epub+zip",
+    ),
+  ]
+  for fixture in fixtures {
+    let (path, format, mime) = fixture
+    let bytes = @fs.read_file_to_bytes(path) catch {
+      err => fail("phase2 fixture read failed: " + err.to_string())
+    }
+    let name = path.split("/").last().unwrap_or(path).to_owned()
+    let path_result = convert_binary_source_for_equivalence(
+      @input.input_from_path(path),
+      format,
+    )
+    let bytes_result = convert_binary_source_for_equivalence(
+      @input.input_from_bytes(bytes, source_name=name),
+      format,
+    )
+    let mime_result = convert_binary_source_for_equivalence(
+      @input.with_mime_type(
+        @input.input_from_bytes(bytes, source_name="phase2-payload"),
+        Some(mime),
+      ),
+      format,
+    )
+    let reader = @input.make_input_reader(
+      fn(offset, length) {
+        let start = offset.to_int()
+        let end_ = (start + length.min(4096)).min(bytes.length())
+        Ok(bytes.view(start~, end=end_).to_owned())
+      },
+      size=bytes.length().to_int64(),
+    )
+    let reader_result = convert_binary_source_for_equivalence(
+      @input.input_from_reader(reader, source_name=name),
+      format,
+    )
+    assert_eq(path_result.content, bytes_result.content)
+    assert_eq(path_result.content, mime_result.content)
+    assert_eq(path_result.content, reader_result.content)
+    assert_true(path_result.content.trim() != "")
+  }
+}
+
+///|
+test "phase2 records OMML and PPTX chart compatibility decisions" {
+  let docx = inprocess_convert_fixture(
+    "samples/fixtures/contracts/docx/docx_advanced_synthetic.docx",
+    Docx,
+    Balanced,
+  )
+  assert_true(docx.content.contains("x \\+ y"))
+  assert_true(docx.content.contains("math") || docx.content.contains("x \\+ y"))
+  let pptx = inprocess_convert_fixture(
+    "samples/fixtures/contracts/pptx/pptx_chart_cache_synthetic.pptx",
+    Pptx,
+    Balanced,
+  )
+  assert_true(pptx.content.contains("Quarterly revenue"))
+  assert_true(pptx.content.contains("| North |"))
+  assert_true(!pptx.content.contains("[Unsupported PPTX chart"))
+}
diff --git a/src/internal/readers/source_io/cp932_native.mbt b/src/internal/readers/source_io/cp932_native.mbt
new file mode 100644
index 00000000..61eb3b9c
--- /dev/null
+++ b/src/internal/readers/source_io/cp932_native.mbt
@@ -0,0 +1,12 @@
+///|
+#cfg(target="native")
+#borrow(payload)
+extern "C" fn decode_cp932_native_ffi(
+  payload : Bytes,
+  payload_len : Int,
+) -> Bytes = "markitdown_decode_cp932"
+
+///|
+fn decode_cp932_native(payload : Bytes) -> Bytes {
+  decode_cp932_native_ffi(payload, payload.length())
+}
diff --git a/src/internal/readers/source_io/cp932_native_stub.c b/src/internal/readers/source_io/cp932_native_stub.c
new file mode 100644
index 00000000..74a694a6
--- /dev/null
+++ b/src/internal/readers/source_io/cp932_native_stub.c
@@ -0,0 +1,76 @@
+#include <errno.h>
+#include <dlfcn.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#include "moonbit.h"
+
+MOONBIT_FFI_EXPORT
+moonbit_bytes_t markitdown_decode_cp932(moonbit_bytes_t input, int32_t input_length) {
+  if (input == NULL) {
+    return moonbit_make_bytes_raw(0);
+  }
+  if (input_length <= 0) {
+    return moonbit_make_bytes_raw(0);
+  }
+  for (int32_t index = 0; index < input_length; index++) {
+    unsigned char value = ((unsigned char *)input)[index];
+    if (value <= 0x7f || (value >= 0xa1 && value <= 0xdf)) continue;
+    if (!((value >= 0x81 && value <= 0x9f) ||
+          (value >= 0xe0 && value <= 0xef)) || index + 1 >= input_length) {
+      return moonbit_make_bytes_raw(0);
+    }
+    unsigned char trail = ((unsigned char *)input)[++index];
+    if (!((trail >= 0x40 && trail <= 0x7e) ||
+          (trail >= 0x80 && trail <= 0xfc))) {
+      return moonbit_make_bytes_raw(0);
+    }
+  }
+  void *library = dlopen("/usr/lib/libiconv.2.dylib", RTLD_LAZY);
+  if (library == NULL) {
+    library = dlopen("libiconv.so.2", RTLD_LAZY);
+  }
+  if (library == NULL) {
+    library = dlopen("libc.so.6", RTLD_LAZY);
+  }
+  if (library == NULL) {
+    return moonbit_make_bytes_raw(0);
+  }
+  typedef void *(*open_fn_t)(const char *, const char *);
+  typedef size_t (*convert_fn_t)(void *, char **, size_t *, char **, size_t *);
+  typedef int (*close_fn_t)(void *);
+  open_fn_t open_fn = (open_fn_t)dlsym(library, "iconv_open");
+  convert_fn_t convert_fn = (convert_fn_t)dlsym(library, "iconv");
+  close_fn_t close_fn = (close_fn_t)dlsym(library, "iconv_close");
+  if (open_fn == NULL || convert_fn == NULL || close_fn == NULL) {
+    dlclose(library);
+    return moonbit_make_bytes_raw(0);
+  }
+  void *converter = open_fn("UTF-8", "CP932");
+  if (converter == (void *)-1) {
+    dlclose(library);
+    return moonbit_make_bytes_raw(0);
+  }
+  size_t capacity = (size_t)input_length * 4u + 4u;
+  moonbit_bytes_t output = moonbit_make_bytes_raw((int32_t)capacity);
+  char *input_cursor = (char *)input;
+  char *output_cursor = (char *)output;
+  size_t input_left = (size_t)input_length;
+  size_t output_left = capacity;
+  size_t result = convert_fn(converter, &input_cursor, &input_left,
+                             &output_cursor, &output_left);
+  close_fn(converter);
+  dlclose(library);
+  if (result == (size_t)-1 || input_left != 0) {
+    moonbit_decref(output);
+    return moonbit_make_bytes_raw(0);
+  }
+  size_t written = capacity - output_left;
+  moonbit_bytes_t resized = moonbit_make_bytes_raw((int32_t)written);
+  if (written > 0) {
+    memcpy(resized, output, written);
+  }
+  moonbit_decref(output);
+  return resized;
+}
diff --git a/src/internal/readers/source_io/cp932_portable.mbt b/src/internal/readers/source_io/cp932_portable.mbt
new file mode 100644
index 00000000..40ce1880
--- /dev/null
+++ b/src/internal/readers/source_io/cp932_portable.mbt
@@ -0,0 +1,5 @@
+///|
+#cfg(not(target="native"))
+fn decode_cp932_native(_payload : Bytes) -> Bytes {
+  Bytes::new(0)
+}
diff --git a/src/internal/readers/source_io/moon.pkg b/src/internal/readers/source_io/moon.pkg
index 0a97f68e..86e28b4e 100644
--- a/src/internal/readers/source_io/moon.pkg
+++ b/src/internal/readers/source_io/moon.pkg
@@ -6,4 +6,9 @@ import {
 
 options(
   "preferred-target": "native",
+  "native-stub": [ "cp932_native_stub.c" ],
+  targets: {
+    "cp932_native.mbt": [ "native" ],
+    "cp932_portable.mbt": [ "wasm", "wasm-gc", "js" ],
+  },
 )
diff --git a/src/internal/readers/source_io/pkg.generated.mbti b/src/internal/readers/source_io/pkg.generated.mbti
index 443348e7..1af2795e 100644
--- a/src/internal/readers/source_io/pkg.generated.mbti
+++ b/src/internal/readers/source_io/pkg.generated.mbti
@@ -22,6 +22,8 @@ pub fn read_source_bytes(@input.InputSource) -> Result[SourceBytesPayload, Strin
 
 pub fn read_source_text(@input.InputSource) -> Result[SourceTextPayload, String]
 
+pub fn read_source_text_with_cp932_fallback(@input.InputSource) -> Result[SourceTextPayload, String]
+
 pub fn read_source_text_with_utf16_bom(@input.InputSource) -> Result[SourceTextPayload, String]
 
 pub fn read_xml_source_text(@input.InputSource) -> Result[SourceTextPayload, String]
diff --git a/src/internal/readers/source_io/source_io.mbt b/src/internal/readers/source_io/source_io.mbt
index b097430c..d318de96 100644
--- a/src/internal/readers/source_io/source_io.mbt
+++ b/src/internal/readers/source_io/source_io.mbt
@@ -50,6 +50,48 @@ pub fn read_source_text(
   }
 }
 
+///|
+pub fn read_source_text_with_cp932_fallback(
+  source : @input.InputSource,
+) -> Result[SourceTextPayload, String] {
+  let text_result = match @input.input_text(source) {
+    Some(text) => Ok(text)
+    None =>
+      match read_source_bytes(source) {
+        Ok(payload) => decode_text_bytes_with_fallback(payload.bytes)
+        Err(err) => Err(err)
+      }
+  }
+  match text_result {
+    Ok(text) =>
+      Ok({
+        text,
+        prepared_source: if @input.input_text(source) is Some(_) {
+          source
+        } else {
+          @input.with_text_payload(source, text)
+        },
+      })
+    Err(err) => Err(err)
+  }
+}
+
+///|
+fn decode_text_bytes_with_fallback(bytes : Bytes) -> Result[String, String] {
+  try @utf8.decode(bytes, ignore_bom=false) |> Ok catch {
+    _ => {
+      let converted = decode_cp932_native(bytes)
+      if converted.length() == 0 {
+        Err("utf8/cp932 decode failed")
+      } else {
+        try @utf8.decode(converted, ignore_bom=false) |> Ok catch {
+          _ => Err("utf8/cp932 decode failed")
+        }
+      }
+    }
+  }
+}
+
 ///|
 pub fn read_source_text_with_utf16_bom(
   source : @input.InputSource,
diff --git a/src/internal/readers/source_io/source_io_wbtest.mbt b/src/internal/readers/source_io/source_io_wbtest.mbt
index c6a56da1..78eff476 100644
--- a/src/internal/readers/source_io/source_io_wbtest.mbt
+++ b/src/internal/readers/source_io/source_io_wbtest.mbt
@@ -220,3 +220,31 @@ test "line readers reject invalid limits and missing sources" {
   assert_true(open_source_text_line_reader(missing) is Err(_))
   assert_true(open_source_text_block_reader(missing) is Err(_))
 }
+
+///|
+#cfg(target="native")
+test "source IO CP932 fallback is explicit and preserves reader errors" {
+  let cp932 = @input.input_from_bytes(
+    Bytes::from_array([0x96, 0xBC, 0x91, 0x4F].map(Int::to_byte)),
+    source_name="names.csv",
+  )
+  match read_source_text_with_cp932_fallback(cp932) {
+    Ok(payload) => assert_eq(payload.text, "名前")
+    Err(error) => fail(error)
+  }
+  let invalid = @input.input_from_bytes(
+    Bytes::from_array([0x80].map(Int::to_byte)),
+    source_name="bad.csv",
+  )
+  assert_true(read_source_text_with_cp932_fallback(invalid) is Err(_))
+  let text = @input.input_from_text("already utf8", source_name="text.csv")
+  match read_source_text_with_cp932_fallback(text) {
+    Ok(payload) => assert_eq(payload.text, "already utf8")
+    Err(error) => fail(error)
+  }
+  let failing = @input.input_from_reader(
+    @input.make_input_reader(fn(_offset, _length) { Err("reader failed") }),
+    source_name="bad.csv",
+  )
+  assert_true(read_source_text_with_cp932_fallback(failing) is Err(_))
+}
diff --git a/tools/compatibility/README.md b/tools/compatibility/README.md
new file mode 100644
index 00000000..7422945d
--- /dev/null
+++ b/tools/compatibility/README.md
@@ -0,0 +1,50 @@
+# Phase 2 Compatibility Lab
+
+This directory is the executable contract surface for Phase 2 of the
+maintenance plan. It is deliberately separate from the product packages and
+from the external quality-lab repository.
+
+`contract-manifest.json` pins the Microsoft MarkItDown `v0.1.7` tag and commit,
+maps each enrolled case to a local or reference-only fixture, and declares the
+input kinds, hints, modes, expected signals, tier, and reviewed difference
+classification. `difference-categories.json` defines the only classifications
+accepted by review. A case without a classification, or a classification not
+present in that file, is a hard failure.
+
+The local cases are project-owned equivalents because the upstream repository's
+test binaries are MIT-licensed but are not part of this source distribution.
+The upstream file name and pinned commit remain recorded so a clean checkout
+can retrieve and audit the reference. Reference-only cases intentionally prove
+that XLS, binary Outlook MSG, and RSS are unsupported rather than silently
+claiming compatibility.
+
+Fetch and verify the exact upstream binaries (they are never committed):
+
+```bash
+python3 tools/compatibility/fetch_upstream_corpus.py
+```
+
+Run the manifest gate without a MoonBit build:
+
+```bash
+python3 tools/compatibility/check_contract_manifest.py
+```
+
+Run executable local semantic checks after building the native CLI:
+
+```bash
+moon build --target native --release --package ZSeanYves/markitdown/cli
+python3 tools/compatibility/run_contract_lab.py \
+  --cli ./_build/native/release/build/cli/cli.exe
+```
+
+The runner executes every declared mode and compares structural fields
+(headings, paragraphs, tables, links, assets, math markers, and diagnostics)
+independently. It never turns an unexplained difference into a new golden
+automatically. Path/Bytes/Reader and hint dimensions are exercised by the
+native integration contract in `src/internal/integration_tests`.
+
+For the upstream comparison, install the pinned reference environment from
+`tools/env/optional_deps.sh install bench`, then pass both `--upstream` and
+`--upstream-corpus`. The runner fails on any structural field not recorded in
+the case's reviewed classification.
diff --git a/tools/compatibility/check_contract_manifest.py b/tools/compatibility/check_contract_manifest.py
new file mode 100644
index 00000000..0f6f765b
--- /dev/null
+++ b/tools/compatibility/check_contract_manifest.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Validate the reviewed Phase 2 contract corpus and coverage matrix."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+MANIFEST = ROOT / "tools/compatibility/contract-manifest.json"
+CATEGORIES = ROOT / "tools/compatibility/difference-categories.json"
+REQUIRED_FORMATS = {"docx","xlsx","pptx","pdf","html","csv","json","xml","ipynb","zip","epub"}
+REQUIRED_INPUT_KINDS = {"path","bytes","reader"}
+REQUIRED_HINTS = {"none","mime","extension"}
+ALLOWED_SOURCE = {"upstream-compatible-local","upstream-reference-only"}
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def validate(root: Path = ROOT) -> list[str]:
+    errors: list[str] = []
+    try:
+        data = json.loads((root / MANIFEST.relative_to(ROOT)).read_text(encoding="utf-8"))
+        cats = json.loads((root / CATEGORIES.relative_to(ROOT)).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return [f"unable to read Phase 2 manifest: {exc}"]
+    if data.get("schema_version") != 1 or cats.get("schema_version") != 1:
+        errors.append("Phase 2 manifest and category schema_version must be 1")
+    if not data.get("tiers", {}).get("A"):
+        errors.append("Tier A must contain at least one format")
+    upstream = data.get("upstream", {})
+    if upstream.get("tag") != "v0.1.7" or upstream.get("commit") != "fd239d5d2be43d9b68329730206b9312c7d5a388":
+        errors.append("upstream reference must remain MarkItDown v0.1.7 at the reviewed commit")
+    allowed_categories = set(data.get("comparison", {}).get("allowed_categories", []))
+    defined_categories = set(cats.get("categories", {}))
+    if allowed_categories != defined_categories:
+        errors.append("comparison categories and difference-categories.json disagree")
+    cases = data.get("cases", [])
+    reviewed = data.get("reviewed_upstream_differences", {})
+    ids: set[str] = set()
+    seen_formats: set[str] = set()
+    for case in cases:
+        case_id = case.get("id")
+        if not case_id or case_id in ids:
+            errors.append(f"duplicate or missing case id: {case_id!r}")
+        ids.add(case_id)
+        fmt = case.get("format")
+        seen_formats.add(fmt)
+        if case.get("source") not in ALLOWED_SOURCE:
+            errors.append(f"{case_id}: invalid source classification")
+        if not case.get("upstream_file"):
+            errors.append(f"{case_id}: upstream_file is required")
+        if case.get("classification") not in allowed_categories:
+            errors.append(f"{case_id}: missing or unknown difference classification")
+        signals = case.get("signals")
+        if not isinstance(signals, dict) or not signals:
+            errors.append(f"{case_id}: reviewed signals are required")
+        if case.get("format") == "docx" and signals.get("math") != "preserved-text-signature":
+            errors.append(f"{case_id}: DOCX equation case must declare math preservation signal")
+        if case.get("format") == "pptx" and "chart" in case.get("comparison_fields", []) and case.get("id") != "pptx-svg-fallback":
+            if not signals.get("contains"):
+                errors.append(f"{case_id}: PPTX chart case must declare structural content signals")
+        if case.get("source") == "upstream-compatible-local":
+            fixture = case.get("input")
+            if not fixture or not (root / fixture).is_file():
+                errors.append(f"{case_id}: local fixture is missing: {fixture}")
+            else:
+                expected_hash = case.get("fixture_sha256")
+                actual_hash = sha256(root / fixture)
+                if not isinstance(expected_hash, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_hash):
+                    errors.append(f"{case_id}: fixture_sha256 must be a lowercase SHA-256")
+                elif expected_hash != actual_hash:
+                    errors.append(
+                        f"{case_id}: fixture hash drifted (manifest={expected_hash}, actual={actual_hash})"
+                    )
+            if not REQUIRED_INPUT_KINDS.issubset(set(case.get("input_kinds", []))):
+                errors.append(f"{case_id}: path/bytes/reader coverage is incomplete")
+            if not REQUIRED_HINTS.issubset(set(case.get("hints", []))):
+                errors.append(f"{case_id}: none/mime/extension hint coverage is incomplete")
+            if not case.get("modes"):
+                errors.append(f"{case_id}: at least one executable mode is required")
+    missing = REQUIRED_FORMATS - seen_formats
+    if missing:
+        errors.append("Tier A formats missing from Phase 2 manifest: " + ", ".join(sorted(missing)))
+    for tier, formats in data.get("tiers", {}).items():
+        if tier not in {"A","B","C"} or not isinstance(formats, list):
+            errors.append(f"invalid tier declaration: {tier!r}")
+    for tier, formats in data.get("tiers", {}).items():
+        for fmt in formats:
+            if not any(case.get("format") == fmt and case.get("tier") == tier for case in cases):
+                errors.append(f"tier format has no enrolled case: {tier}/{fmt}")
+    if not data.get("comparison", {}).get("unclassified_difference_is_failure"):
+        errors.append("unclassified differences must be a blocking failure")
+    executable_ids = {case.get("id") for case in cases if case.get("source") == "upstream-compatible-local"}
+    if set(reviewed) != executable_ids:
+        errors.append("reviewed upstream difference fields must exactly cover executable cases")
+    allowed_fields = {"headings", "paragraphs", "tables", "links", "assets"}
+    for case_id, fields in reviewed.items():
+        if not isinstance(fields, list) or len(fields) != len(set(fields)) or not set(fields).issubset(allowed_fields):
+            errors.append(f"{case_id}: reviewed upstream difference fields are invalid")
+    return errors
+
+def main() -> int:
+    errors = validate()
+    if errors:
+        for error in errors:
+            print(f"Phase 2 contract manifest: {error}", file=sys.stderr)
+        return 1
+    print("Phase 2 contract manifest, coverage dimensions and difference taxonomy pass")
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/compatibility/contract-manifest.json b/tools/compatibility/contract-manifest.json
new file mode 100644
index 00000000..81987837
--- /dev/null
+++ b/tools/compatibility/contract-manifest.json
@@ -0,0 +1,765 @@
+{
+  "schema_version": 1,
+  "upstream": {
+    "project": "microsoft/markitdown",
+    "tag": "v0.1.7",
+    "commit": "fd239d5d2be43d9b68329730206b9312c7d5a388",
+    "license": "MIT",
+    "repository": "https://github.com/microsoft/markitdown",
+    "test_root": "packages/markitdown/tests/test_files"
+  },
+  "upstream_files": {
+    "equations.docx": "339b064492530598859de0bde8504de7a4aefead88210baf3e9f3db0ed925b40",
+    "test_svg_no_fallback.pptx": "f8f966fd01be50cee72a6912ad48c1a473baf374db4a7dd1baf65fb11d9a532e",
+    "test.docx": "ee1974633f3b1e8bb54201abce779a755cb1cd5259641a08cf7b1b9b36dec42b",
+    "test.xlsx": "a867be6ece38a4224bcfe34312e5c296ed520a76a431e0454603ceb171fbd4af",
+    "test.pptx": "f0b9e5252aec3730c91f276a7c3b8f4a9893a7b66540f6c6af160a49855ca507",
+    "test.pdf": "77c4014cf15ea5e56663e9b8093ddc2a89a9224c15d6a9eb2aa8af2b48e1b237",
+    "test_blog.html": "a4668c9aa9e639a193a1582de35786239bd71d457dc534a2a32e642606ffa221",
+    "test_mskanji.csv": "184c3dbe4c92d80c0ffef7141dc2401d6ed2fed2e001d444dffb3c3414ce5ff9",
+    "test.json": "d489e024aee6ef05f4c6eba3c64fe14404b7b39281385ead3eae0afec92dfe7f",
+    "test_rss.xml": "d94148d91336e3c87cc4311b0e9f780ccb405d5ff075e6b814b5bc955094d7c2",
+    "test_notebook.ipynb": "60bc053abcbdb10588c9bdc7d59436a8b09604b1e7d5e57a093ba31e555e1505",
+    "test_files.zip": "fdc6402d0c47d7f2891f9bb46a0389024c63b0aa6325596027519bbe2ded7f05",
+    "test.epub": "33e65f39f54bd24f74d5f333d24213a68c62ee2f2854d12f8c4c59b15a4031a7",
+    "test_outlook_msg.msg": "028d84ffe67e1865009669d13d4c12682943b32eccf7f84a8da1899db63b0131",
+    "test.xls": "17a94b6514e8998f4dc25bc77265b6f62982c18614ba4401a87fa01f90f53f1d"
+    ,"test_wikipedia.html": "4c1f6c5ca1147455b8df8b19cd957844cad37d23d541c039af421a7634074ea6"
+    ,"test_serp.html": "ac6e1a5f16dfcdb3b04725a08a9379dcf37d3c48bde16cbd3c210279cee39f52"
+  },
+  "comparison": {
+    "normalizer": "markdown-structure-v1",
+    "unclassified_difference_is_failure": true,
+    "allowed_categories": [
+      "bug",
+      "upstream_feature_missing",
+      "expected_enhancement",
+      "undefined_behavior",
+      "unsupported_by_design"
+    ]
+  },
+  "reviewed_upstream_differences": {
+    "docx-equations": ["paragraphs"],
+    "pptx-chart-cache": ["headings", "paragraphs", "tables", "links", "assets"],
+    "pptx-svg-fallback": ["headings", "paragraphs", "links", "assets"],
+    "xlsx-basic": [],
+    "pdf-text": ["headings", "paragraphs"],
+    "html-entities": ["headings", "paragraphs", "links", "assets"],
+    "csv-cp932": [],
+    "json-basic": ["paragraphs", "tables"],
+    "xml-basic": ["headings", "paragraphs", "links"],
+    "ipynb-basic": ["paragraphs", "tables"],
+    "zip-basic": ["headings", "paragraphs", "tables", "links", "assets"],
+    "epub-basic": ["headings", "paragraphs"],
+    "markdown-basic": [],
+    "yaml-basic": ["paragraphs", "tables"],
+    "toml-basic": ["paragraphs", "tables"]
+  },
+  "tiers": {
+    "A": [
+      "docx",
+      "xlsx",
+      "pptx",
+      "pdf",
+      "html",
+      "csv",
+      "json",
+      "xml",
+      "ipynb",
+      "zip",
+      "epub"
+    ],
+    "B": [
+      "eml",
+      "markdown",
+      "yaml",
+      "toml"
+    ],
+    "C": [
+      "xls",
+      "outlook-msg",
+      "rss",
+      "atom",
+      "wikipedia",
+      "youtube",
+      "bing-serp"
+    ]
+  },
+  "cases": [
+    {
+      "id": "docx-equations",
+      "format": "docx",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/docx/docx_advanced_synthetic.docx",
+      "upstream_file": "equations.docx",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "accurate"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "contains": [
+          "x \\+ y"
+        ],
+        "math": "preserved-text-signature"
+      },
+      "classification": "upstream_feature_missing",
+      "fixture_sha256": "e068adc11ccaead0004a8cd2b4a39b45b5f8f437f0a7c0854b7fdb21918ed768",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics",
+        "math"
+      ]
+    },
+    {
+      "id": "pptx-chart-cache",
+      "format": "pptx",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/pptx/pptx_chart_cache_synthetic.pptx",
+      "upstream_file": "test.pptx",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "accurate"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "contains": [
+          "Quarterly revenue",
+          "1970-01-01",
+          "| North |"
+        ],
+        "not_contains": [
+          "[Unsupported PPTX chart"
+        ]
+      },
+      "classification": "expected_enhancement",
+      "fixture_sha256": "ef880baee6c3ad948333f7a57bc1a0f67b000776c1f7bf5d1435d5e3b85135c0",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics",
+        "chart",
+        "svg_assets"
+      ]
+    },
+    {
+      "id": "pptx-svg-fallback",
+      "format": "pptx",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/pptx/pptx_simple.pptx",
+      "upstream_file": "test_svg_no_fallback.pptx",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "asset_policy": "preserve-original-or-diagnostic"
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "8e07969ae725de04d9300aab505a0f5c7eb207e7a63a7d1e32dd2aeeea673d27",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics",
+        "chart",
+        "svg_assets"
+      ]
+    },
+    {
+      "id": "xlsx-basic",
+      "format": "xlsx",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/xlsx/sheet_simple.xlsx",
+      "upstream_file": "test.xlsx",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "accurate",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "contains": [
+          "Sheet1"
+        ]
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "f05289a8e14b1f30e5ced34daeeed63a9c28b14bcca5eb97ed51a56f6f81c577",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "pdf-text",
+      "format": "pdf",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/pdf/text_simple.pdf",
+      "upstream_file": "test.pdf",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "accurate"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "ff68dae545ca8b437b028c97dfade55c2a09bb75d4cb614f5d6c0eadbb5bef28",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "html-entities",
+      "format": "html",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/html/html_entities.html",
+      "upstream_file": "test_blog.html",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "17070693e09bfc5c67618e627b018ebd6c536ecf8f4d44564522d73e52ea95fc",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "csv-cp932",
+      "format": "csv",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/csv/csv_basic.csv",
+      "upstream_file": "test_mskanji.csv",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "1e9bf0c637bb6b4eeeab8f6c6ecf90d43ca1d2f0e234c3c314e7a4e861f48c26",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "json-basic",
+      "format": "json",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/json/json_object_basic.json",
+      "upstream_file": "test.json",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "c84aa1cad1d6b6e75f9f8fddbaff93b74cfe3c6f1e7eb39a51bd9ae4446ee231",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "rss-unsupported",
+      "format": "rss",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_rss.xml",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "xls-unsupported",
+      "format": "xls",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test.xls",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "msg-binary-unsupported",
+      "format": "outlook-msg",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_outlook_msg.msg",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "xml-basic",
+      "format": "xml",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/xml/xml_basic.xml",
+      "upstream_file": "test_rss.xml",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "15395cdb0483e51d53315ea2946a2d59f90b6a2c82e7566b2e50bf1dcab11f79",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "ipynb-basic",
+      "format": "ipynb",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/ipynb/ipynb_markdown_basic.ipynb",
+      "upstream_file": "test_notebook.ipynb",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "bf11f71f155429535c737877d948596dfa2014284ee5a0aedbb595a2b06a35c0",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "zip-basic",
+      "format": "zip",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/zip/zip_basic_structured.zip",
+      "upstream_file": "test_files.zip",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "8abcac29696bdb24359e958c6744d7701038ada11a310721f1f093f6fe7936eb",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "epub-basic",
+      "format": "epub",
+      "tier": "A",
+      "input": "samples/fixtures/contracts/epub/epub_basic_package.epub",
+      "upstream_file": "test.epub",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "c466798fd58d9c8453688e5baec85cef53b916347bae2ab285695e83b748a1fe",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "markdown-basic",
+      "format": "markdown",
+      "tier": "B",
+      "input": "samples/fixtures/contracts/markdown/markdown_basic_heading_paragraph.md",
+      "upstream_file": "test_blog.html",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "25068aaf7a4e2020699499c71f9301abed9889de2a3c675f37584ee67988703e",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "yaml-basic",
+      "format": "yaml",
+      "tier": "B",
+      "input": "samples/fixtures/contracts/yaml/yaml_mapping_basic.yaml",
+      "upstream_file": "test.json",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance",
+        "stream"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "6d4e410ee0a9b6eda83a92fafa7493c3f3a07e05c4aebfa340e3ff4827ef26eb",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "toml-basic",
+      "format": "toml",
+      "tier": "B",
+      "input": "samples/fixtures/contracts/toml/toml_object_basic.toml",
+      "upstream_file": "test.json",
+      "source": "upstream-compatible-local",
+      "modes": [
+        "balance"
+      ],
+      "input_kinds": [
+        "path",
+        "text",
+        "bytes",
+        "reader"
+      ],
+      "hints": [
+        "none",
+        "mime",
+        "extension"
+      ],
+      "signals": {
+        "non_empty": true
+      },
+      "classification": "undefined_behavior",
+      "fixture_sha256": "0f6e94c97ad5a3dd454eb92ff80c563a6c4c122582d696e323e3730292a0679f",
+      "comparison_fields": [
+        "headings",
+        "paragraphs",
+        "tables",
+        "links",
+        "assets",
+        "diagnostics"
+      ]
+    },
+    {
+      "id": "atom-unsupported",
+      "format": "atom",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_rss.xml",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "wikipedia-unsupported",
+      "format": "wikipedia",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_wikipedia.html",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "youtube-unsupported",
+      "format": "youtube",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_youtube.html",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "bing-serp-unsupported",
+      "format": "bing-serp",
+      "tier": "C",
+      "input": null,
+      "upstream_file": "test_serp.html",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "unsupported",
+        "error_code": "MID-0001"
+      },
+      "classification": "unsupported_by_design"
+    },
+    {
+      "id": "eml-reference",
+      "format": "eml",
+      "tier": "B",
+      "input": null,
+      "upstream_file": "test.eml",
+      "source": "upstream-reference-only",
+      "modes": [],
+      "input_kinds": [],
+      "hints": [],
+      "signals": {
+        "status": "stable-reference",
+        "note": "local EML corpus is maintained by the pinned external quality lab"
+      },
+      "classification": "undefined_behavior"
+    }
+  ]
+}
diff --git a/tools/compatibility/difference-categories.json b/tools/compatibility/difference-categories.json
new file mode 100644
index 00000000..c347e0d4
--- /dev/null
+++ b/tools/compatibility/difference-categories.json
@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "categories": {
+    "bug": {"owner":"format-owner","action":"fix before golden update","release_effect":"blocking"},
+    "upstream_feature_missing": {"owner":"format-owner","action":"record issue and capability impact","release_effect":"experimental-or-gap"},
+    "expected_enhancement": {"owner":"api-owner","action":"assert project contract separately","release_effect":"non-regression"},
+    "undefined_behavior": {"owner":"quality-owner","action":"do not update golden without decision","release_effect":"review-required"},
+    "unsupported_by_design": {"owner":"api-owner","action":"keep stable unsupported status and code","release_effect":"documented"}
+  }
+}
diff --git a/tools/compatibility/fetch_upstream_corpus.py b/tools/compatibility/fetch_upstream_corpus.py
new file mode 100644
index 00000000..1b775a68
--- /dev/null
+++ b/tools/compatibility/fetch_upstream_corpus.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Fetch and verify the exact MarkItDown v0.1.7 reference fixtures."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+from urllib.request import urlopen
+
+ROOT = Path(__file__).resolve().parents[2]
+MANIFEST = ROOT / "tools/compatibility/contract-manifest.json"
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output", type=Path, default=ROOT / ".tmp/compatibility/upstream-v0.1.7")
+    parser.add_argument("--check", action="store_true")
+    args = parser.parse_args()
+    data = json.loads(MANIFEST.read_text(encoding="utf-8"))
+    base = "https://raw.githubusercontent.com/microsoft/markitdown/" + data["upstream"]["commit"] + "/" + data["upstream"]["test_root"] + "/"
+    errors = []
+    for name, expected in data["upstream_files"].items():
+        target = args.output / name
+        if not target.is_file() and args.check:
+            errors.append(f"missing upstream fixture: {name}")
+            continue
+        if not target.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                with urlopen(base + name, timeout=60) as response:
+                    target.write_bytes(response.read())
+            except Exception:
+                # Reference-only web fixtures live beside the format corpus.
+                reference_base = base.replace("/test_files/", "/")
+                with urlopen(reference_base + name, timeout=60) as response:
+                    target.write_bytes(response.read())
+        actual = digest(target.read_bytes())
+        if actual != expected:
+            errors.append(f"hash mismatch for {name}: expected {expected}, got {actual}")
+    if errors:
+        for error in errors:
+            print("Phase 2 upstream corpus: " + error, file=sys.stderr)
+        return 1
+    print(f"verified {len(data['upstream_files'])} MarkItDown {data['upstream']['tag']} fixtures under {args.output}")
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/compatibility/run_contract_lab.py b/tools/compatibility/run_contract_lab.py
new file mode 100644
index 00000000..1650bce1
--- /dev/null
+++ b/tools/compatibility/run_contract_lab.py
@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Execute local Phase 2 contract cases and compare structural signals."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+MANIFEST = ROOT / "tools/compatibility/contract-manifest.json"
+
+def structure(markdown: str) -> dict[str, object]:
+    lines = markdown.splitlines()
+    return {
+        "headings": [line.lstrip("#").strip() for line in lines if line.startswith("#")],
+        "paragraphs": [line.strip() for line in lines if line.strip() and not line.startswith(("#", "|", "- ", ">", "```", "!["))],
+        "tables": [line.strip() for line in lines if line.startswith("|")],
+        "links": re.findall(r"\[[^\]]*\]\(([^)]+)\)", markdown),
+        "assets": re.findall(r"!\[[^\]]*\]\(([^)]+)\)", markdown),
+        "math_markers": [line for line in lines if "math" in line.lower() or "omml" in line.lower()],
+        "text": markdown,
+    }
+
+def compare_structures(local: dict[str, object], upstream: dict[str, object]) -> list[str]:
+    differences = []
+    for field in ["headings", "paragraphs", "tables", "links", "assets"]:
+        if local.get(field) != upstream.get(field):
+            differences.append(field)
+    return differences
+
+def run_case(cli: Path, case: dict[str, object], root: Path, mode: str, upstream: Path | None = None, upstream_corpus: Path | None = None, reviewed_differences: dict[str, list[str]] | None = None) -> tuple[bool, str, dict[str, object]]:
+    fixture = case.get("input")
+    if not fixture:
+        return True, "reference-only", {}
+    signals = case.get("signals", {})
+    input_path = root / str(fixture)
+    if upstream_corpus is not None and case.get("upstream_file"):
+        candidate = upstream_corpus / str(case["upstream_file"])
+        suffix = candidate.suffix.lower().lstrip(".")
+        expected = str(case.get("format", "")).lower()
+        compatible_suffixes = {expected}
+        if expected == "html": compatible_suffixes |= {"htm"}
+        if expected == "markdown": compatible_suffixes |= {"md", "markdown"}
+        if expected in {"yaml", "toml", "json"}: compatible_suffixes.add("json")
+        if candidate.is_file() and suffix in compatible_suffixes:
+            input_path = candidate
+    with tempfile.TemporaryDirectory(prefix="markitdown-phase2-") as temp:
+        output = Path(temp) / "result.md"
+        command = [str(cli), mode, str(input_path), str(output)]
+        completed = subprocess.run(command, cwd=root, text=True, capture_output=True, timeout=90)
+        if completed.returncode != 0:
+            return False, completed.stderr.strip() or "CLI failed", {}
+        text = output.read_text(encoding="utf-8")
+        view = structure(text)
+        enforce_case_signals = upstream_corpus is None
+        for fragment in signals.get("contains", []) if enforce_case_signals else []:
+            if fragment not in text:
+                return False, f"missing required fragment: {fragment!r}", view
+        for fragment in signals.get("not_contains", []) if enforce_case_signals else []:
+            if fragment in text:
+                return False, f"forbidden fragment present: {fragment!r}", view
+        if signals.get("non_empty") and not text.strip():
+            return False, "successful conversion produced empty output", view
+        if signals.get("diagnostic"):
+            debug_output = Path(temp) / "debug.json"
+            debug = subprocess.run(
+                [str(cli), mode, "--debug", str(input_path), str(debug_output)],
+                cwd=root, text=True, capture_output=True, timeout=90,
+            )
+            if debug.returncode != 0 or signals["diagnostic"] not in debug_output.read_text(encoding="utf-8"):
+                return False, f"missing diagnostic: {signals['diagnostic']}", view
+        if enforce_case_signals and signals.get("math") == "preserved-text-signature" and not view["math_markers"] and "x \\+ y" not in str(view["text"]):
+            return False, "missing preserved math text signature", view
+        if upstream is None:
+            return True, "pass", view
+        reference = Path(temp) / "upstream.md"
+        baseline = subprocess.run(
+            [str(upstream), str(input_path), "-o", str(reference)],
+            cwd=root, text=True, capture_output=True, timeout=90,
+        )
+        if baseline.returncode != 0:
+            return False, baseline.stderr.strip() or "upstream CLI failed", view
+        upstream_view = structure(reference.read_text(encoding="utf-8"))
+        differences = compare_structures(view, upstream_view)
+        expected_differences = None if reviewed_differences is None else reviewed_differences.get(str(case["id"]))
+        if upstream_corpus is not None and expected_differences is None:
+            return False, "missing reviewed upstream difference fields", view
+        if expected_differences is not None and sorted(differences) != sorted(expected_differences):
+            return False, "observed structural difference fields differ from reviewed expectation: " + ",".join(differences), view
+        if differences and not case.get("classification"):
+            return False, "unclassified structural difference: " + ",".join(differences), view
+        if differences:
+            return True, "classified difference: " + ",".join(differences) + " (" + str(case["classification"]) + ")", view
+        return True, "semantic structure match", view
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--cli", type=Path, required=True)
+    parser.add_argument("--format")
+    parser.add_argument("--upstream", type=Path)
+    parser.add_argument("--upstream-corpus", type=Path)
+    args = parser.parse_args()
+    data = json.loads(MANIFEST.read_text(encoding="utf-8"))
+    failures = 0
+    executed = 0
+    for case in data["cases"]:
+        if case.get("source") != "upstream-compatible-local":
+            continue
+        if args.format and case["format"] != args.format:
+            continue
+        modes = case.get("modes", [])
+        if args.upstream_corpus is not None and modes:
+            modes = modes[:1]
+        for mode in modes:
+            executed += 1
+            ok, detail, view = run_case(args.cli, case, ROOT, str(mode), args.upstream, args.upstream_corpus, data.get("reviewed_upstream_differences"))
+            status = "PASS" if ok else "FAIL"
+            print(f"{status}\t{case['id']}\t{case['format']}\t{mode}\t{detail}")
+            if not ok:
+                failures += 1
+                print(json.dumps(view, ensure_ascii=True, sort_keys=True), file=sys.stderr)
+    print(f"Phase 2 local contract cases: {executed} executed, {failures} failed")
+    return 1 if failures else 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/compatibility/tests/test_contract_manifest.py b/tools/compatibility/tests/test_contract_manifest.py
new file mode 100644
index 00000000..54736d90
--- /dev/null
+++ b/tools/compatibility/tests/test_contract_manifest.py
@@ -0,0 +1,44 @@
+import importlib.util
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[3]
+
+def load(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+class ContractManifestTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.checker = load("phase2_checker", ROOT / "tools/compatibility/check_contract_manifest.py")
+
+    def test_repository_manifest_passes(self):
+        self.assertEqual(self.checker.validate(), [])
+
+    def test_unclassified_difference_is_rejected(self):
+        with tempfile.TemporaryDirectory() as raw:
+            root = Path(raw)
+            (root / "tools/compatibility").mkdir(parents=True)
+            manifest = json.loads((ROOT / "tools/compatibility/contract-manifest.json").read_text())
+            manifest["cases"][0].pop("classification")
+            (root / "tools/compatibility/contract-manifest.json").write_text(json.dumps(manifest))
+            categories = (ROOT / "tools/compatibility/difference-categories.json").read_text()
+            (root / "tools/compatibility/difference-categories.json").write_text(categories)
+            self.assertTrue(any("classification" in e for e in self.checker.validate(root)))
+
+    def test_reference_only_cases_cannot_claim_input_coverage(self):
+        data = json.loads((ROOT / "tools/compatibility/contract-manifest.json").read_text())
+        cases = [case for case in data["cases"] if case["source"] == "upstream-reference-only"]
+        self.assertEqual(
+            {case["format"] for case in cases},
+            {"rss", "atom", "xls", "outlook-msg", "wikipedia", "youtube", "bing-serp", "eml"},
+        )
+        self.assertTrue(all(case["input_kinds"] == [] for case in cases))
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/governance/check_documentation.py b/tools/governance/check_documentation.py
index 17c59a95..c1c65273 100644
--- a/tools/governance/check_documentation.py
+++ b/tools/governance/check_documentation.py
@@ -32,6 +32,8 @@
     "docs/migration-0.8.md",
     "docs/performance.md",
     "docs/project-maintenance-plan.md",
+    "docs/phase-2-compatibility-lab.md",
+    "docs/adr/0005-phase-2-compatibility-lab.md",
 }
 RETIRED_DOCUMENTS = {"docs/migration-0.7.md"}
 CURRENT_NARRATIVES = {
diff --git a/tools/governance/tests/test_governance.py b/tools/governance/tests/test_governance.py
index e01b37db..62484408 100644
--- a/tools/governance/tests/test_governance.py
+++ b/tools/governance/tests/test_governance.py
@@ -29,6 +29,9 @@ def setUpClass(cls):
         cls.documentation = load_module(
             "check_documentation", ROOT / "tools/governance/check_documentation.py"
         )
+        cls.compatibility = load_module(
+            "check_contract_manifest", ROOT / "tools/compatibility/check_contract_manifest.py"
+        )
 
     def test_toolchain_parser_reads_all_components(self):
         output = """moon 0.1.20260803 (c19f78e 2026-08-03) ~/.moon/bin/moon
@@ -118,6 +121,9 @@ def test_source_root_rejects_moon_packages_outside_src(self):
     def test_documentation_contract_passes_repository(self):
         self.assertEqual(self.documentation.verify(), [])
 
+    def test_phase2_contract_manifest_passes_repository(self):
+        self.assertEqual(self.compatibility.validate(), [])
+
     def test_documentation_link_parser_only_returns_local_paths(self):
         self.assertEqual(
             self.documentation.local_link_target("../docs/README.md#lifecycle"),