分舟载模，共引一源 · Split runtime from the Small model facade

.github/workflows/pull-request.yml

@@ -22,6 +22,11 @@ jobs:
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: "22"
+      - name: Check the N2 workspace contracts
+        run: |
+          npm ci --ignore-scripts --no-audit --no-fund --omit=optional
+          npm run typecheck
+          npm run test:workspace
       - name: Validate repository and release tooling contracts
         run: python -m unittest discover -s tests/python -p 'test_*.py'
       - name: Bootstrap pinned inputs and prove the dependency cache is complete

.gitignore

@@ -4,6 +4,7 @@
 /models/generated/
 /reports/
 /dist/
+/node_modules/
 .DS_Store
 __pycache__/
 *.pyc

docs/decisions.md

@@ -251,6 +251,21 @@ Reason: Roadmap §5.2 requires a small, stable command surface, but the draft ha
 
 Consequence: This decision fixes the stable CLI surface for N1. Adding flags requires a new decision; exit codes are additive-only. The `info` subcommand departure from roadmap §5.2's top-level flag wording is recorded here. Core `Engine::detect()` signature and `DetectionResult` structure are implementation details resolved during implementation per [cli-design.md §8](cli-design.md), not a separate product decision.
 
+### D107 — Split model-free runtime from exact model facades
+
+Status: Accepted for N2 stage 1
+Authority: N2 package topology and monorepo migration ([roadmap §3.1, §3.4 and §6](roadmap.md)); directory and migration details in [monorepo-design.md](monorepo-design.md)
+
+Decision: `@arcships/light-ocr-runtime` owns the Node adapter, scheduler, encoded-image/native loading and public OCR types without carrying a default model. Direct runtime callers must pass an explicit local `bundlePath`; the runtime never accepts a model alias and never downloads a bundle. `@arcships/light-ocr`, `@arcships/light-ocr-tiny` and `@arcships/light-ocr-medium` are thin model facades that exact-pin one compatible runtime and one model package, reuse the runtime's `OcrError` identity and public engine/result types, and differ only in their built-in model resolution and package/CLI names. The default `@arcships/light-ocr` facade remains PP-OCRv6 Small and remains the only owner of the `light-ocr` bin.
+
+Packages use independent versions. A facade release exact-pins its tested runtime, native and model combination; no caret, tilde, tag or workspace range enters a published manifest. The new runtime starts private in the workspace and may publish as a preview only after its standalone tarball, platform optional dependencies and model-free API pass install tests. Starting N2 does not itself authorize a `0.4.0` facade release; the minor version is cut only after the runtime topology is publishable and the default Small experience remains compatible.
+
+Migration uses npm workspaces under `packages/*`. The non-package `native/` CMake tree stays outside npm workspaces. `bindings/node/` remains the `0.3.x` compatibility/release source until the new runtime and Small facade pass one focused semantic-equivalence check; CI does not run duplicate full native matrices during this overlap. Tiny is added only after this cutover. Medium remains prerelease until its own product-quality evidence justifies GA.
+
+Reason: Three model cups need one adapter, error model and result schema, while users must install only the model they selected. Separating model selection from runtime mechanics prevents three copies of the Node implementation and lets unchanged native/model packages be reused without rebuilding them for a facade-only change.
+
+Consequence: Runtime/model/native packages can evolve independently, while each user-facing facade records an exact compatible composition. Model aliases are facade concerns; explicit `bundlePath` is the runtime escape hatch. N2 stage 1 is an internal migration and adds no new public cup until package cutover evidence exists.
+
 ## 3. Deferred decisions
 
 ### D102 — Public native SDK and ABI policy

docs/implementation-status.md

@@ -1,14 +1,24 @@
 # C++ Core 与 Node-API 实施状态
 
