@v587d/capital-generation 2.8.2 → 2.9.0

package/lib/ocr/markdown.js

@@ -1,16 +1,11 @@
 /**
- * PaddleOCR 输出 → 模型可读 markdown 的归一化（`ocr` 的呈现层，唯一一份实现）。
- *
- * 为什么必须归一化（2026-09-25 拿真报文实测，贵州茅台 15 页研报）：上游把**表格输出成内联
- * HTML**，每个单元格都带 `style='text-align: center; word-wrap: break-word;'`——
- * 105,639 个字符里 63,232 个（60%）是 `style='...'` 样板，去掉再转成 GFM 管道表只剩 27,156。
- * 本仓的场景恰恰是"大量表格、图形"，不处理就等于**预算的六成买的是 HTML 属性**，
- * 而 `prettifyMarkdown` 这类 flag 在上游被静默忽略（未知键也返回 Success），帮不上。
- *
- * 归一化只做**无损排版**：不删正文、不改数字、不做摘要。数字一律照抄上游。
+ * PaddleOCR output -> model-readable markdown (the only implementation). Upstream emits
+ * tables as inline HTML with per-cell `style=`, so on a measured 15-page report ~60% of
+ * characters were style boilerplate; `prettifyMarkdown`-style flags are silently ignored.
+ * Normalization is lossless layout only: no text, numbers or tables are dropped.
  */
 const PAGE_MARKER_PREFIX = '<!-- page:';
