dsh-vision-router 3.2.1 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +5 -4
  2. package/README.zh.md +20 -3
  3. package/THIRD_PARTY_NOTICES.md +60 -0
  4. package/assets/licenses/llvm-mingw-LICENSE.txt +279 -0
  5. package/assets/licenses/mingw-w64-runtime-COPYING.txt +265 -0
  6. package/assets/licenses/ncnn-LICENSE.txt +86 -0
  7. package/docs/architecture/dsh-support-window.md +25 -6
  8. package/docs/compatibility/dsh-0.2.2-rc3-audit.md +131 -0
  9. package/docs/releases/v3.2.2.md +25 -0
  10. package/docs/releases/v3.3.0.md +34 -0
  11. package/docs/releases/v3.4.0.md +41 -0
  12. package/index.js +313 -169
  13. package/lib/client.js +4 -4
  14. package/lib/core-primitives.js +115 -56
  15. package/lib/dsh-support-window.js +6 -3
  16. package/lib/maintenance-routes.js +2 -0
  17. package/lib/managed-tesseract-child.js +33 -0
  18. package/lib/native-ocr-annotation-risk.js +33 -0
  19. package/lib/native-ocr-canary.js +156 -0
  20. package/lib/native-ocr-chemistry-review.js +37 -0
  21. package/lib/native-ocr-document.js +243 -0
  22. package/lib/native-ocr-installation.js +17 -0
  23. package/lib/native-ocr-integrity.js +93 -0
  24. package/lib/native-ocr-question-labels.js +167 -0
  25. package/lib/native-ocr-supervisor.js +268 -0
  26. package/lib/optional-ocr-engines.js +330 -0
  27. package/lib/optional-ocr-routes.js +87 -0
  28. package/lib/runtime-reliability.js +7 -0
  29. package/lib/session-query-readers.js +8 -2
  30. package/lib/session-vision-attachment-index.js +61 -14
  31. package/lib/settings-ia-client-prelude.js +56 -2
  32. package/lib/tesseract-image-preprocess.js +35 -0
  33. package/lib/trace-vtracer-process-runtime.js +133 -0
  34. package/lib/trace-vtracer-process.js +43 -0
  35. package/lib/vision-attachment-handle-runtime.js +11 -2
  36. package/lib/vision-backend-runtime-policy.js +5 -3
  37. package/lib/vision-image-input-reader.js +67 -0
  38. package/lib/vision-image-input-verdict.js +24 -3
  39. package/lib/vision-tool-runtime-boundary.js +7 -10
  40. package/lib/vision-tool-stage.js +58 -0
  41. package/lib/web-capability-boundary.js +4 -0
  42. package/package.json +5 -4
  43. package/scripts/install-native-ocr.mjs +144 -0
package/lib/client.js CHANGED
@@ -394,8 +394,8 @@ openLogFolder,
394
394
  numVisionTaskTimeoutMs: '识图任务最长时间(毫秒)',
395
395
  numOcrTimeoutMs: 'OCR 最长时间(毫秒)',
396
396
  selectOcrEngine: 'OCR 默认引擎',
397
- hintOcrEngine: '决定 vision_ocr 未显式指定 engine 时的默认策略。自动:先本地 Tesseract,失败/空结果再用视觉模型;Tesseract:只用本地 OCR;视觉模型:直接跳过 Tesseract。单次工具调用显式 engine=tesseract/vision 始终优先。',
398
- ocrEngineAuto: '自动(Tesseract → 视觉模型)',
397
+ hintOcrEngine: '决定 vision_ocr 未显式指定 engine 时的默认策略。自动:优先已安装并校验的 PP-OCRv6(Mac ARM64 / Windows x64),否则使用本地 Tesseract,失败/空结果再用视觉模型;Tesseract:只用本地 OCR;视觉模型:直接跳过 Tesseract。单次工具调用显式 engine=tesseract/vision 始终优先。',
398
+ ocrEngineAuto: '自动(PP-OCRv6 → Tesseract → 视觉模型)',
399
399
  ocrEngineTesseract: '仅 Tesseract',
400
400
  ocrEngineVision: '仅视觉模型',
401
401
  numDownscaleMaxPixels: '图片像素上限',
@@ -682,8 +682,8 @@ openLogFolder,
682
682
  numVisionTaskTimeoutMs: 'Vision task maximum time (ms)',
683
683
  numOcrTimeoutMs: 'OCR maximum time (ms)',
684
684
  selectOcrEngine: 'Default OCR engine',