-更新时间：2026-07-19<br>
-结论：`@arcships/light-ocr@0.3.0` 与五个依赖包已发布，npm `next`/`latest` 均指向 `0.3.0`。该版本交付 Direct Core ML Apple provider、Linux x64 glibc/Windows x64 official Native WebGPU Plugin EP、D112 Auto 与自包含 npm payload；Apple M4、Linux/NVIDIA 与 Windows/AMD 的审阅证据及产物哈希均已进入 production lock。
+更新时间：2026-07-22<br>
+结论：`@arcships/light-ocr@0.3.4` 与七个依赖包已发布，npm `next`/`latest` 均指向 `0.3.4`。`0.3.0` 交付的 Direct Core ML、Native WebGPU、D112 Auto 与自包含 payload 保持有效；`0.3.4` 修复 N1 CLI ROI 的 native option contract。N2 阶段 1 已按 D107 启动内部 workspace 迁移，但尚未发布 runtime、tiny 或 medium。
 
 状态含义：
 
 - **Done**：代码存在，并有本地实际运行证据。
 - **Configured**：自动化已写好，但当前工作区未产生真实远端 run 证据。
 - **Pending**：需要外部平台或制品仓动作。
 
+## N2 阶段 1：runtime / Small facade 拆分
+
+状态：In progress
+
+- 根目录已采用仅覆盖 `packages/*` 的 npm workspaces；CMake `native/` 源码不伪装为 npm package。
+- `packages/runtime/` 建立 model-free `@arcships/light-ocr-runtime`：直接调用必须显式提供本地 `bundlePath`，不接受 model alias，不下载模型。
+- `packages/light-ocr/` 建立默认 Small facade：复用 runtime 的 engine/types/`OcrError`，精确依赖 runtime 与 Small model，并独占 `light-ocr` bin。
+- `bindings/node/` 暂时保留为 `0.3.x` 兼容发布源。切换前只运行一条 workspace 语义检查，不复制整套原生矩阵。
+- tiny 尚未接入；下一步是消除旧 facade 与 workspace facade 的源码重复，并让 release assembler 能独立产出 runtime + Small meta tarball。
+
 ## 需求验收矩阵
 
 | `requirements.md` §19 条目 | 状态 | 当前证据或缺口 |

docs/monorepo-design.md

@@ -1,6 +1,6 @@
 # light-ocr Monorepo 设计
 
-状态：草案（2026-07-21）。
+状态：已接受用于 N2 阶段 1（2026-07-22）。
 受众：维护者、贡献者。本文定义 monorepo 的目录结构、包依赖关系、迁移路径和约束，不替代各包自身的实现设计。
 
 ## 1. 动机
@@ -110,13 +110,12 @@ Server 依赖 `@arcships/light-ocr`（默认 small），而不是 `runtime`。
 {
   "private": true,
   "workspaces": [
-    "packages/*",
-    "native"
+    "packages/*"
   ]
 }
 ```
 
-- `npm install` 在根目录执行，自动为所有 workspace 安装依赖并创建 symlink。
+- `npm install` 在根目录执行，自动为所有 `packages/*` workspace 安装依赖并创建 symlink；`native/` 是 CMake 源码目录，不伪装成 npm workspace。
 - `npm test --workspaces` 运行所有包的测试。
 - `npm publish --workspace packages/light-ocr` 发布单个包。
 
@@ -157,7 +156,7 @@ bindings/node/          # @arcships/light-ocr，JS + native addon 混合
 - 创建 `packages/light-ocr/`，依赖 `runtime` + 模型包，包含 CLI bin。
 - `native/` 保持 addon 源码 + CMake，平台预编译包独立发布。
 - `bindings/node/` 标记为 deprecated，保留到确认迁移稳定后删除。
-- 此阶段 CI 同时运行旧路径和新 workspace。
+- 此阶段保留 `bindings/node/` 作为 `0.3.x` 发布兼容入口，但只增加一条 workspace 契约检查，不重复运行两套完整原生矩阵；切换发布源之前必须证明 workspace facade 与旧入口的 API、错误类型和真实 OCR 语义一致。
 
 ### 5.3 阶段 2：加入 server（N2 完成或 N3 前后）
 

package.json

@@ -0,0 +1,17 @@
+{
+  "name": "light-ocr-workspace",
+  "private": true,
+  "packageManager": "npm@11.0.0",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "npm test --workspaces --if-present",
+    "test:workspace": "npm test --workspace @arcships/light-ocr-runtime && npm test --workspace @arcships/light-ocr",
+    "typecheck": "tsc --strict --noEmit --skipLibCheck false --target ES2022 --module NodeNext --moduleResolution NodeNext --types node tools/npm/smoke.ts packages/runtime/test/types.ts"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "5.9.3"
+  }
+}