-/** HTML 实体：财报文档里 `&amp;` 出现在公司名与科目名里，不解开就是脏数据。 */
+/** `&amp;` appears in company and account names; leaving it encoded is dirty data. */
 const NAMED_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
 function decodeEntities(value) {
     return value.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/giu, (whole, body) => {
@@ -32,27 +27,22 @@ function stripTags(value) {
         .trim();
 }
 function escapeCell(value) {
-    // GFM 单元格里的竖线必须转义，否则一行被切成更多列——表格串列比报错危险（声明与正文不一致）。
+    // GFM cells need escaped pipes; a split row misaligns columns silently.
     return value.replace(/\|/gu, '\\|');
 }
-/** 取一行 `<tr>` 里的单元格文本。 */
+/** Cell text from one `<tr>`; split on open tags, then cut at the matching close tag. */
 function rowCells(row) {
     const cells = [];
-    // 先按**开**标签切：畸形行（少写 `</td>`，实测存在）也能一格一切；再按闭标签截断本段，
-    // 防止 `1</td><td>2` 这类残留把下一格的内容并进来。第一格之前的 `<thead>` 碎片一律丢弃。
-    // ⚠️ 单元格标签是 `<td>` **或** `<th>`（上游表头行用 `<th>`，实测）：写成 `<t(?:d|th)`
-    //    只匹配得到 `<td`，`<th>` 行切不出格、整行被 `kept` 丢掉——表头静默消失。
-    //    `\b` 在这里是必要的：它让 `<thead>` / `<table>` 不被误当成单元格开标签。
+    // Upstream header rows use `<th>`; matching only `<td` silently drops whole header rows.
+    // `\b` keeps `<thead>` / `<table>` from being read as cell openers.
     for (const segment of row.split(/<t(?:d|h)\b[^>]*>/giu).slice(1)) {
         cells.push(stripTags(segment.split(/<\/t(?:d|h)\s*>/iu)[0] ?? ''));
     }
     return cells;
 }
 /**
- * 一张 HTML 表 → GFM 管道表。
- *
- * 表头按上游第一行处理（上游会把 `<thead><th>` 放第一行）；列数以各行最大值为准并补齐，
- * 因为 GFM 要求分隔行列数与表头一致，少一格整张表退化成裸文本。
+ * HTML table -> GFM pipe table. Header is upstream's first row; pad every row to the
+ * widest so GFM's separator count matches the header (a short row degrades the table).
  */
 function tableToMarkdown(tableHtml) {
     const rows = [...tableHtml.matchAll(/<tr\b[^>]*>([\s\S]*?)(?:<\/tr>|$)/giu)].map((match) => rowCells(match[1]));
@@ -64,7 +54,7 @@ function tableToMarkdown(tableHtml) {
     lines.splice(1, 0, `|${' --- |'.repeat(width)}`);
     return lines.join('\n');
 }
-/** 剥样式 + HTML 表转 GFM + 收空行。对不含 HTML 的正文近似恒等。 */
+/** Strip styles, convert HTML tables to GFM, collapse blank lines; near-identity otherwise. */
 export function normalizeOcrMarkdown(source) {
     const styleMatches = source.match(/\s(?:style|class)\s*=\s*(?:"[^"]*"|'[^']*')/giu) ?? [];
     const styleCharsRemoved = styleMatches.reduce((total, match) => total + match.length, 0);
@@ -77,8 +67,8 @@ export function normalizeOcrMarkdown(source) {
         .replace(/<br\s*\/?\s*>/giu, ' ')
         .replace(/<\/?(?:td|th|tr|thead|tbody|tfoot|table|div|span|p|font|img|a|sup|sub|b|i|u|s|em|strong)\b[^>]*>/giu, '')
         .replace(/\s(?:style|class)\s*=\s*(?:"[^"]*"|'[^']*')/giu, '')
-        // 上游会把标题粘在正文尾巴上（实测 `2024-11-12## 盈利预测`），标题不在行首就没法进索引；
-        // 要求 `#` 后必须有空格，避免把 "评级#买入" 这类没有空格的井号误拆。
+        // Upstream glues headings to preceding text (`2024-11-12## 盈利预测`); require a
+        // space after `#` so "评级#买入" is not split.
         .replace(/(?<=\S)(#{1,6}\s+\S)/gu, '\n\n$1')
         .replace(/[ \t]+\n/gu, '\n')
         .replace(/\n{3,}/gu, '\n\n');
@@ -92,7 +82,7 @@ function firstHeading(markdown) {
     }
     return undefined;
 }
-/** 把逐页 markdown 拼成一份文档，并算出**页偏移索引**（按页取回与关键词定位都靠它）。 */
+/** Join per-page markdown and record page offsets, used by page reads and keyword lookup. */
 export function buildOcrDocument(sourcePages) {
     const chunks = [];
     const pages = [];
@@ -127,8 +117,8 @@ function pageOf(pages, at) {
     return pages.find((entry) => at >= entry.start && at < entry.end) ?? pages[pages.length - 1];
 }
 /**
- * 页区间解析：`"1-3"` / `"5"` / `"2-4,9"`（1 起始，闭区间）。
- * 越界页码**响亮失败**而不是静默少给——"这页没有"和"我没给"在回执里必须能区分。
+ * `"1-3"` / `"5"` / `"2-4,9"` (1-based, inclusive). Out-of-range pages fail loudly:
+ * "page absent" and "not requested" must stay distinguishable in the receipt.
  */
 export function parsePageRange(spec, totalPages) {
     const taken = [];
@@ -159,7 +149,7 @@ export function parsePageRange(spec, totalPages) {
         throw new Error(`pages is empty after normalization: '${spec}'`);
     return taken;
 }
-/** 按页切出正文（纯字符串切片，不重跑上游）。 */
+/** Slice pages out of the stored text; never re-runs upstream. */
 export function selectPages(document, pages) {
     return pages.map((page) => {
         const entry = document.pages.find((item) => item.page === page);
@@ -172,11 +162,10 @@ export function selectPages(document, pages) {
     });
 }
 /**
- * 关键词定位：在**已落盘的文档**里找命中，回带页号的上下文片段。
- *
- * 为什么不靠 `pages` 硬读：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算 6,144——
- * 想拿财务预测表就得能"跳着看"。上游页区间不影响算力（整篇都算过），所以定位必须在这份
- * 归一化文本上做，不再出网。
+ * Keyword lookup over the persisted normalized text (no egress): the output budget is
+ * smaller than a whole report, so callers must be able to jump. Adjacent hits merge into
+ * one window, and windows never cross a page boundary — a miscited page is worse than
+ * fewer hits — which also keeps `<!-- page:N -->` markers out of excerpts.
  */
 export function locateQuery(document, query, limit, windowChars) {
     const haystack = document.document;
@@ -193,12 +182,10 @@ export function locateQuery(document, query, limit, windowChars) {
         if (at < 0)
             break;
         cursor = at + needle.length;
-        // 相邻命中合并成一段窗口：否则同一句话的三次命中会占满 limit，看着像三条证据其实是一条。
+        // Merge adjacent hits: three occurrences of one sentence must not fill `limit`.
         if (at < lastEnd)
             continue;
         const entry = pageOf(document.pages, at);
-        // 窗口**不越页**：片段被标成"第 N 页"就是要能被引用回第 N 页，跨了页就是错引（错引比少引危险）。
-        // 顺带把 `<!-- page:N -->` 存储标记挡在外面——那是落盘布局，不是给模型回传正文的东西。
         const from = Math.max(entry?.start ?? 0, at - windowChars);
         const to = Math.min(entry?.end ?? haystack.length, at + needle.length + windowChars);
         hits.push({ page: entry?.page ?? 1, at, excerpt: haystack.slice(from, to).replace(/\n+/gu, ' ⏎ ') });

package/lib/ocr/store.d.ts

@@ -1,43 +1,24 @@
 /**
- * `ocr` 的**产物层**：解析结果一律落 `capital-data/ocr/<doc_id>/`，模型侧只拿 `doc_id` 与索引。
- *
- * 为什么必须落盘而不是留在内存：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算
- * 只有 6,144（`SOURCE_OUTPUT_BUDGET_CHARS`）。落盘之后"按页取回 / 关键词定位"才是**纯本地
- * 零花费**的第二、第三次读取；否则每次翻页都要重跑上游、再花一次 job。
- *
- * ```text
- * capital-data/ocr/<doc_id>/
- * ├── meta.json      # 页偏移索引与花费口径（model / charts / job_id / created_at）
- * └── document.md    # 全篇归一化 markdown，页分隔 `<!-- page:N -->`
- * ```
- *
- * `doc_id` 是**内容寻址**的：`sha1(归一化输入 + model + flags)` 前 12 位。因此"同一份文档
- * 重复解析"自动命中缓存不再出网；`refresh` 才强制重跑（上游对同一份 PDF 两次给出过
- * 18% 与 19% 的不同数字，重跑**不是**独立验证，引用必须带 `doc_id` 与 `created_at`）。
- *
- * 写入顺序是 `document.md` → `meta.json`：**meta 的在场即代表产物完整**。中途被中断
- * （超时、取消）留下半件产物时，下一次读取按"未缓存"处理并重写（`overwrite`），
- * 不会把模型永久锁死在一个坏 `doc_id` 上。
+ * OCR artifacts live under `capital-data/ocr/<doc_id>/`; the model only gets `doc_id`.
+ * Content-addressed ids make a repeat parse a cache hit. `document.md` is written before
+ * `meta.json`, so meta's presence means a complete artifact; half-written ones are redone.
+ * Page reads reuse the persisted text instead of re-running a paid upstream job.
  */
 import type { SessionLike, WorkspaceDatasetStore } from '../data-collector/store.js';
 import type { OcrDocument, OcrPageEntry } from './markdown.js';
 export declare const OCR_ARTIFACT_SUBDIR = "capital-data/ocr";
 export declare const OCR_DOC_ID_PATTERN: RegExp;
-/** 本地文档字节的读取上限：上游 100 页口径下的研报/公告量级，超限宁可报错也不要缓冲整份。 */
+/** Read cap for local documents: 100-page reports fit; fail rather than buffer a whole file. */
 export declare const OCR_MAX_SOURCE_BYTES: number;
-/** 产物元数据（落盘形态）。字段名与回执一致，模型看到的和盘上的不是两份真相。 */
+/** On-disk metadata; field names match the receipt so disk and model see one truth. */
 export interface OcrArtifactMeta {
     doc_id: string;
-    /**
-     * 输入指认：`url:<http(s) URL>` 或 `file:<workspace 相对路径>`。**绝不落绝对路径**。
-     * 续查（只传 `job_id` + `doc_id`）时本机没有重算种子的输入，此时**留空而不是编一个**——
-     * 把作业号写成来源会被当成"这条 URL 就是文档出处"。
-     */
+    /** Input identity, `url:` or `file:` (never absolute); empty on resume — never pass job_id off as provenance. */
     source?: string;
     source_kind: 'url' | 'file' | 'job';
     job_id: string;
     model: string;
-    /** 提交时的图表识别开关；续查时无从得知，留空。 */
+    /** Chart-recognition flag at submit; unknown on resume, so omitted. */
     charts?: boolean;
     pages: number;
     chars: number;
@@ -51,17 +32,9 @@ export interface OcrArtifact {
     meta: OcrArtifactMeta;
     document: OcrDocument;
 }
-/** `seed` 由各形态自己拼（URL 文本 / 文件字节），统一在此收敛成 `ocr_<12 hex>`。 */
 export declare function deriveOcrDocId(seed: string | Uint8Array, model: string, charts: boolean): string;
-/** 回执里给模型的 opaque 引用（与 Dataset/profile 引用同一套 `workspace://` 口径）。 */
 export declare function ocrArtifactRef(docId: string): string;
-/**
- * 落盘产物**自己**坏了（调用方没做错任何事）。
- *
- * 为什么要单独一个类型：翻成回执的那一层要把"下一步该传什么"写清楚，而那一步需要的指认
- * （当初解析用过的 url / file）只有这份 meta 里有。让调用方重新去猜链接，等于把一次
- * 可机械执行的修复推回给人或模型。
- */
+/** Corrupt artifact, not caller error; the repair hint needs the source only this meta holds. */
 export declare class OcrArtifactError extends Error {
     readonly reason: 'meta_unreadable' | 'meta_invalid' | 'document_missing';
     readonly docId: string;
@@ -70,17 +43,15 @@ export declare class OcrArtifactError extends Error {
     constructor(reason: 'meta_unreadable' | 'meta_invalid' | 'document_missing', docId: string, sourceKind: OcrArtifactMeta['source_kind'] | undefined, source: string | undefined, message: string);
 }
 /**
- * 读回一份产物。三种"读不到"必须能区分：
- *  - `undefined`：从未解析过（meta 与 document 都不在）——调用方据此决定提交新 job。
- *  - 抛错：meta 在但正文丢失/损坏，或半件产物——**不能**当成"没有内容"，也不能静默重跑
- *    （重跑要花一次 job，用户看不到钱去哪了），交给调用方翻成带 `doc_id` 的失败回执。
+ * `undefined` = never parsed (safe to submit a job). A throw = meta present but body
+ * missing/corrupt: do not treat as empty and do not silently re-run (a re-run costs a job).
  */
 export declare function readOcrArtifact(store: WorkspaceDatasetStore, input: {
     session: SessionLike;
     doc_id: string;
     signal?: AbortSignal;
 }): Promise<OcrArtifact | undefined>;
-/** 落盘。`overwrite` 只在调用方**已经决定**重新生成时传（见文件头的写入顺序）。 */
+/** `overwrite` only when the caller has already decided to regenerate. */
 export declare function writeOcrArtifact(store: WorkspaceDatasetStore, input: {
     session: SessionLike;
     meta: OcrArtifactMeta;
@@ -91,7 +62,6 @@ export declare function writeOcrArtifact(store: WorkspaceDatasetStore, input: {
     artifact_ref: string;
     paths: string[];
 }>;
-/** 拼一条与盘上记录同形状的 meta（`document` 只提供算好的排版统计）。 */
 export declare function buildArtifactMeta(input: {
     doc_id: string;
     source?: string;
@@ -103,11 +73,8 @@ export declare function buildArtifactMeta(input: {
     createdAt: string;
 }): OcrArtifactMeta;
 /**
- * 读取**待解析**的本地文档字节（`file` 形态的入口）。
- *
- * 只接受 session workspace 内的相对路径：绝对路径（含 Windows 盘符）与 `..` 段在
- * `normalizeWorkspaceRelativePath` 就被拒，之后仍要过沙箱归属校验。模型从 `@xxx.pdf`
- *  mention 里看到的是路径末段，因此回执话术要求它传 workspace 相对路径。
+ * `file` entry: workspace-relative only (absolute paths, drive letters and `..` are
+ * rejected downstream, then ownership is checked); @mentions show just the path tail.
  */
 export declare function readOcrSourceBytes(store: WorkspaceDatasetStore, input: {
     session: SessionLike;

package/lib/ocr/store.js

@@ -1,23 +1,8 @@
 /**
- * `ocr` 的**产物层**：解析结果一律落 `capital-data/ocr/<doc_id>/`，模型侧只拿 `doc_id` 与索引。
- *
- * 为什么必须落盘而不是留在内存：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算
- * 只有 6,144（`SOURCE_OUTPUT_BUDGET_CHARS`）。落盘之后"按页取回 / 关键词定位"才是**纯本地
- * 零花费**的第二、第三次读取；否则每次翻页都要重跑上游、再花一次 job。
- *
- * ```text
- * capital-data/ocr/<doc_id>/
- * ├── meta.json      # 页偏移索引与花费口径（model / charts / job_id / created_at）
- * └── document.md    # 全篇归一化 markdown，页分隔 `<!-- page:N -->`
- * ```
- *
- * `doc_id` 是**内容寻址**的：`sha1(归一化输入 + model + flags)` 前 12 位。因此"同一份文档
- * 重复解析"自动命中缓存不再出网；`refresh` 才强制重跑（上游对同一份 PDF 两次给出过
- * 18% 与 19% 的不同数字，重跑**不是**独立验证，引用必须带 `doc_id` 与 `created_at`）。
- *
- * 写入顺序是 `document.md` → `meta.json`：**meta 的在场即代表产物完整**。中途被中断
- * （超时、取消）留下半件产物时，下一次读取按"未缓存"处理并重写（`overwrite`），
- * 不会把模型永久锁死在一个坏 `doc_id` 上。
+ * OCR artifacts live under `capital-data/ocr/<doc_id>/`; the model only gets `doc_id`.
+ * Content-addressed ids make a repeat parse a cache hit. `document.md` is written before
+ * `meta.json`, so meta's presence means a complete artifact; half-written ones are redone.
+ * Page reads reuse the persisted text instead of re-running a paid upstream job.
  */
 import { DatasetStoreError } from '../data-collector/store.js';
 import { WORKSPACE_DATA_DIR } from '../data-collector/store.js';
@@ -25,12 +10,11 @@ export const OCR_ARTIFACT_SUBDIR = `${WORKSPACE_DATA_DIR}/ocr`;
 export const OCR_DOC_ID_PATTERN = /^ocr_[0-9a-f]{12}$/u;
 const META_FILE = 'meta.json';
 const DOCUMENT_FILE = 'document.md';
-/** 本地文档字节的读取上限：上游 100 页口径下的研报/公告量级，超限宁可报错也不要缓冲整份。 */
+/** Read cap for local documents: 100-page reports fit; fail rather than buffer a whole file. */
 export const OCR_MAX_SOURCE_BYTES = 32 * 1024 * 1024;
 /**
- * 与 `hub.ts` / `sources.ts` 同一个 `process.getBuiltinModule` 惯用法（本仓刻意不装
- * `@types/node`）。拿不到就**响亮失败**：`doc_id` 是缓存键，退回一个更弱的哈希会让两份不同
- * 文档撞在同一个 `doc_id` 上、把 A 的正文当 B 交出去。
+ * No `@types/node` (same `process.getBuiltinModule` idiom as hub/sources). Fail loudly:
+ * `doc_id` is a cache key, so a weaker fallback could collide two documents onto one id.
  */
 function createHash(algorithm) {
     const processLike = globalThis.process;
@@ -39,14 +23,12 @@ function createHash(algorithm) {
         throw new Error('node:crypto is unavailable; cannot derive a content-addressed doc_id');
     return hash;
 }
-/** `seed` 由各形态自己拼（URL 文本 / 文件字节），统一在此收敛成 `ocr_<12 hex>`。 */
 export function deriveOcrDocId(seed, model, charts) {
     const hash = createHash('sha1');
     hash.update(seed);
     hash.update(`\u0000${model}\u0000${charts ? 'charts' : 'no-charts'}`);
     return `ocr_${hash.digest('hex').slice(0, 12)}`;
 }
-/** 回执里给模型的 opaque 引用（与 Dataset/profile 引用同一套 `workspace://` 口径）。 */
 export function ocrArtifactRef(docId) {
     return `workspace://${OCR_ARTIFACT_SUBDIR}/${docId}`;
 }
@@ -67,13 +49,7 @@ function isNotFound(error) {
 function isTooLarge(error) {
     return error instanceof DatasetStoreError && error.code === 'dataset_too_large';
 }
-/**
- * 落盘产物**自己**坏了（调用方没做错任何事）。
- *
- * 为什么要单独一个类型：翻成回执的那一层要把"下一步该传什么"写清楚，而那一步需要的指认
- * （当初解析用过的 url / file）只有这份 meta 里有。让调用方重新去猜链接，等于把一次
- * 可机械执行的修复推回给人或模型。
- */
+/** Corrupt artifact, not caller error; the repair hint needs the source only this meta holds. */
 export class OcrArtifactError extends Error {
     reason;
     docId;
@@ -89,10 +65,8 @@ export class OcrArtifactError extends Error {
     }
 }
 /**
- * 读回一份产物。三种"读不到"必须能区分：
- *  - `undefined`：从未解析过（meta 与 document 都不在）——调用方据此决定提交新 job。
- *  - 抛错：meta 在但正文丢失/损坏，或半件产物——**不能**当成"没有内容"，也不能静默重跑
- *    （重跑要花一次 job，用户看不到钱去哪了），交给调用方翻成带 `doc_id` 的失败回执。
+ * `undefined` = never parsed (safe to submit a job). A throw = meta present but body
+ * missing/corrupt: do not treat as empty and do not silently re-run (a re-run costs a job).
  */
 export async function readOcrArtifact(store, input) {
     const docId = requireDocId(input.doc_id);
@@ -126,7 +100,7 @@ export async function readOcrArtifact(store, input) {
     }
     return { meta, document: { document: text, pages: meta.page_entries, chars: meta.chars, images: meta.images, tables: meta.tables, styleCharsRemoved: meta.style_chars_removed } };
 }
-/** 落盘。`overwrite` 只在调用方**已经决定**重新生成时传（见文件头的写入顺序）。 */
+/** `overwrite` only when the caller has already decided to regenerate. */
 export async function writeOcrArtifact(store, input) {
     const docId = requireDocId(input.meta.doc_id);
     const written = await store.writeWorkspaceFiles({
@@ -141,7 +115,7 @@ export async function writeOcrArtifact(store, input) {
     });
     return { artifact_ref: ocrArtifactRef(docId), paths: written.map((file) => file.path) };
 }
-/** meta 是**我们**写出去的记录，读回来时仍逐字段核一遍——手改过的盘也要能响亮失败。 */
+/** Re-validate our own record field by field so a hand-edited file fails loudly. */
 function normalizeMeta(value, docId) {
     const record = (typeof value === 'object' && value !== null ? value : {});
     const pages = Array.isArray(record.page_entries) ? record.page_entries : [];
@@ -183,13 +157,12 @@ function normalizeMeta(value, docId) {
         created_at: text('created_at'),
     };
 }
-/** 来源类别缺省或写歪时**响亮失败**：把不认识的 provenance 默认成 `url` 会伪造出处。 */
+/** Fail on an unknown provenance: defaulting it to `url` would fabricate attribution. */
 function sourceKind(value) {
     if (value === 'url' || value === 'file' || value === 'job')
         return value;
     throw new Error(`meta.source_kind 不认识：${String(value)}`);
 }
-/** 拼一条与盘上记录同形状的 meta（`document` 只提供算好的排版统计）。 */
 export function buildArtifactMeta(input) {
     return {
         doc_id: requireDocId(input.doc_id),
@@ -208,11 +181,8 @@ export function buildArtifactMeta(input) {
     };
 }
 /**
- * 读取**待解析**的本地文档字节（`file` 形态的入口）。
- *
- * 只接受 session workspace 内的相对路径：绝对路径（含 Windows 盘符）与 `..` 段在
- * `normalizeWorkspaceRelativePath` 就被拒，之后仍要过沙箱归属校验。模型从 `@xxx.pdf`
- *  mention 里看到的是路径末段，因此回执话术要求它传 workspace 相对路径。
+ * `file` entry: workspace-relative only (absolute paths, drive letters and `..` are
+ * rejected downstream, then ownership is checked); @mentions show just the path tail.
  */
 export async function readOcrSourceBytes(store, input) {
     const bytes = await store.readWorkspaceBytes({

package/lib/ocr-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/ocr` row: PaddleOCR job -> markdown -> disk. The `url` vs `file` / `doc_id`
+ * split is a call-level guard in `root-tool-policy` (name-level deny cannot express it).
+ * Client construction is per mount; credentials resolve per call.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-ocr-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/ocr-entry.js

@@ -0,0 +1,10 @@
+import { registerOcrTool } from './web-retriever/tools.js';
+import { createRetrieverRuntime } from './retriever-runtime.js';
+import { capitalDatasetStore } from './runtime.js';
+import { readRetrieverConfig } from './capital-settings.js';
+export const name = 'capital-ocr-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    const runtime = createRetrieverRuntime(ctx, readRetrieverConfig(ctx));
+    registerOcrTool(ctx, { store: capitalDatasetStore(ctx), client: runtime.ocrClient });
+}

package/lib/policy-entry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Host-plane Capital policy row: call-level gates that preset composition cannot express.
+ * Root convergence (visibility already closed by family rows), per-name sibling deny,
+ * call-level guards for the `ocr` url form and role `interrupt_agent`, plus shell and fs
+ * guards. Identity must be read per call: the host creates the Agent before selecting a
+ * preset. Also hides delegation-only roles from the remote roster. Listens on `ctx.root`;
+ * one registration per process.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-policy";
+/**
+ * `tools` is a hard dependency: without `inject`, boot resolves it to undefined without
+ * throwing and every identity guard silently skips installation. Waiting for the fiber
+ * to provide it closes that boot-time race.
+ */
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/policy-entry.js

@@ -0,0 +1,22 @@
+import { registerBashGuard } from './agents/bash-guard.js';
+import { registerPresetRosterFilter } from './agents/preset-roster.js';
+import { registerFsWriteGuard, registerRootOcrGuard, registerRootToolPolicy } from './agents/root-tool-policy.js';
+import { registerRoleSiblingGuard, registerRoleToolPolicy } from './agents/role-tool-policy.js';
+export const name = 'capital-policy';
+/**
+ * `tools` is a hard dependency: without `inject`, boot resolves it to undefined without
+ * throwing and every identity guard silently skips installation. Waiting for the fiber
+ * to provide it closes that boot-time race.
+ */
+export const inject = ['tools'];
+export function apply(ctx) {
+    const policy = ctx;
+    // Preset rows now own visibility; the host keeps only call-level gates.
+    registerRootToolPolicy(policy, { deny: false });
+    registerRootOcrGuard(policy);
+    registerRoleToolPolicy(policy);
+    registerRoleSiblingGuard(policy);
+    registerBashGuard(policy);
+    registerFsWriteGuard(policy);
+    registerPresetRosterFilter(ctx);
+}

package/lib/preset-claim.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Single reader for an Agent's preset claim. Callers differ only in the fail direction:
+ * root convergence assumes a claim, role surfaces skip convergence, tool authorization
+ * falls back to the old topology check (which is never broader). Any exception is folded
+ * into flags, never thrown, because callers sit on the Agent creation path.
+ */
+/** Registry surface unavailable, or `composedPreset` threw (see `failed`). */
+export interface PresetClaimResult {
+    /** Raw `composedPreset` value; undefined means unbound Agent or a throw. */
+    readonly claim: string | undefined;
+    readonly registryMissing: boolean;
+    /** `composedPreset` threw; distinct from "no preset bound". */
+    readonly failed: boolean;
+}
+interface ReadableContext {
+    get?(name: string): unknown;
+    readonly [key: string]: unknown;
+}
+export declare function readPresetClaim(ctx: ReadableContext | undefined, agent: {
+    ctx?: unknown;
+} | undefined): PresetClaimResult;
+export {};

package/lib/preset-claim.js

@@ -0,0 +1,24 @@
+/**
+ * Single reader for an Agent's preset claim. Callers differ only in the fail direction:
+ * root convergence assumes a claim, role surfaces skip convergence, tool authorization
+ * falls back to the old topology check (which is never broader). Any exception is folded
+ * into flags, never thrown, because callers sit on the Agent creation path.
+ */
+export function readPresetClaim(ctx, agent) {
+    let presets;
+    try {
+        presets = ctx?.get?.('agentPresets');
+    }
+    catch {
+        return { claim: undefined, registryMissing: true, failed: false };
+    }
+    if (presets === undefined || typeof presets.composedPreset !== 'function') {
+        return { claim: undefined, registryMissing: true, failed: false };
+    }
+    try {
+        return { claim: presets.composedPreset(agent?.ctx), registryMissing: false, failed: false };
+    }
+    catch {
+        return { claim: undefined, registryMissing: false, failed: true };
+    }
+}

package/lib/preset-ids.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Single source of Capital preset identity. Since 0.2.1 the preset id is the role
+ * identity used by root convergence, shell guards, role surfaces, diagnostics and tests.
+ * These strings must match `preset/capital-generation/agent.patch.yml` `config.id` and
+ * delegation `agentPreset` values; `config.id` is also session-log identity, so do not
+ * rename casually. `test/persona.test.mjs` cross-checks them.
+ */
+export declare const ROOT_PRESET_ID = "capital-generation";
+export declare const ROLE_PRESET_IDS: {
+    readonly collector: "capital-data-collector";
+    readonly junior: "capital-data-junior";
+    readonly specialist: "capital-visualization-specialist";
+    readonly retriever: "capital-web-retriever";
+    readonly analyst: "capital-data-analyst";
+};
+export type RolePresetId = (typeof ROLE_PRESET_IDS)[keyof typeof ROLE_PRESET_IDS];
+/** Role preset ids (array form avoids prototype-method coupling). */
+export declare const ROLE_PRESET_ID_LIST: readonly string[];
+/** Every preset claimed by this plugin: root plus five roles. */
+export declare const CAPITAL_PRESET_IDS: readonly string[];
+export declare function isCapitalPresetId(id: string | undefined): boolean;
+/**
+ * Roles reached only through delegation. They stay registered because delegation rows resolve
+ * `config.id`, but the host roster filter hides them from the new-session selector.
+ */
+export declare const INTERNAL_ROLE_PRESET_IDS: readonly string[];
+export declare function isInternalRolePresetId(id: unknown): boolean;
+/**
+ * Which preset may use which tool (enforced by `src/tool-exec.ts`). This replaces the old
+ * session-topology check, which rejected manually opened role sessions.
+ *
+ * The root preset must never appear in any set. These lists live at `src/` root because
+ * data and chart layers must not depend on the agents layer.
+ */
+export declare const DATA_COLLECTION_PRESET_IDS: readonly string[];
+export declare const DATASET_READING_PRESET_IDS: readonly string[];
+/** May issue `chart_source_ref` for chart reads. */
+export declare const CHART_SOURCE_PRESET_IDS: readonly string[];

package/lib/preset-ids.js

@@ -0,0 +1,46 @@
+/**
+ * Single source of Capital preset identity. Since 0.2.1 the preset id is the role
+ * identity used by root convergence, shell guards, role surfaces, diagnostics and tests.
+ * These strings must match `preset/capital-generation/agent.patch.yml` `config.id` and
+ * delegation `agentPreset` values; `config.id` is also session-log identity, so do not
+ * rename casually. `test/persona.test.mjs` cross-checks them.
+ */
+export const ROOT_PRESET_ID = 'capital-generation';
+export const ROLE_PRESET_IDS = {
+    collector: 'capital-data-collector',
+    junior: 'capital-data-junior',
+    specialist: 'capital-visualization-specialist',
+    retriever: 'capital-web-retriever',
+    analyst: 'capital-data-analyst',
+};
+/** Role preset ids (array form avoids prototype-method coupling). */
+export const ROLE_PRESET_ID_LIST = Object.values(ROLE_PRESET_IDS);
+/** Every preset claimed by this plugin: root plus five roles. */
+export const CAPITAL_PRESET_IDS = [ROOT_PRESET_ID, ...ROLE_PRESET_ID_LIST];
+const CAPITAL_PRESET_ID_SET = new Set(CAPITAL_PRESET_IDS);
+export function isCapitalPresetId(id) {
+    return id !== undefined && CAPITAL_PRESET_ID_SET.has(id);
+}
+/**
+ * Roles reached only through delegation. They stay registered because delegation rows resolve
+ * `config.id`, but the host roster filter hides them from the new-session selector.
+ */
+export const INTERNAL_ROLE_PRESET_IDS = [
+    ROLE_PRESET_IDS.junior,
+    ROLE_PRESET_IDS.specialist,
+];
+const INTERNAL_ROLE_PRESET_ID_SET = new Set(INTERNAL_ROLE_PRESET_IDS);
+export function isInternalRolePresetId(id) {
+    return typeof id === 'string' && INTERNAL_ROLE_PRESET_ID_SET.has(id);
+}
+/**
+ * Which preset may use which tool (enforced by `src/tool-exec.ts`). This replaces the old
+ * session-topology check, which rejected manually opened role sessions.
+ *
+ * The root preset must never appear in any set. These lists live at `src/` root because
+ * data and chart layers must not depend on the agents layer.
+ */
+export const DATA_COLLECTION_PRESET_IDS = [ROLE_PRESET_IDS.collector];
+export const DATASET_READING_PRESET_IDS = [ROLE_PRESET_IDS.junior, ROLE_PRESET_IDS.analyst];
+/** May issue `chart_source_ref` for chart reads. */
+export const CHART_SOURCE_PRESET_IDS = [ROLE_PRESET_IDS.junior];

package/lib/retriever-config.d.ts

@@ -0,0 +1,37 @@
+export interface WindDocsConfig {
+    endpoint?: string;
+    credentialRef?: string;
+    timeoutMs?: number;
+}
+export interface LocalFetchConfig {
+    enabled?: boolean;
+    timeoutMs?: number;
+    maxBytes?: number;
+    maxContentChars?: number;
+    maxRedirects?: number;
+    userAgent?: string;
+}
+/** `pollBudgetMs` must stay below the tool's declared 240000 ms timeout: the margin is for
+ * persisting the pending receipt, without which a framework timeout leaves no `doc_id`. */
+export interface PaddleOcrConfig {
+    endpoint?: string;
+    credentialRef?: string;
+    model?: string;
+    pollBudgetMs?: number;
+}
+export interface RetrieverConfig {
+    baseURL?: string;
+    credentialRef?: string;
+    windDocs?: WindDocsConfig;
+    localFetch?: LocalFetchConfig;
+    paddleOcr?: PaddleOcrConfig;
+}
+/** Sole default source for both the schema and `resolveLocalFetchConfig()`.
+ * timeoutMs 30000 matches dsh-web-fetch-http; 15s misreads slow proxy failover as TIMEOUT.
+ * maxContentChars applies to raw HTML before markdown conversion, so size it for HTML.
+ * userAgent is a product token: a bare version looks like a crawler to WAFs. */
+export declare const LOCAL_FETCH_DEFAULTS: Required<LocalFetchConfig>;
+/** Empty endpoint/model defer to `src/ocr/client.ts`; pollBudgetMs 0 defers to its DEFAULT_WAIT_BUDGET_MS. */
+export declare const PADDLE_OCR_DEFAULTS: Required<PaddleOcrConfig>;
+/** Consumers fill defaults themselves: `apply()` can receive a raw object that never passed the schema. */
+export declare function resolveLocalFetchConfig(config?: LocalFetchConfig): Required<LocalFetchConfig>;