685
- hintOcrEngine: 'Default policy when vision_ocr does not explicitly choose an engine. Auto tries local Tesseract first and falls back to the vision model; Tesseract uses local OCR only; Vision skips Tesseract. An explicit engine=tesseract/vision on a tool call always wins.',
686
- ocrEngineAuto: 'Auto (Tesseract → vision)',
685
+ hintOcrEngine: 'Default policy when vision_ocr does not explicitly choose an engine. Auto prefers verified locally installed PP-OCRv6 (macOS ARM64 / Windows x64), otherwise local Tesseract; falls back to the vision model; Tesseract uses local OCR only; Vision skips Tesseract. An explicit engine=tesseract/vision on a tool call always wins.',
686
+ ocrEngineAuto: 'Auto (PP-OCRv6 → Tesseract → vision)',
687
687
  ocrEngineTesseract: 'Tesseract only',
688
688
  ocrEngineVision: 'Vision model only',
689
689
  numDownscaleMaxPixels: 'Image pixel limit',
@@ -4,11 +4,10 @@ import path from 'node:path'
4
4
 
5
5
  import { existsSync } from 'node:fs'
6
6
  import { execFile } from 'node:child_process'
7
- import { Worker } from 'node:worker_threads'
8
7
  import { createRequire } from 'node:module'
9
8
  import { pathToFileURL } from 'node:url'
10
- import { promisify } from 'node:util'
11
9
  import { fetchWithOpenAICompatibility } from './http-compat.js'
