dsh-ab-ocr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-ab-ocr contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+---
+description: "The out-of-tree ocr tool: recognizes a scanned PDF or image page by page, merges the pages in order only after the last one, and saves one Markdown document with the heading levels the model decided."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-ab-ocr
+
+## Summary
+
+`dsh-ab-ocr` gives this machine's `dsh` profiles one way to read a document whose text cannot be selected. One `ocr` call renders, recognizes, and merges every page of a PDF or a still image, and saves the result as one Markdown document: page numbers and repeated edge lines removed, the whitespace a line box leaves behind removed, and paragraphs rejoined across page breaks.
+
+The outline is a two-step shape. The merge infers a heading level for every line it can, and writes the lines a reader might call headings to a small outline file beside the document. The conversation's model reads that file, decides the levels, and calls `ocr` again with a `levels` value; the second call rewrites the document from the geometry it stored, without recognizing anything again. With no second call the document is still complete — it simply carries the inferred outline.
+
+The OCR engine is RapidOCR, whose PP-OCRv6 detection, classification, and recognition weights ship inside the wheel, so installing the dependencies *is* installing the model. The environment is created from inside the package by `pnpm run setup`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Install the engine](#install-the-engine)
+- [Configuration](#configuration)
+- [What one call records](#what-one-call-records)
+- [Where the files go](#where-the-files-go)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Evidence](#evidence)
+- [`./invariant`](#invariant)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the row in a profile when the agent should read a scan, a photographed page, a screenshot, or a PDF whose text cannot be selected. The row injects `ctx.tools` and `ctx.systemPrompt`: the tool reaches the model catalog through the ordinary schema assembly, and the prompt through the ordinary section assembly. Mounting it adds no provider — every file it writes goes through the filesystem capability the composition already has.
+
+### Mount it in a profile
+
+```yaml
+# <DSH_HOME>/profiles/<profile>/cordis.patch.yml
+- insert:
+    - id: ocr
+      name: '@deepseek-ai/dsh-ab-ocr'
+      config:
+        dpi: 200
+        maxPixels: 12000000
+        maxPages: 2000
+        maxDocuments: 20
+        timeoutMs: 1800000
+        startupTimeoutMs: 60000
+        maxOutlineCandidates: 400
+        engineLifetime: perDocument
+        writePageFiles: true
+        outlineCandidateRatio: 1.05
+```
+
+```json
+// <DSH_HOME>/profiles/<profile>/package.json
+"@deepseek-ai/dsh-ab-ocr": "link:<plugins root>/plugins/dsh-ab-ocr"
+```
+
+Every bound that block states is required: the row is where this deployment says how much work, memory, time, and disk it is willing to carry, and a row that omits one fails to load naming the field. The recognition heuristics have documented defaults and appear here only when this deployment wants a different value.
+
+Run `pnpm install` in the profile directory after editing either file.
+
+<a id="install-the-engine"></a>
+### Install the engine
+
+The Python environment is separate from pnpm and is created by a script inside this package:
+
+```sh
+pnpm --dir <plugins root>/plugins/dsh-ab-ocr run setup
+```
+
+It finds a base interpreter, creates `python/.venv`, installs `python/requirements.txt`, runs the worker's own `--self-test`, and reports the interpreter, the package versions, and the model files the wheel carries. It is idempotent: a run against a working environment verifies and exits without touching the network.
+
+| Flag | Effect |
+|---|---|
+| `--python <path>` | Base interpreter to build the environment from (or `DSH_OCR_PYTHON`) |
+| `--prefetch` | Also load the engine once, so the first recognition is not the one that waits for the models |
+| `--force` | Remove the environment and build it again |
+| `--json` | Print the summary as one JSON object |
+
+Installing into the environment needs permission to create directories with a private mode, so run it outside a restricted shell. The tool reports what is missing — and names this script — when a call arrives without an environment.
+
+<a id="configuration"></a>
+### Configuration
+
+Every field is overridable from the row. A field the deployment owns is **required** — it has no value inside the package, because a hidden default would state an agreement the deployment never made — and a field whose default is a documented resolution rule or a recognition heuristic is **defaulted**.
+
+| Field | Required | Default | Meaning |
+|---|---|---|---|
+| `pythonPath` | | (auto) | Interpreter carrying the OCR dependencies |
+| `workerScript` | | (auto) | Worker script to run |
+| `outputDir` | | (beside source) | Where the Markdown files go |
+| `pageDirName` | | `.ocr-pages` | Per-document directory, relative to each output file |
+| `writePageFiles` | yes | — | Write each page's text to its own file as it finishes |
+| `dpi` | yes | — | PDF render resolution |
+| `maxPixels` | yes | — | Ceiling on one rendered page; 0 disables it |
+| `textScore` | | 0.5 | Recognition confidence floor |
+| `detectHeadings` | | `true` | Render the inferred outline into the document |
+| `headingMinRatio` | | 1.18 | Glyph-height ratio that makes a line a heading |
+| `indentRatio` | | 1.0 | Left-edge offset, in body glyph heights, that marks an indented first line |
+| `paragraphGapRatio` | | 0.85 | Vertical gap, in body glyph heights, that separates two paragraphs |
+| `outlineCandidateRatio` | | 1.05 | Glyph-height ratio above which a line becomes an outline candidate |
+| `maxOutlineCandidates` | yes | — | Most candidates one document's outline file may list |
+| `detectColumns` | | `true` | Split a page at a vertical gutter |
+| `removePageNumbers` | | `true` | Drop folios |
+| `removeRunningHeads` | | `true` | Drop lines repeated in the edge bands |
+| `runningHeadRatio` | | 0.6 | Fraction of pages such a line must appear on |
+| `runningHeadMinPages` | | 3 | Absolute page minimum for that rule |
+| `engineLifetime` | yes | — | Rebuild the engine per document, or share it across the call |
+| `timeoutMs` | yes | — | Ceiling on one recognition; 0 disables it |
+| `startupTimeoutMs` | yes | — | Ceiling on the worker's startup check before the call is refused |
+| `maxPages` | yes | — | Pages a document may carry without an explicit selection; 0 disables it |
+| `maxDocuments` | yes | — | Files one call may name |
+
+The required group is what the tool may cost this machine: the render resolution, the per-page pixel ceiling, the page and file ceilings, the two time ceilings, the outline candidate ceiling, the engine lifetime, and whether per-page text is kept. The defaulted group is what a document reader wants: where the interpreter, the worker, and the artifacts are found, and how a page is read and merged.
+
+`startupTimeoutMs` exists because the startup check is a separate process from the batch. An environment whose engine never loads has to be refused inside the deployment's startup window rather than held for the whole recognition ceiling.
+
+<a id="what-one-call-records"></a>
+### What one call records
+
+```jsonc
+// ocr({ path: "D:/docs/部署规范.pdf" })
+{
+  "documents": [{
+    "input": "D:/docs/部署规范.pdf",
+    "output": "D:/docs/部署规范.md",
+    "pages": 3, "totalPages": 3, "selection": [1, 2, 3],
+    "lines": 16, "headings": 3, "chars": 289,
+    "droppedPageNumbers": 1, "droppedRunningHeads": 0, "joinedAcrossPages": 0,
+    "pageDir": "D:/docs/.ocr-pages/部署规范",
+    "digest": "9c41acae7ce7",
+    "outlinePath": "D:/docs/.ocr-pages/部署规范/9c41acae7ce7/outline.json",
+    "outlineTruncated": false,
+    "corrections": 0,
+    "seconds": 31.56
+  }],
+  "failures": []
+}
+```
+
+A call carrying `levels` reports `corrections` instead of a recognition, and rewrites the Markdown the earlier recognition produced. A document that fails does not discard the others; each failure carries its own path and reason.
+
+<a id="where-the-files-go"></a>
+### Where the files go
+
+For a source named `<stem>.<ext>` under a base directory `<base>` — the source's own directory, or `outputDir`:
+
+| Artifact | Path |
+|---|---|
+| Markdown | `<base>/<stem>.md` |
+| A second recognition of the same source | `<base>/<stem>.<digest12>.md` |
+| Per-page text | `<base>/.ocr-pages/<stem>/<digest12>/page-00001.txt` |
+| Recognition record | `<base>/.ocr-pages/<stem>/<digest12>/record.json` |
+| Outline sheet | `<base>/.ocr-pages/<stem>/<digest12>/outline.json` |
+| Most recent recognition | `<base>/.ocr-pages/<stem>/latest.json` |
+
+The source's extension is replaced by `.md` and every space is removed, so the name is space-free on disk and in a link. Tabs, non-breaking spaces, and the full-width space are removed with it; characters a file system rejects are replaced, a reserved Windows device name gains a leading underscore, and a name that compacts to nothing becomes `document`.
+
+`digest12` is the first twelve hex characters of a hash over the source path and content, the page selection, and the merge settings. The worker reports the source's own content digest as the document starts, so the name follows what the document *is* rather than how large it happens to be: a source edited without changing size is a different recognition, and an unchanged one is always the same recognition. That is how a `levels` call finds what to correct without scanning.
+
+`<stem>.md` is never overwritten with different content: when it already holds another document, the new one takes the digest name. Repeating a recognition whose result is unchanged reuses the file it wrote. `writePageFiles: false` suppresses only the per-page text; the record and the outline are always written, because the correction pass reads them.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+### Design commitments
+
+- **One page in memory.** A page is rendered, recognized, reported, and dropped before the next page is rendered.
+- **A page is saved as it finishes.** The text is written when the page event arrives, so an interrupted run keeps every page it completed.
+- **The document is merged only after the last page.** The merge is a separate pass in the worker, over records it kept; nothing is written to a document while a page is still being recognized.
+- **The engine is released per document.** `engineLifetime: perDocument` rebuilds it for each document, so a batch never holds more than one.
+- **Nothing reads a PDF's text layer.** Every page is rendered and recognized, which is what makes a scan work and what costs time on a text PDF.
+- **Every write goes through ctx.fs.** See [Why every write goes through ctx.fs](#why-every-write-goes-through-ctxfs).
+
+### Why every write goes through ctx.fs
+
+This deployment enforces its file policy in two different places, and only one of them reaches a plugin that opens files itself.
+
+| Layer | What it confines |
+|---|---|
+| The process sandbox | A command started through the sandbox provider, and everything that command spawns |
+| `ctx.fs` | Every mutation a plugin performs through the capability, at the path level |
+
+The base bundle mounts the sandbox-enforcing filesystem provider, so `ctx.fs.writeText` fences each write against the session mode and the writable roots. A plugin that calls the host filesystem directly is fenced by neither. The worker therefore opens only the document it was given and writes to stdout; the page text, the geometry, the merged Markdown, and the outline all travel back as events, and this module writes them through `ctx.fs`.
+
+The capability is read with `ctx.get('fs')` when a call runs and is not listed in the row's `inject`. Cordis satisfies a declared injection by waiting for the service, so declaring `fs` would make the row a provider requirement and leave it unmounted in a composition that has none.
+
+### Why every write carries a fence
+
+A sandboxing backend fences a mutation by a per-call policy, and that policy — not the backend's own default — is the only thing naming the workspace the **calling session** runs in. Calling `writeText` without one makes the backend fall back to the deployment's root, which is the directory the server was launched from; a session working anywhere else then has every artifact refused, one page at a time. `src/sandbox.ts` owns that seam:
+
+- `callFence(ctx, request)` resolves the calling session's policy once per call and refuses a composition that mounts a confining backend with no `ctx.sandboxPolicy`.
+- `saveText(fs, target, content, fence, signal)` is the one path every persisted text goes through, so the fence is applied in one place. Every other write in the plugin (`writeJson`, `writeDocument`, the page files, the correction pass) delegates to it.
+- The resolved fence's `workspaceRoot` is also the base a relative `outputDir` resolves against, so a call that names no directory writes inside the only root the fence will accept. `process.cwd()` is not consulted at all when a policy is available.
+
+The guard has to live at the call rather than at load: `dsh-fs-sandbox` declares `sandboxPolicy` as a declared injection, so in a composition that mounts the backend **without** the policy service the backend is never constructed — `ctx.get('fs')` is `undefined` while this row applies, and the row mounts cleanly. The first call is the earliest point at which the composition's real shape is knowable.
+
+A refused write is restated rather than passed through: the denial marker, the path, the mode, and the workspace root the artifact has to move under, with the backend's refusal kept as the `cause` and the `FS_SANDBOX_DENIED` code re-stamped, so a caller that keys a retry off the code still sees it.
+
+### Source map
+
+| Path | Role |
+|---|---|
+| `src/index.ts` | plugin entry: identity, routing section, tool registration, pending-call presentation |
+| `src/config.ts` | the deployment's bounds and the recognition heuristics, and their schema |
+| `src/plan.ts` | request planning: interpreter, worker, and artifact resolution; the worker spec |
+| `src/recognize.ts` | one call: startup check, the batch, the correction pass, the artifact writes |
+| `src/events.ts` | the worker's event stream and the per-call state it accumulates |
+| `src/documents.ts` | the artifact files of one recognition, and the report it produces |
+| `src/artifacts.ts` | artifact paths and the recognition digest |
+| `src/records.ts` | the stored record and outline formats, their readers, and the JSON write |
+| `src/sandbox.ts` | the per-call fence, the guard for a composition that cannot resolve one, and the one policy-stamped write path |
+| `src/levels.ts` | the `levels` argument |
+| `src/filename.ts` | output naming |
+| `src/worker.ts` | process transport: spec handoff, line framing, timeout, cancellation |
+| `src/render.ts` | model-facing result text |
+| `scripts/setup.mjs` | the environment installer |
+| `python/ocr_worker.py` | worker entry: engine lifetime, page loop, merge and assemble modes |
+| `python/source.py` | PDF and image page sources |
+| `python/layout.py` | boxes to lines, column detection, outline levels |
+| `python/clean.py` | folios, running heads, line joining |
+| `python/assemble.py` | the merge pass, the candidate list, and the level overrides |
+
+### The per-page pass
+
+For each page the worker renders the page, recognizes it, and turns the engine's boxes into reading-order lines. It reports the page's text and its geometry on a page event; this module writes the text to `page-NNNNN.txt` and accumulates the geometry. The page's pixels are dropped before the next render. A page split by a vertical gutter is read column by column; every other page is read top to bottom, with boxes that share a row joined left to right.
+
+The page files carry five digits, so their order on disk is their order in the document past the 9999th page.
+
+### Page order and identity
+
+The page selection is resolved to the explicit list of page numbers it names — `"1-5,8"` is 1, 2, 3, 4, 5, 8, and nothing else — and the worker emits pages in that ascending order with the source's own page number as the index. The merge looks each page's lines up by that number rather than by position, so a selection that does not start at page 1 merges like any other.
+
+This module validates what the worker reports: a page number must be a positive integer, strictly greater than the one before it, and within the document's own page count. A violation aborts the call with a message naming the page, rather than producing a document with pages out of order or missing.
+
+### The merge pass
+
+When the last page is done the worker merges its records in one pass.
+
+- **Outline.** Heading levels come from the trailing outline number (`1.1`, `第 3 章`, `三、`), from a named section (`摘要`, `References`), or from glyph height measured against the document's own body size.
+- **Furniture.** Folios and repeated edge lines are removed.
+- **Whitespace.** Blank runs collapse, spaces that exist only because of a line box are removed between CJK characters, and a Latin word split by a hyphen at a line break is rejoined.
+- **Page breaks.** A paragraph cut in half by a page break is rejoined when the page's first kept line continues it.
+
+### The outline pass
+
+The merge also collects the lines a reader might call headings, and writes them to the outline file as candidates:
+
+| Field | Meaning |
+|---|---|
+| `id` | `h1`, `h2`, … in document order |
+| `page` | The page the line came from |
+| `text` | The line as the document renders it |
+| `level` | The level the document used: the correction when one was applied, else the inferred level, or `null` for body text |
+| `inferred` | The level the merge inferred, before any correction |
+| `ratio` | The line's glyph height over the document's body height |
+| `numbered` | The section number the line opens with, or `null` |
+
+A line becomes a candidate when the merge would call it a heading, when it opens with a section number, when it is taller than `outlineCandidateRatio` of the body height, or when it names a known section. Those last two are what put *body* lines in the list as well: a line the merge left alone is exactly the kind of line a reader can see is not a heading, and the model needs to be able to say so.
+
+The model answers with `levels`, a compact list of `h<id>=<level>`. `1` to `6` makes that line a heading at that depth; `0` leaves it as body text, which is how a line the recognition promoted is demoted again. A second `ocr` call carrying `levels` reads the stored geometry, re-runs the same merge with those levels applied, and rewrites the Markdown. It does not render or recognize anything, so it costs the merge rather than the document — three pages answered in about a second where the recognition took thirty.
+
+The corrections become part of the record, and the outline keeps both the applied level and the inferred one. Recognizing the same source again therefore reproduces the corrected document at the path it already owns rather than writing an uncorrected one beside it, and a caller re-reading the outline can see that its correction took.
+
+### Export shape
+
+The entry module named-exports `name`, `inject`, `Config`, and `apply` and carries no default export. `Config` applies the documented defaults and requires every bound the deployment owns. The entry re-exports the pure core its suites drive — the request planning, the artifact digest and naming, the correction parser, the finished-document reader, the result renderer, and the line framing — and the orchestration and artifact-writing modules behind `recognize`, so the model-facing surface and the testable core are both reachable from the one `.` export.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### System-prompt section
+
+#### What the model sees
+
+`tool:ocr` at order 2975, after the built-in tool band. It says when to reach for the tool, that the call saves a document and an outline file, that the heading levels can be corrected by calling again with `levels`, and that the document is what to pass to `present`. The text is empty wherever `ocr` is not visible in that scope.
+
+#### Token effect
+
+Three sentences, constant — 438 characters measured.
+
+#### KV Cache effect
+
+None; the section is a function of tool visibility, not of the conversation.
+
+### Tool schema
+
+#### What the model sees
+
+Five parameters: `path`, `paths`, `pages`, `outputDir`, and `levels`. `path` and `paths` are alternatives.
+
+#### Token effect
+
+Roughly constant — 1275 characters of JSON Schema measured on a booted row, of which the parameters are 953 and the description 277. The plugin's whole fixed per-request cost is 1713 characters against 1561 before the outline pass existed: the correction step and the `present` hand-off cost about ten percent more per request.
+
+#### KV Cache effect
+
+None. The schema does not vary with the conversation.
+
+### Tool-call history and result
+
+#### What the model sees
+
+The call as made, then one block per document (source path, saved path, page counts, line and heading counts, character count, what was removed, and the outline file), followed by one block per failure. A correction reports what it corrected instead.
+
+#### Token effect
+
+Proportional to the number of documents and failures, not to document size: the file path is reported instead of its contents, and the outline is a file rather than a list in the result. A three-page document costs 341 characters of result. The recognized text enters the conversation only if the model subsequently reads the Markdown it was told about.
+
+#### KV Cache effect
+
+None on its own. The result enters the transcript on the following turn like any other tool result.
+
+-----
+
+<a id="evidence"></a>
+## Evidence
+
+| File | Proves |
+|---|---|
+| `tests/index.test.mjs` | Request planning, page validation, the artifact layout, the correction pass, every rejection, the deployment bounds that have no default, and the heuristics that keep one |
+| `tests/transport.test.mjs` | A real child process: page events written to the right files, an out-of-order page aborting the call, a silent worker, the time ceiling, and one failed document leaving the rest of the batch intact |
+| `tests/filename.test.mjs` | The stem rules, the digest name, and the five-digit page file |
+| `tests/render.test.mjs` | The model-facing result of a recognition, a correction, a failure, and a truncated outline |
+| `tests/presentation.test.mjs` | The presentation metadata, and that no result text carries deployment vocabulary |
+| `tests/load-path.test.mjs` | The module form through the real Loader: no default export, `inject` kept |
+| `tests/loader-composition.test.mjs` | A real `cordis.yml` boots, the row's bounds are live, an omitted bound fails the load, the section reaches the assembled prompt, and a call dispatched through the registered tool drives the worker and writes every artifact through the mounted capability |
+| `tests/hmr-safety.test.mjs` | The registrations leave with their contributing fiber |
+| `tests/sandbox-write.test.mjs` | The artifact writes under a real `workspace-write` backend: the fence is required, lands the document inside the session workspace, refuses a path outside it, restates the refusal, and leaves a non-denial alone |
+| `tests/conventions.test.mjs` | The source rules the skill scaffolds a package with |
+| `tests/deployment.mjs` | The bounds a suite configures the tool with, so no suite inherits one from the package |
+| `python/tests/` | The pure layout, cleaning, merge, page-numbering, candidate, and override rules — 89 cases, no third-party import |
+
+## `./invariant`
+
+The package publishes none. An invariant companion is warranted only when independent observations of one owned relation can diverge; here the merge is a pure function of the page records one process produced, and the artifact layout is derived from a digest of its own inputs. The worker's and the plugin's suites cover those relations instead.
+
+## Known Limitations and Deferred Work
+
+- **The row must state every bound the deployment owns.** There is no fallback: a profile that mounts this tool without `dpi`, the pixel, page, file, outline, and time ceilings, the engine lifetime, and the per-page policy fails to load. That is deliberate — a hidden default would decide how much memory and time this machine spends without anyone having agreed to it — but it does mean a copied patch row from an earlier release needs those values added.
+- **A read-only session saves nothing.** Every write goes through the sandboxed filesystem capability and is stamped with the calling session's per-call policy, so the call fails with the standard denial marker when the session forbids writing, and a write whose path falls outside the session workspace is refused by name.
+- **A composition that mounts a confining filesystem without `ctx.sandboxPolicy` is refused at the first call.** The tool borrows both capabilities rather than declaring them, so the row itself still mounts; the misconfiguration surfaces as one readable error on the first call instead of as artifacts refused one page at a time.
+- **The outline pass is one model turn.** A document whose structure the model gets wrong needs a second `levels` call. A correction replaces the levels it names and leaves the rest as the recognition inferred them, and the worker reports the inferred level alongside the applied one, so a correction can be revised rather than only repeated.
+- **The candidate list is capped.** Past `maxOutlineCandidates` the remaining candidates are dropped and the result says the outline is incomplete.
+- **Nothing here reads a PDF's embedded text layer.** Every page is rendered and recognized, which is what makes a scan work and what costs time on a text PDF.
+- **Recognition quality is the engine's.** Small type, dense tables, handwriting, and mathematical notation are recognized poorly or not at all.
+- **Tables are not reconstructed.** Cells on one row become one line, so a table is emitted as prose.
+- **Column detection finds one gutter.** A page with three columns, or with full-width headings between columns, is read as two.
+- **A running head needs repetition to be recognized.** A document shorter than `runningHeadMinPages`, or a page selection covering fewer pages, keeps its running head as body text.
+- **The tool needs a local filesystem.** Its renderer opens the source by path, so a remote filesystem backend cannot serve it.
+- **The engine's first use loads its models**, so expect a few seconds before the first page is recognized; `--prefetch` moves that cost to installation.
+- **The environment is large** — about 260 MB, of which 30 MB is the model weights — and lives inside the package directory at `python/.venv`.
+
+-----
+
+<a id="dev-note"></a>
+## Dev Note
+
+Built with the plugin-development skill's scaffolder, `node <checkout>/.dsh/skills/dsh-plugin-development/scripts/src/index.mjs ocr --tool --plugins-root .`, which wrote the package skeleton, the profile patch row, and the profile link dependency in one run.
+
+```sh
+pnpm build        # tsc -p tsconfig.json && tsdown
+pnpm test         # node --test over the built output
+pnpm run setup    # create python/.venv and verify it
+pnpm test:python  # the pure layout, cleaning, and merge rules
+```
+
+`pnpm test` runs against `lib/`, so build first. The Python suite has no third-party dependency and runs under any Python 3; it does not need the environment `pnpm run setup` creates.
+
+The two halves are specified by one wire protocol, documented in [python/README.md](python/README.md). The host validates what the worker reports rather than trusting it, and every field the host reads is emitted by a test fixture as well as by the real worker.

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# Bundle patch for dsh-ab-ocr: contributes the ocr plugin row.
+# Installed via `dsh plugin --profile <name> add <dir>`; the row references this
+# package by name so Node resolution finds the built code. The browser half is
+# discovered by the Web plugin table through the manifest dsh.client declaration.
+- insert:
+    - id: ocr
+      name: 'dsh-ab-ocr'

package/lib/artifacts.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Where one source document's artifacts live, and the content digest that names
+ * the recognition they belong to.
+ *
+ * A source named `<stem>` under a base directory `<base>` keeps its Markdown at
+ * `<base>/<stem>.md`, its records under `<base>/<pageDirName>/<stem>/`, and one
+ * revision of those records under that page root's `<digest>` directory. The
+ * digest covers everything a recognition is: the source path and content, the page
+ * selection, and the merge options. The same digest therefore names the same record
+ * on a repeat call, so the record directory is found without scanning the page root
+ * — and a source whose content changed is a different recognition even when its
+ * length did not change with it.
+ * @module @deepseek-ai/dsh-ab-ocr/artifacts
+ */
+import type { MergeOptions } from './types.ts';
+/** File name of the pointer to a document's newest recognition. */
+export declare const LATEST_NAME = "latest.json";
+/** File name of a recognition's record. */
+export declare const RECORD_NAME = "record.json";
+/** File name of a recognition's heading outline. */
+export declare const OUTLINE_NAME = "outline.json";
+/**
+ * What the digest covers about the source file, as far as the filesystem
+ * capability reported it. A backend that reports no metadata leaves `size` at
+ * the empty string and `mtimeMs` at 0, which the record marks as unavailable.
+ */
+export interface SourceStamp {
+    /** Byte size, or the empty string when the filesystem reported none. */
+    size: number | '';
+    /** Modification time in milliseconds, or 0 when the filesystem reported none. */
+    mtimeMs: number;
+    /** Whether the filesystem reported nothing at all for the source. */
+    unavailable: boolean;
+}
+/** The paths of one source document that do not depend on a recognition. */
+export interface ArtifactRoot {
+    /** Directory the Markdown document and the page directory sit under. */
+    base: string;
+    /** The source's base name with its spaces removed. */
+    stem: string;
+    /** The preferred Markdown path, `<base>/<stem>.md`. */
+    document: string;
+    /** The document's page directory, `<base>/<pageDirName>/<stem>`. */
+    pageRoot: string;
+    /** The pointer to the newest recognition, `latest.json` under the page root. */
+    latest: string;
+}
+/** Every path one recognition's artifacts are written to. */
+export interface ArtifactPaths extends ArtifactRoot {
+    /** Content digest of the recognition, 12 hex characters. */
+    digest: string;
+    /** The Markdown path of this digest, `<base>/<stem>.<digest>.md`. */
+    digestedDocument: string;
+    /** The revision's directory: its page files, record, and outline. */
+    recordDir: string;
+    /** The recognition's record. */
+    record: string;
+    /** The recognition's heading outline. */
+    outline: string;
+}
+/**
+ * Resolve the base directory one source document's artifacts sit under.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param outputDir - the call's output directory, or an empty string for the source's own.
+ * @returns the base directory.
+ */
+export declare function artifactBase(sourcePath: string, outputDir: string): string;
+/**
+ * Resolve the paths of one source document that do not depend on a recognition.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param base - the directory the document's artifacts sit under.
+ * @param pageDirName - the page directory's name under the base directory.
+ * @returns the document's stable artifact paths.
+ */
+export declare function artifactRoot(sourcePath: string, base: string, pageDirName: string): ArtifactRoot;
+/**
+ * Resolve every path one recognition's artifacts are written to.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param base - the directory the document's artifacts sit under.
+ * @param pageDirName - the page directory's name under the base directory.
+ * @param digest - the recognition's content digest.
+ * @returns the document's artifact paths, including this recognition's revision.
+ */
+export declare function artifactPaths(sourcePath: string, base: string, pageDirName: string, digest: string): ArtifactPaths;
+/**
+ * Identify one recognition from the values that decided its text.
+ *
+ * The digest follows the source's content, not merely its length: a source edited
+ * without changing size is a different recognition, and an unchanged one is the
+ * same recognition however often it is read.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param stamp - the source metadata the digest covers alongside its content.
+ * @param sourceDigest - digest of the source bytes, or an empty string when the
+ *   worker did not report one.
+ * @param pageSelection - the call's page selection, or null for the whole document.
+ * @param merge - the merge options the call sends.
+ * @returns the first 12 hex characters of the digest.
+ */
+export declare function digest12(sourcePath: string, stamp: SourceStamp, sourceDigest: string, pageSelection: string | null, merge: MergeOptions): string;
+//# sourceMappingURL=artifacts.d.ts.map

package/lib/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,mEAAmE;AACnE,eAAO,MAAM,WAAW,gBAAgB,CAAA;AAExC,2CAA2C;AAC3C,eAAO,MAAM,WAAW,gBAAgB,CAAA;AAExC,oDAAoD;AACpD,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAK1C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,EAAE,CAAA;IACjB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAA;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAA;IACjB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAUhG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,aAAa,CAWf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,KAAK,EAAE,YAAY,GAClB,MAAM,CASR"}

package/lib/artifacts.js

@@ -0,0 +1,97 @@
+/**
+ * Where one source document's artifacts live, and the content digest that names
+ * the recognition they belong to.
+ *
+ * A source named `<stem>` under a base directory `<base>` keeps its Markdown at
+ * `<base>/<stem>.md`, its records under `<base>/<pageDirName>/<stem>/`, and one
+ * revision of those records under that page root's `<digest>` directory. The
+ * digest covers everything a recognition is: the source path and content, the page
+ * selection, and the merge options. The same digest therefore names the same record
+ * on a repeat call, so the record directory is found without scanning the page root
+ * — and a source whose content changed is a different recognition even when its
+ * length did not change with it.
+ * @module @deepseek-ai/dsh-ab-ocr/artifacts
+ */
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { markdownDigestFileName, markdownFileName, markdownStem } from "./filename.js";
+/** File name of the pointer to a document's newest recognition. */
+export const LATEST_NAME = 'latest.json';
+/** File name of a recognition's record. */
+export const RECORD_NAME = 'record.json';
+/** File name of a recognition's heading outline. */
+export const OUTLINE_NAME = 'outline.json';
+/** Characters of the digest that name a record directory. */
+const DIGEST_LENGTH = 12;
+/**
+ * Resolve the base directory one source document's artifacts sit under.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param outputDir - the call's output directory, or an empty string for the source's own.
+ * @returns the base directory.
+ */
+export function artifactBase(sourcePath, outputDir) {
+    return outputDir === '' ? dirname(sourcePath) : outputDir;
+}
+/**
+ * Resolve the paths of one source document that do not depend on a recognition.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param base - the directory the document's artifacts sit under.
+ * @param pageDirName - the page directory's name under the base directory.
+ * @returns the document's stable artifact paths.
+ */
+export function artifactRoot(sourcePath, base, pageDirName) {
+    const stem = markdownStem(sourcePath);
+    const pageRoot = join(base, pageDirName, stem);
+    return {
+        base,
+        stem,
+        document: join(base, markdownFileName(sourcePath)),
+        pageRoot,
+        latest: join(pageRoot, LATEST_NAME),
+    };
+}
+/**
+ * Resolve every path one recognition's artifacts are written to.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param base - the directory the document's artifacts sit under.
+ * @param pageDirName - the page directory's name under the base directory.
+ * @param digest - the recognition's content digest.
+ * @returns the document's artifact paths, including this recognition's revision.
+ */
+export function artifactPaths(sourcePath, base, pageDirName, digest) {
+    const root = artifactRoot(sourcePath, base, pageDirName);
+    const recordDir = join(root.pageRoot, digest);
+    return {
+        ...root,
+        digest,
+        digestedDocument: join(base, markdownDigestFileName(sourcePath, digest)),
+        recordDir,
+        record: join(recordDir, RECORD_NAME),
+        outline: join(recordDir, OUTLINE_NAME),
+    };
+}
+/**
+ * Identify one recognition from the values that decided its text.
+ *
+ * The digest follows the source's content, not merely its length: a source edited
+ * without changing size is a different recognition, and an unchanged one is the
+ * same recognition however often it is read.
+ * @param sourcePath - the absolute path the model asked to recognize.
+ * @param stamp - the source metadata the digest covers alongside its content.
+ * @param sourceDigest - digest of the source bytes, or an empty string when the
+ *   worker did not report one.
+ * @param pageSelection - the call's page selection, or null for the whole document.
+ * @param merge - the merge options the call sends.
+ * @returns the first 12 hex characters of the digest.
+ */
+export function digest12(sourcePath, stamp, sourceDigest, pageSelection, merge) {
+    const material = JSON.stringify([
+        sourcePath,
+        sourceDigest === '' ? stamp.size : sourceDigest,
+        stamp.mtimeMs,
+        pageSelection,
+        merge,
+    ]);
+    return createHash('sha256').update(material, 'utf8').digest('hex').slice(0, DIGEST_LENGTH);
+}
+//# sourceMappingURL=artifacts.js.map

package/lib/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAGtF,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAA;AAExC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAA;AAExC,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAA;AAE1C,6DAA6D;AAC7D,MAAM,aAAa,GAAG,EAAE,CAAA;AA4CxB;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,SAAiB;IAChE,OAAO,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,IAAY,EAAE,WAAmB;IAChF,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAA;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,CAAA;IAC9C,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAClD,QAAQ;QACR,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC;KACpC,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,MAAc;IAEd,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,CAAA;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC7C,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,sBAAsB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACxE,SAAS;QACT,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC;QACpC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC;KACvC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAkB,EAClB,KAAkB,EAClB,YAAoB,EACpB,aAA4B,EAC5B,KAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,UAAU;QACV,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;QAC/C,KAAK,CAAC,OAAO;QACb,aAAa;QACb,KAAK;KACN,CAAC,CAAA;IACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAA;AAC5F,CAAC"}