10
+ import { runIsolatedTraceProcess } from './trace-vtracer-process-runtime.js'
12
11
  import {
13
12
  directSessionAffinityHeaders,
14
13
  rawSessionIdentity,
@@ -652,7 +651,7 @@ export function cacheKeyFor({ pairs, httpProviders, contentIds, wantJson, questi
652
651
  ]
653
652
  const payload = JSON.stringify({
654
653
  chains,
655
- contentIds: [...(contentIds ?? [])].sort(),
654
+ contentIds: [...(contentIds ?? [])],
656
655
  mode: wantJson ? 'json' : 'text',
657
656
  question: String(question ?? ''),
658
657
  })
@@ -1191,51 +1190,11 @@ function isVisionAbort(error, signal) {
1191
1190
  return signal?.aborted === true || error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
1192
1191
  }
1193
1192
 
1194
- /** Shared hard-timeout and cancellation boundary for local VTracer SVG workers. */
1193
+ /** Shared deadline and cancellation wrapper around the isolated trace subprocess. */
1195
1194
  function runTraceWorker(mode, payload, timeoutMs, signal) {
1196
- const aborted = () => visionAbortReason(signal, 'vector trace aborted')
1197
- if (signal?.aborted) return Promise.reject(aborted())
1198
- return new Promise((resolve, reject) => {
1199
- let worker
1200
- let timer
1201
- let finished = false
1202
- const finish = (error, svg) => {
1203
- if (finished) return
1204
- finished = true
1205
- if (timer !== undefined) clearTimeout(timer)
1206
- signal?.removeEventListener?.('abort', onAbort)
1207
- if (worker) void worker.terminate().catch(() => {})
1208
- if (error) reject(error)
1209
- else resolve(svg)
1210
- }
1211
- const onAbort = () => finish(aborted())
1212
- signal?.addEventListener?.('abort', onAbort, { once: true })
1213
- if (signal?.aborted) { finish(aborted()); return }
1214
- if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
1215
- finish(new Error('vector trace timed out'))
1216
- return
1217
- }
1218
- timer = setTimeout(() => finish(new Error(
1219
- 'vector trace timed out — crop the image or reduce its complexity',
1220
- )), timeoutMs)
1221
- try {
1222
- // This file-backed runtime worker uses only published JavaScript and
1223
- // absolute peer imports; it never needs Host CLI, eval, test or loader
1224
- // flags. Inheriting them can fail or run unwanted diagnostic hooks.
1225
- worker = new Worker(new URL('./trace-vtracer-worker.js', import.meta.url), {
1226
- execArgv: [],
1227
- workerData: { mode, ...payload },
1228
- resourceLimits: { maxOldGenerationSizeMb: 192, maxYoungGenerationSizeMb: 32 },
1229
- })
1230
- worker.once('message', (message) => {
1231
- if (message?.ok === true && typeof message.svg === 'string') finish(undefined, message.svg)
1232
- else finish(new Error(String(message?.error || 'vector trace worker returned invalid output')))
1233
- })
1234
- worker.once('error', (error) => finish(error))
1235
- worker.once('exit', (code) => {
1236
- if (!finished) finish(new Error('vector trace worker exited before producing SVG (code ' + code + ')'))
1237
- })
1238
- } catch (error) { finish(error) }
1195
+ return runIsolatedTraceProcess({
1196
+ mode, payload, timeoutMs, signal,
1197
+ abortReason: () => visionAbortReason(signal, 'vector trace aborted'),
1239
1198
  })
1240
1199
  }
1241
1200
 
@@ -1291,9 +1250,89 @@ export function resolveVisionOcrEngine(requestedEngine, configuredEngine = 'auto
1291
1250
  return 'auto'
1292
1251
  }
1293
1252
 
1253
+ /** Node's asynchronous execFile does not support an \`input\` option.
1254
+ * Explicitly stream bounded image bytes to the subprocess's stdin.
1255
+ * The callback still owns timeout, AbortSignal, output cap and exit status.
1256
+ */
1257
+ export function execFileWithStdin(file, args, { input, ...options } = {}) {
1258
+ if (!(input instanceof Uint8Array)) {
1259
+ return Promise.reject(new TypeError('subprocess input must be a byte array'))
1260
+ }
1261
+ return new Promise((resolve, reject) => {
1262
+ let inputError
1263
+ const child = execFile(file, args, { encoding: 'utf8', ...options }, (error, stdout, stderr) => {
1264
+ if (error || inputError) reject(error ?? inputError)
1265
+ else resolve({ stdout, stderr })
1266
+ })
1267
+ if (!child.stdin) {
1268
+ child.kill()
1269
+ reject(new Error('subprocess stdin unavailable'))
1270
+ return
1271
+ }
1272
+ child.stdin.on('error', error => {
1273
+ inputError = error
1274
+ if (child.exitCode === null) child.kill()
1275
+ })
1276
+ try {
1277
+ child.stdin.end(input)
1278
+ } catch (error) {
1279
+ inputError = error
1280
+ child.kill()
1281
+ }
1282
+ })
1283
+ }
1284
+
1285
+ /** Never spend a model call on uncertain local OCR when the caller explicitly
1286
+ * requested local-only text, a breaker is degraded, or the shared deadline is low.
1287
+ */
1288
+ export function shouldVerifyUncertainAutoOcr({
1289
+ engine, uncertain, localOnlyVision, degraded, remainingMs,
1290
+ } = {}) {
1291
+ return engine === 'auto' && uncertain === true &&
1292
+ localOnlyVision !== true && degraded !== true &&
1293
+ Number.isFinite(remainingMs) && remainingMs >= 1200
1294
+ }
1295
+
1296
+ /**
1297
+ * A nonempty, uncertain local transcript remains useful evidence. In auto
1298
+ * mode only, optionally verify it using the caller's existing vision route,
1299
+ * without discarding the local result if no trustworthy review is available.
1300
+ * The caller owns permission, breaker, deadline and abort enforcement.
1301
+ */
1302
+ export async function verifyUncertainAutoOcrResult(localResult, {
1303
+ engine = 'auto', localOnlyVision = false, degraded = false,
1304
+ remainingMs = 0, verifyVision, checkAbort,
1305
+ } = {}) {
1306
+ if (!shouldVerifyUncertainAutoOcr({
1307
+ engine, uncertain: localResult?.uncertain, localOnlyVision, degraded, remainingMs,
1308
+ }) || typeof verifyVision !== 'function') return localResult
1309
+
1310
+ let vision
1311
+ try {
1312
+ vision = await verifyVision()
1313
+ } catch (error) {
1314
+ checkAbort?.(error)
1315
+ return localResult
1316
+ }
1317
+ checkAbort?.()
1318
+ if (vision?.ok === false || typeof vision?.text !== 'string' ||
1319
+ vision.text.trim() === '') return localResult
1320
+ return {
1321
+ engine: 'vision',
1322
+ text: vision.text.trim(),
1323
+ review: {
1324
+ fallbackReason: 'low_confidence_local_ocr',
1325
+ localEngine: localResult.engine,
1326
+ localText: localResult.text.slice(0, 1000),
1327
+ ...(Number.isFinite(localResult.review?.quality)
1328
+ ? { localQuality: localResult.review.quality } : {}),
1329
+ },
1330
+ }
1331
+ }
1332
+
1294
1333
  /** OCR image bytes with a local tesseract binary (chi_sim+eng) when available. */
1295
1334
  export async function ocrWithTesseract(bytes, timeoutMs = 60000, options = {}) {
1296
- const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
1335
+ const exec = typeof options.exec === 'function' ? options.exec : execFileWithStdin
1297
1336
  const signal = options.signal
1298
1337
  throwIfVisionAborted(signal, 'tesseract OCR aborted')
1299
1338
  const { stdout } = await exec(
@@ -1310,7 +1349,7 @@ export async function ocrWithTesseract(bytes, timeoutMs = 60000, options = {}) {
1310
1349
  return String(stdout ?? '')
1311
1350
  }
1312
1351
 
1313
- const TESSERACT_OCR_PSMS = Object.freeze([6, 3, 11])
1352
+ const TESSERACT_OCR_PSMS = Object.freeze([6, 7, 3, 11])
1314
1353
  const TESSERACT_REVIEW_THRESHOLD = 70
1315
1354
  const TESSERACT_CANDIDATE_MARGIN = 5
1316
1355
  const TESSERACT_CONFUSABLE_RUN = /[0O1IlL]{3,}/
@@ -1369,7 +1408,7 @@ export function selectTesseractOcrCandidate(candidates) {
1369
1408
  }
1370
1409
 
1371
1410
  export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options = {}) {
1372
- const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
1411
+ const exec = typeof options.exec === 'function' ? options.exec : execFileWithStdin
1373
1412
  const signal = options.signal
1374
1413
  const requestedBudget = Number(timeoutMs)
1375
1414
  const budgetMs = Number.isFinite(requestedBudget) && requestedBudget > 0
@@ -1378,27 +1417,27 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
1378
1417
  const started = Date.now()
1379
1418
  const attemptedPsms = []
1380
1419
  const remaining = () => Math.max(1, budgetMs - (Date.now() - started))
1381
- const run = async (psm) => {
1420
+ const run = async (psm, inputBytes = bytes, variant = 'original') => {
1382
1421
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1383
1422
  attemptedPsms.push(psm)
1384
1423
  const common = ['stdin', 'stdout', '-l', 'chi_sim+eng', '--psm', String(psm)]
1385
1424
  const execOptions = () => ({
1386
1425
  timeout: remaining(),
1387
1426
  maxBuffer: 32 * 1024 * 1024,
1388
- input: bytes,
1427
+ input: inputBytes,
1389
1428
  ...(signal === undefined ? {} : { signal }),
1390
1429
  })
1391
1430
  const { stdout: plain } = await exec('tesseract', common, execOptions())
1392
1431
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1393
1432
  const text = String(plain ?? '').trim()
1394
- if (text === '') return assessTesseractOcr('', '', psm)
1433
+ if (text === '') return { ...assessTesseractOcr('', '', psm), variant }
1395
1434
  try {
1396
1435
  const { stdout: tsv } = await exec('tesseract', [...common, 'tsv'], execOptions())
1397
1436
  throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1398
- return assessTesseractOcr(text, String(tsv ?? ''), psm)
1437
+ return { ...assessTesseractOcr(text, String(tsv ?? ''), psm), variant }
1399
1438
  } catch (error) {
1400
1439
  if (isVisionAbort(error, signal)) throw error
1401
- return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true }
1440
+ return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true, variant }
1402
1441
  }
1403
1442
  }
1404
1443
 
@@ -1415,7 +1454,27 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
1415
1454
  // Keep the first successful local OCR result when an optional review pass fails.
1416
1455
  }
1417
1456
  }
1418
- const selected = selectTesseractOcrCandidate(candidates) ?? candidates[0]
1457
+ let selected = selectTesseractOcrCandidate(candidates) ?? candidates[0]
1458
+ // Last resort only. A damaged/low-confidence original can still contain
1459
+ // a legitimate single subtitle line; a bounded local crop may recover it.
1460
+ if (selected.uncertain && typeof options.preprocess === 'function' &&
1461
+ budgetMs - (Date.now() - started) >= 900) {
1462
+ try {
1463
+ const processed = await options.preprocess(bytes, {
1464
+ signal, remainingMs: Math.max(0, budgetMs - (Date.now() - started)),
1465
+ })
1466
+ throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
1467
+ if (processed?.bytes instanceof Uint8Array && processed.bytes.length > 0 &&
1468
+ processed.bytes.length <= 16 * 1024 * 1024 &&
1469
+ budgetMs - (Date.now() - started) >= 500) {
1470
+ const retry = await run(7, processed.bytes, processed.variant ?? 'preprocessed')
1471
+ selected = selectTesseractOcrCandidate([...candidates, retry]) ?? selected
1472
+ }
1473
+ } catch (error) {
1474
+ if (isVisionAbort(error, signal)) throw error
1475
+ // The original best candidate still wins when preprocessing is unavailable.
1476
+ }
1477
+ }
1419
1478
  return { ...selected, attemptedPsms }
1420
1479
  }
1421
1480
 
@@ -10,6 +10,8 @@ export const DSH_SUPPORT_WINDOW = Object.freeze({
10
10
  export const DSH_VERIFICATION_EVIDENCE = Object.freeze({
11
11
  exactFloor: '0.2.1-rc.5',
12
12
  exactRecommended: '0.2.2-rc.1',
13
+ // Qualified exact-host evidence is distinct from the recommended upgrade target.
14
+ exactVerified: Object.freeze(['0.2.1-rc.5', '0.2.2-rc.1', '0.2.2-rc.2', '0.2.2-rc.3']),
13
15
  stableCanaryDistTag: 'latest',
14
16
  nextCanaryDistTag: 'next',
15
17
  previewCanaryDistTag: 'alpha',
@@ -70,7 +72,7 @@ export function supportWindowUpgradeAdvice(capabilities = {}, {
70
72
  }
71
73
  // Admission is an open 0.2.x train on purpose, not blanket evidence.
72
74
  // A later Host or Node major is not automatically verified by the exact
73
- // rc5/rc1, Node 24.9/24.21 matrix; Doctor reports unknown, not green.
75
+ // pinned-release Node 24.9/24.21 matrix; Doctor reports unknown, not green.
74
76
  if (semver.major(node) !== 24) {
75
77
  return Object.freeze({
76
78
  level: 'unknown', code: 'NODE_FORWARD_MAJOR_UNVERIFIED',
@@ -78,10 +80,10 @@ export function supportWindowUpgradeAdvice(capabilities = {}, {
78
80
  })
79
81
  }
80
82
  const exactHost = semver.valid(String(hostVersion).replace(/^v/, ''))
81
- if (![DSH_VERIFICATION_EVIDENCE.exactFloor, DSH_VERIFICATION_EVIDENCE.exactRecommended].includes(exactHost)) {
83
+ if (!DSH_VERIFICATION_EVIDENCE.exactVerified.includes(exactHost)) {
82
84
  return Object.freeze({
83
85
  level: 'unknown', code: 'HOST_FORWARD_RELEASE_UNVERIFIED',
84
- message: `DSH ${hostVersion} meets the 0.2.x admission range but lacks the two pinned exact-release acceptance gates`,
86
+ message: `DSH ${hostVersion} meets the 0.2.x admission range but has no exact-release acceptance evidence`,
85
87
  })
86
88
  }
87
89
  return Object.freeze({
@@ -102,6 +104,7 @@ export function formatDshSupportWindowLines(capabilities = {}, options = {}) {
102
104
  'DSH compatibility verification evidence:',
103
105
  ` exact supported Host floor: ${DSH_VERIFICATION_EVIDENCE.exactFloor}`,
104
106
  ` exact recommended Host: ${DSH_VERIFICATION_EVIDENCE.exactRecommended}`,
107
+ ` verified exact Host releases: ${DSH_VERIFICATION_EVIDENCE.exactVerified.join(', ')}`,
105
108
  ` scheduled published canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.stableCanaryDistTag}`,
106
109
  ` scheduled next/rc canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.nextCanaryDistTag}`,
107
110
  ` scheduled alpha/pre-release canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.previewCanaryDistTag}`,
@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto'
2
2
  import { createCachedUpdateChecker } from './update-check.js'
3
3
  import { isLocalUiRequest } from './web-capability-boundary.js'
4
4
  import { detectDshSelfUpdatePlan, runDshPluginUpdate } from './self-update.js'
5
+ import { installOptionalOcrRoutes } from './optional-ocr-routes.js'
5
6
 
6
7
  function json(res, status, body, headers = {}) {
7
8
  res.writeHead(status, {
@@ -20,6 +21,7 @@ function json(res, status, body, headers = {}) {
20
21
  */
21
22
  export function installVisionMaintenanceRoutes(ctx, options = {}) {
22
23
  if (!ctx || typeof ctx.inject !== 'function') return
24
+ installOptionalOcrRoutes(ctx, options.optionalOcr)
23
25
  const logger = options.logger ?? ctx.logger
24
26
  const updateChecker = options.updateChecker ?? createCachedUpdateChecker()
25
27
  const selfUpdatePlan = options.selfUpdatePlan ?? detectDshSelfUpdatePlan()
@@ -0,0 +1,33 @@
1
+ // Only spawned by the owner-scoped OCR manager. The parent enforces
2
+ // input/output bounds, cancellation and a hard process deadline.
3
+ import { readFile } from 'node:fs/promises'
4
+ import { join } from 'node:path'
5
+ import { pathToFileURL } from 'node:url'
6
+
7
+ async function main() {
8
+ const [root] = process.argv.slice(2)
9
+ if (!root) throw Error('missing managed Tesseract root')
10
+ const data = []
11
+ let length = 0
12
+ for await (const part of process.stdin) {
13
+ length += part.length
14
+ if (length > 24 * 1024 * 1024) throw Error('OCR image too large')
15
+ data.push(part)
16
+ }
17
+ const entry = pathToFileURL(join(root, 'node_modules', 'tesseract.js', 'src', 'index.js')).href
18
+ const mod = await import(entry)
19
+ const createWorker = mod.createWorker ?? mod.default?.createWorker
20
+ if (typeof createWorker !== 'function') throw Error('missing managed Tesseract worker')
21
+ let worker
22
+ try {
23
+ worker = await createWorker(['chi_sim', 'eng'], 1, {
24
+ langPath: join(root, 'models'), gzip: true, cacheMethod: 'none', logger: () => {},
25
+ })
26
+ const result = await worker.recognize(Buffer.concat(data, length))
27
+ process.stdout.write(JSON.stringify({
28
+ text: String(result?.data?.text ?? '').slice(0, 32768),
29
+ confidence: Number.isFinite(result?.data?.confidence) ? result.data.confidence : 0,
30
+ }) + '\n')
31
+ } finally { await worker?.terminate?.() }
32
+ }
33
+ main().catch(() => { process.stderr.write('managed Tesseract OCR failed\n'); process.exitCode = 1 })
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Optional visual-evidence flag for photographed pages with red pen annotations.
3
+ * This is NOT OCR: it never changes recognized text and never reconstructs
4
+ * hidden numeric dots or digits. Coordinates are from the same RGB source.
5
+ */
6
+ export function detectRedAnnotationNearText(rgb,width,height,box,{
7
+ scanWidth=165,redFractionThreshold=0.012,
8
+ }={}) {
9
+ if(!(rgb instanceof Uint8Array) ||
10
+ !Number.isSafeInteger(width) || !Number.isSafeInteger(height) ||
11
+ width<=0 || height<=0 || rgb.length!==width*height*3 ||
12
+ !Array.isArray(box) || box.length!==4 || !box.every(Number.isFinite)) {
13
+ return {detected:false,reason:'invalid_geometry'}
14
+ }
15
+ const x1=Math.max(0,Math.floor(box[0]))
16
+ const x2=Math.min(width,Math.ceil(box[2]),x1+scanWidth)
17
+ const y1=Math.max(0,Math.floor(box[1]))
18
+ const y2=Math.min(height,Math.ceil(box[3]))
19
+ if(x2<=x1 || y2<=y1)return {detected:false,reason:'empty_region'}
20
+ let colored=0,total=0
21
+ for(let y=y1;y<y2;y++){
22
+ for(let x=x1;x<x2;x++){
23
+ const at=(y*width+x)*3
24
+ const r=rgb[at],g=rgb[at+1],b=rgb[at+2]
25
+ if(r>80 && r-g>35 && r-b>46)colored++
26
+ total++
27
+ }
28
+ }
29
+ const fraction=colored/total
30
+ const detected=colored>=15 && fraction>=redFractionThreshold
31
+ return {detected,redPixelFraction:Math.round(fraction*10000)/10000,
32
+ redPixelCount:colored,scannedPixelCount:total}
33
+ }
@@ -0,0 +1,156 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { createReadStream } from 'node:fs'
3
+ import { lstat, realpath } from 'node:fs/promises'
4
+ import { isAbsolute } from 'node:path'
5
+ import { performance } from 'node:perf_hooks'
6
+ import { runIsolatedLocalOcr, LocalOcrProcessError } from './native-ocr-supervisor.js'
7
+ import { runExperimentalNativeDocumentOcr } from './native-ocr-document.js'
8
+ import { verifyNativeOcrAssets } from './native-ocr-integrity.js'
9
+
10
+ const MAX_TIME_MS = 22_000
11
+ const MAX_DECODE_INPUT_BYTES = 24 * 1024 * 1024
12
+ const MAX_INPUT_PIXELS = 16_000_000
13
+ // SHA-pinned experimental identities for owner-installed native OCR workers.
14
+ // These hashes do NOT establish public redistribution clearance. A public
15
+ // model/binary archive needs signed clean-CI builds, SBOM and all notices;
16
+ // the JS/npm release must not silently bundle these native assets.
17
+ export const EXPERIMENTAL_OCR_BINARY_SHA256 = Object.freeze({
18
+ 'darwin-arm64': '71d535b86b0543e7408b41ed66f45d3bea46e09e0e3f38aa491a32a60085d204',
19
+ 'win32-x64': '2e4b96a204c34eebe11f117049b1a3b966f43a8402a66065c28773528cd18a33',
20
+ })
21
+
22
+ function fail(code, description) {
23
+ return new LocalOcrProcessError(code, description)
24
+ }
25
+ async function hashFile(path) {
26
+ const hash = createHash('sha256')
27
+ for await (const buf of createReadStream(path)) hash.update(buf)
28
+ return hash.digest('hex')
29
+ }
30
+
31
+ export async function verifyExperimentalNativeOcrBinary(binaryPath, {
32
+ platform = process.platform,
33
+ arch = process.arch,
34
+ binaryDigests = EXPERIMENTAL_OCR_BINARY_SHA256,
35
+ } = {}) {
36
+ const expected = binaryDigests[platform + '-' + arch]
37
+ if (!expected) throw fail('OCR_UNSUPPORTED_PLATFORM', 'native OCR preview unsupported on this platform')
38
+ if (typeof binaryPath !== 'string' || !isAbsolute(binaryPath)) {
39
+ throw fail('OCR_UNTRUSTED_RUNNER', 'native OCR binary path must be absolute')
40
+ }
41
+ let info
42
+ try {
43
+ info = await lstat(binaryPath)
44
+ if (!info.isFile() || info.isSymbolicLink() || info.size > 32 * 1024 * 1024) {
45
+ throw new Error('not a regular executable')
46
+ }
47
+ // On macOS /tmp is an OS-managed symlink to /private/tmp; requiring
48
+ // literal canonical-path equality would reject legitimate runner files.
49
+ // Reject a symlink at the file itself and pin file content by SHA-256.
50
+ const canonical = await realpath(binaryPath)
51
+ if (!isAbsolute(canonical)) throw new Error('invalid canonical path')
52
+ } catch {
53
+ throw fail('OCR_UNTRUSTED_RUNNER', 'native OCR runner missing or invalid')
54
+ }
55
+ const digest = await hashFile(binaryPath)
56
+ if (digest !== expected) throw fail('OCR_BINARY_INTEGRITY', 'native OCR executable integrity mismatch')
57
+ return { ok: true, digest }
58
+ }
59
+
60
+ function isAbort(signal, error) {
61
+ return signal?.aborted || error?.code === 'OCR_CANCELLED' || error?.name === 'AbortError'
62
+ }
63
+
64
+ /**
65
+ * Build the same strict RGB24 input used by the native ncnn worker. sharp is
66
+ * Host-owned and supplied lazily; native code does not parse untrusted JPEG
67
+ * and is never given an image file path. Existing image admission happens
68
+ * before calling this function.
69
+ */
70
+ export async function decodeExperimentalOcrRgb(bytes, {
71
+ loadSharp,
72
+ signal,
73
+ } = {}) {
74
+ // DSH's attachment store returns Uint8Array; filesystem reads may be Buffer.
75
+ // Normalize only byte views, preserving byteOffset/byteLength so no adjacent
76
+ // ArrayBuffer content is decoded or transported to the native process.
77
+ if (!(bytes instanceof Uint8Array) || bytes.byteLength < 8 ||
78
+ bytes.byteLength > MAX_DECODE_INPUT_BYTES) {
79
+ throw fail('OCR_INVALID_INPUT', 'invalid image buffer')
80
+ }
81
+ const imageBuffer = Buffer.isBuffer(bytes)
82
+ ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
83
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
84
+ if (typeof loadSharp !== 'function') throw fail('OCR_DECODER_MISSING', 'sharp loader unavailable')
85
+ const sharp = await loadSharp()
86
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
87
+ const { data, info } = await sharp(imageBuffer, {
88
+ failOn: 'error',
89
+ limitInputPixels: MAX_INPUT_PIXELS,
90
+ sequentialRead: true,
91
+ })
92
+ .rotate()
93
+ .resize({ width: 2048, height: 2048, fit: 'inside', withoutEnlargement: true })
94
+ .removeAlpha()
95
+ .toColourspace('srgb')
96
+ .raw()
97
+ .toBuffer({ resolveWithObject: true })
98
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
99
+ if (!info || !Number.isSafeInteger(info.width) || !Number.isSafeInteger(info.height) ||
100
+ info.channels !== 3 || info.width < 1 || info.height < 1 ||
101
+ info.width > 4096 || info.height > 4096 ||
102
+ info.width * info.height > 4_000_000 ||
103
+ data.byteLength !== info.width * info.height * 3) {
104
+ throw fail('OCR_INVALID_RGB', 'decoded image outside native OCR limits')
105
+ }
106
+ return { rgb: data, width: info.width, height: info.height }
107
+ }
108
+
109
+ /**
110
+ * Called only for explicit isolated canary tests or when auto mode finds an
111
+ * approved owner-installed native worker; absent native assets cannot enable
112
+ * OCR by themselves. The executable's hash AND all 5 model/charset file hashes
113
+ * must match before the child process can be started.
114
+ *
115
+ * Returns full document OCR evidence for the caller to render conservatively.
116
+ * Does not contact any vision service, change user settings or mutate images.
117
+ */
118
+ export async function runExperimentalNativeOcrCanary(bytes, {
119
+ binaryPath,
120
+ modelDir,
121
+ loadSharp,
122
+ signal,
123
+ timeoutMs = 18_000,
124
+ platform = process.platform,
125
+ arch = process.arch,
126
+ binaryDigests,
127
+ } = {}) {
128
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
129
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
130
+ throw fail('OCR_INVALID_TIMEOUT', 'invalid native OCR timeout')
131
+ }
132
+ const started = performance.now()
133
+ const budget = Math.min(MAX_TIME_MS, Math.floor(timeoutMs))
134
+ const left = () => budget - (performance.now() - started)
135
+ // Cheap gate first: don't decode an untrusted image if model assets are broken.
136
+ await verifyExperimentalNativeOcrBinary(binaryPath, { platform, arch, binaryDigests })
137
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
138
+ await verifyNativeOcrAssets(modelDir)
139
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
140
+ const { rgb, width, height } = await decodeExperimentalOcrRgb(bytes, { loadSharp, signal })
141
+ if (left() <= 0) throw fail('OCR_TIMEOUT', 'native OCR time exhausted before inference')
142
+ const nativeRun = (frame, options) => runIsolatedLocalOcr(frame, {
143
+ executable: binaryPath,
144
+ args: [modelDir],
145
+ timeoutMs: Math.min(Math.max(1, left()), options.timeoutMs),
146
+ signal,
147
+ })
148
+ const result = await runExperimentalNativeDocumentOcr(rgb, width, height, {
149
+ nativeRun, signal, timeoutMs: Math.max(1, left()),
150
+ })
151
+ if (signal?.aborted) throw fail('OCR_CANCELLED', 'OCR cancelled')
152
+ if (!result || typeof result.text !== 'string') {
153
+ throw fail('OCR_INVALID_RESULT', 'native OCR returned malformed result')
154
+ }
155
+ return result
156
+ }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Minimal evidence-backed chemistry glyph reconciliation for photographed
3
+ * textbook pages. Never fabricates a number or changes element stoichiometry.
4
+ */
5
+ const normalizeSpecies = text => text.normalize('NFKC').replace(/\s+/g,'')
6
+ const speciesPattern = /([A-Z][A-Za-z0-9]{1,18})\(1\)/g
7
+
8
+ export function reviewChemicalStateGlyphs(regions) {
9
+ const updates=[]
10
+ const normalized=regions.map(r=>normalizeSpecies(String(r.text??'')))
11
+ for(let i=0;i<regions.length;i++) {
12
+ const row=regions[i]
13
+ if(!row.text || !/[+=→]/.test(row.text))continue
14
+ const input=normalizeSpecies(row.text)
15
+ const matches=[...input.matchAll(speciesPattern)]
16
+ for(const match of matches) {
17
+ const species=match[1]
18
+ // '1' is not a valid physical-state label. Prefer independently
19
+ // recognized '(l)' only when the *same species* occurs elsewhere.
20
+ const expected=species+'(l)'
21
+ const verifiedElsewhere=normalized.some((line,j)=>j!==i && line.includes(expected))
22
+ if(!verifiedElsewhere)continue
23
+ const erroneous=species+'(1)'
24
+ if(!row.text.includes(erroneous))continue
25
+ const corrected=row.text.replace(erroneous,expected)
26
+ if(corrected===row.text)continue
27
+ row.text=corrected
28
+ row.uncertain=true
29
+ row.phaseGlyphReconciled=true
30
+ row.phaseEvidence={before:erroneous,after:expected,
31
+ reason:'same_species_independently_recognized_with_liquid_state'}
32
+ updates.push({index:i,...row.phaseEvidence})
33
+ break
34
+ }
35
+ }
36
+ return {regions,updates}
37
+ }