@arcships/light-ocr 0.2.0 → 0.3.2

package/js/exif.cjs

@@ -0,0 +1,241 @@
+'use strict';
+
+// Minimal JPEG EXIF orientation parser (D106, D-N1-5).
+// Reads the orientation tag from the JPEG APP1 segment and applies the
+// corresponding pixel transform. Zero-dependency, stb-style.
+//
+// Only orientation (tag 0x0112) is read. Other EXIF fields are skipped.
+// PNG eXIf is not handled here; PNG has no EXIF orientation in v1.
+//
+// References:
+// - JEITA CP-3451C (Exif 2.3) section 4.6.4 (APP1 structure)
+// - TIFF tag 0x0112 Orientation
+
+// Parse the EXIF orientation value from a JPEG buffer.
+// Returns 1..8 if found, or 1 (normal) if not present / not a JPEG.
+function parseExifOrientation(buffer) {
+  if (!buffer || buffer.length < 4) return 1;
+  // JPEG must start with SOI marker 0xFFD8
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return 1;
+
+  let offset = 2;
+  while (offset + 1 < buffer.length) {
+    // Each marker: 0xFF then marker code
+    if (buffer[offset] !== 0xff) return 1;
+    const marker = buffer[offset + 1];
+    offset += 2;
+
+    // SOI (D8), EOI (D9), RSTn (D0-D7), TEM (01): no payload
+    if (marker === 0xd8 || marker === 0xd9) return 1;
+    if (marker >= 0xd0 && marker <= 0xd7) continue;
+    if (marker === 0x01) continue;
+
+    // SOS (DA): start of scan — EXIF would be before this
+    if (marker === 0xda) return 1;
+
+    // All other markers have a 2-byte length (including the length bytes)
+    if (offset + 1 >= buffer.length) return 1;
+    const length = (buffer[offset] << 8) | buffer[offset + 1];
+    if (length < 2 || offset + length > buffer.length) return 1;
+
+    // APP1 marker is 0xFFE1
+    if (marker === 0xe1) {
+      const orientation = tryParseApp1(buffer, offset, length);
+      if (orientation) return orientation;
+    }
+
+    offset += length;
+  }
+  return 1;
+}
+
+// Try to parse APP1 as EXIF. Returns orientation 1..8 or 0 if not EXIF.
+function tryParseApp1(buffer, dataOffset, segmentLength) {
+  // APP1 data starts after the 2-byte length field
+  // EXIF header: "Exif\0\0" (6 bytes)
+  const exifHeader = dataOffset + 2;
+  if (exifHeader + 6 > dataOffset + segmentLength) return 0;
+  if (buffer[exifHeader] !== 0x45 || buffer[exifHeader + 1] !== 0x78 ||
+      buffer[exifHeader + 2] !== 0x69 || buffer[exifHeader + 3] !== 0x66 ||
+      buffer[exifHeader + 4] !== 0x00 || buffer[exifHeader + 5] !== 0x00) {
+    return 0; // not EXIF (could be XMP)
+  }
+
+  // TIFF header starts here
+  const tiffStart = exifHeader + 6;
+  if (tiffStart + 8 > dataOffset + segmentLength) return 0;
+
+  // Byte order: II (little-endian) or MM (big-endian)
+  const littleEndian = buffer[tiffStart] === 0x49 && buffer[tiffStart + 1] === 0x49;
+  const bigEndian = buffer[tiffStart] === 0x4d && buffer[tiffStart + 1] === 0x4d;
+  if (!littleEndian && !bigEndian) return 0;
+  const le = littleEndian;
+
+  // Magic number 42 (0x002A)
+  const magic = readU16(buffer, tiffStart + 2, le);
+  if (magic !== 0x002a) return 0;
+
+  // Offset to IFD0 from TIFF start
+  const ifdOffset = tiffStart + readU32(buffer, tiffStart + 4, le);
+  if (ifdOffset + 2 > dataOffset + segmentLength) return 0;
+
+  const entryCount = readU16(buffer, ifdOffset, le);
+  for (let i = 0; i < entryCount; i++) {
+    const entryOffset = ifdOffset + 2 + i * 12;
+    if (entryOffset + 12 > dataOffset + segmentLength) break;
+    const tag = readU16(buffer, entryOffset, le);
+    if (tag === 0x0112) { // Orientation
+      const type = readU16(buffer, entryOffset + 2, le);
+      const count = readU32(buffer, entryOffset + 4, le);
+      if (type === 3 && count === 1) { // SHORT
+        const value = readU16(buffer, entryOffset + 8, le);
+        if (value >= 1 && value <= 8) return value;
+      }
+      return 0;
+    }
+  }
+  return 0;
+}
+
+function readU16(buffer, offset, littleEndian) {
+  if (littleEndian) return buffer[offset] | (buffer[offset + 1] << 8);
+  return (buffer[offset] << 8) | buffer[offset + 1];
+}
+
+function readU32(buffer, offset, littleEndian) {
+  if (littleEndian) {
+    return (buffer[offset]) |
+           (buffer[offset + 1] << 8) |
+           (buffer[offset + 2] << 16) |
+           (buffer[offset + 3] << 24);
+  }
+  return (buffer[offset] << 24) |
+         (buffer[offset + 1] << 16) |
+         (buffer[offset + 2] << 8) |
+         (buffer[offset + 3]);
+}
+
+// Apply EXIF orientation to RGB pixel data.
+// input: { data: Uint8Array (RGB), width, height }
+// orientation: 1..8
+// Returns { data, width, height } in pageSpace (orientation-corrected).
+function applyOrientation(pixels, orientation) {
+  if (orientation === 1) return pixels; // normal, no transform
+
+  const { data, width: w, height: h } = pixels;
+  const channels = 3;
+
+  switch (orientation) {
+    case 2: // flip horizontal
+      return flipHorizontal(data, w, h, channels);
+    case 3: // rotate 180
+      return rotate180(data, w, h, channels);
+    case 4: // flip vertical
+      return flipVertical(data, w, h, channels);
+    case 5: // transpose (flip horizontal + rotate 270 CW)
+      return transpose(data, w, h, channels);
+    case 6: // rotate 90 CW
+      return rotate90CW(data, w, h, channels);
+    case 7: // transverse (flip horizontal + rotate 90 CW)
+      return transverse(data, w, h, channels);
+    case 8: // rotate 90 CCW (= 270 CW)
+      return rotate90CCW(data, w, h, channels);
+    default:
+      return pixels;
+  }
+}
+
+function alloc(w, h, channels) {
+  return { data: new Uint8Array(w * h * channels), width: w, height: h };
+}
+
+function flipHorizontal(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = (y * w + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function flipVertical(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * w + x) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate180(data, w, h, c) {
+  const out = alloc(w, h, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * w + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate90CW(data, w, h, c) {
+  // new dimensions: h x w
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      // (x, y) -> (h-1-y, x) in the new w'=h, h'=w grid
+      const dst = (x * h + (h - 1 - y)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function rotate90CCW(data, w, h, c) {
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      // (x, y) -> (y, w-1-x)
+      const dst = ((w - 1 - x) * h + y) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function transpose(data, w, h, c) {
+  // transpose: (x,y) -> (y,x)
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = (x * h + y) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+function transverse(data, w, h, c) {
+  // transverse: (x,y) -> (h-1-y, w-1-x)
+  const out = alloc(h, w, c);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const src = (y * w + x) * c;
+      const dst = ((h - 1 - y) * h + (w - 1 - x)) * c;
+      for (let i = 0; i < c; i++) out.data[dst + i] = data[src + i];
+    }
+  }
+  return out;
+}
+
+module.exports = { parseExifOrientation, applyOrientation };

package/js/index.cjs

@@ -7,7 +7,10 @@ const { loadNative } = require('./load-native.cjs');
 
 const DEFAULT_MODEL = 'ppocrv6-small';
 const MODEL_PACKAGE = '@arcships/light-ocr-model-ppocrv6-small';
-const EXPECTED_BUNDLE_ID = 'ppocrv6-small-onnx-20260714.2';
+const CPU_BUNDLE_ID = 'ppocrv6-small-onnx-20260714.2';
+const APPLE_BUNDLE_ID = 'ppocrv6-small-apple-20260715.1';
+const WEBGPU_BUNDLE_ID = 'ppocrv6-small-webgpu-20260719.1';
+const NATIVE_BUNDLE_ID = 'ppocrv6-small-native-20260719.1';
 
 class OcrError extends Error {
   constructor(code, message, detail) {
@@ -49,7 +52,7 @@ function abortReason(signal) {
     : signal.reason;
 }
 
-function resolveBuiltInBundle(model) {
+function resolveBuiltInBundle(model, requireApple) {
   if (model !== DEFAULT_MODEL) {
     throw new OcrError(
       'invalid_argument',
@@ -76,11 +79,14 @@ function resolveBuiltInBundle(model) {
       cause instanceof Error ? cause.message : String(cause),
     );
   }
-  if (manifest.bundleId !== EXPECTED_BUNDLE_ID) {
+  const compatibleBundleIds = requireApple
+    ? [APPLE_BUNDLE_ID, NATIVE_BUNDLE_ID]
+    : [CPU_BUNDLE_ID, APPLE_BUNDLE_ID, WEBGPU_BUNDLE_ID, NATIVE_BUNDLE_ID];
+  if (!compatibleBundleIds.includes(manifest.bundleId)) {
     throw new OcrError(
       'package_load_failed',
       'The installed model package is incompatible with this light-ocr release',
-      `expected ${EXPECTED_BUNDLE_ID}, received ${String(manifest.bundleId)}`,
+      `expected ${compatibleBundleIds.join(' or ')}, received ${String(manifest.bundleId)}`,
     );
   }
   return path.dirname(manifestPath);
@@ -101,7 +107,8 @@ function resolveCreateOptions(options) {
   }
   if (hasBundlePath) return options;
   const model = hasModel ? options.model : DEFAULT_MODEL;
-  const resolved = { ...options, bundlePath: resolveBuiltInBundle(model) };
+  const requireApple = options.execution?.provider === 'apple';
+  const resolved = { ...options, bundlePath: resolveBuiltInBundle(model, requireApple) };
   delete resolved.model;
   return resolved;
 }
@@ -124,6 +131,10 @@ class OcrEngineImpl {
     return this.#recognize('recognizeEncoded', data, options);
   }
 
+  detect(data, options = {}) {
+    return this.#recognize('detect', data, options);
+  }
+
   #recognize(nativeMethod, image, options) {
     let signal;
     let nativeOptions;
@@ -196,13 +207,16 @@ class OcrEngineImpl {
   }
 }
 
-let binding;
+let nativeRuntime;
 
 async function createEngine(options) {
   try {
     const resolvedOptions = resolveCreateOptions(options);
-    if (!binding) binding = loadNative();
-    const nativeEngine = await binding.createEngine(resolvedOptions);
+    if (!nativeRuntime) nativeRuntime = loadNative();
+    const nativeEngine = await nativeRuntime.binding.createEngine(
+      resolvedOptions,
+      nativeRuntime.runtimePolicy,
+    );
     return new OcrEngineImpl(nativeEngine);
   } catch (error) {
     throw normalizeNativeError(error);

package/js/index.d.ts

@@ -3,12 +3,28 @@
 export type PixelFormat = 'gray8' | 'rgb8' | 'bgr8' | 'rgba8';
 export type DetectionStrategy = 'bounded' | 'tiled' | 'upstreamExact';
 export type BuiltInModel = 'ppocrv6-small';
+export type ExecutionProvider = 'auto' | 'cpu' | 'apple' | 'webgpu';
+export type SessionFallback = 'error' | 'cpu';
+export type CpuPartition = 'allow' | 'forbid';
+export type PerformanceHint = 'latency' | 'throughput';
+/** WebGPU accepts auto/fp32; fp16 is reserved for the Apple provider. */
+export type Precision = 'auto' | 'fp32' | 'fp16';
 
 export interface DetectionOptions {
   readonly strategy?: DetectionStrategy;
   readonly maxSide?: number;
 }
 
+export interface ExecutionOptions {
+  /** Only providers shipped and qualified by this release appear in this union. */
+  readonly provider?: ExecutionProvider;
+  readonly sessionFallback?: SessionFallback;
+  readonly cpuPartition?: CpuPartition;
+  readonly deviceId?: number;
+  readonly performanceHint?: PerformanceHint;
+  readonly precision?: Precision;
+}
+
 export interface RawImage {
   readonly data: Uint8Array;
   readonly width: number;
@@ -43,6 +59,7 @@ export interface CreateEngineOptions {
   readonly queueCapacity?: number;
   readonly maxPendingInputBytes?: number;
   readonly detection?: DetectionOptions;
+  readonly execution?: ExecutionOptions;
 }
 
 export interface RecognizeOptions {
@@ -52,9 +69,17 @@ export interface RecognizeOptions {
   readonly signal?: AbortSignal;
   readonly useTextlineOrientation?: boolean;
   readonly detectionMaxSide?: number;
+  readonly applyExif?: boolean;
+  readonly region?: Rect;
 }
 
 export interface Point { readonly x: number; readonly y: number }
+export interface Rect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
 export interface OcrLine {
   readonly text: string;
   readonly confidence: number;
@@ -67,6 +92,9 @@ export interface RecognitionBatchShape {
   readonly batchSize: number;
   readonly height: number;
   readonly width: number;
+  readonly computeUnit: 'cpu' | 'ane' | 'gpu';
+  readonly modelId: string;
+  readonly shapeBucket: string;
 }
 export interface DetectionPassShape {
   readonly tileOrdinal: number;
@@ -121,13 +149,76 @@ export interface TiledDetectionInfo {
   readonly mergeIouThreshold: 0.5;
   readonly mergeIosThreshold: 0.8;
 }
+export interface ProviderCapabilityInfo {
+  readonly provider: string;
+  readonly packageIncluded: boolean;
+  readonly deviceAvailable: boolean;
+  /** True only when this exact hardware family has reviewed qualification evidence. */
+  readonly deviceValidated: boolean;
+}
+export interface SessionExecutionInfo {
+  readonly requestedProvider: string;
+  readonly actualProviderChain: readonly string[];
+  readonly device: string;
+  readonly deviceFamily: string;
+  readonly operatingSystem: string;
+  readonly precision: string;
+  readonly shapePolicy: string;
+  readonly modelId: string;
+  readonly modelSha256: string;
+  readonly runtime: string;
+  readonly runtimeVersion: string;
+  readonly providerVersion: string;
+  readonly modelCacheStatus: string;
+  readonly qualificationId: string;
+  /** False means the open macOS compatibility path is experimental on this device. */
+  readonly deviceValidated: boolean;
+  readonly sessionFallback: boolean;
+  readonly fallbackReason?: string;
+}
+export type CreationReason =
+  | 'adapter_unavailable' | 'model_compute_unsupported'
+  | 'device_memory_insufficient' | 'driver_version_unsupported'
+  | 'package_corrupt' | 'artifact_hash_mismatch' | 'provider_abi_mismatch'
+  | 'internal_assertion_failed' | 'unrecoverable_load_failed';
+export type CreationAttemptStatus = 'selected' | 'skipped' | 'fatal';
+export interface CreationAttempt {
+  readonly provider: string;
+  readonly status: CreationAttemptStatus;
+  readonly creationReason?: CreationReason;
+  readonly errorCode?: CoreErrorCode;
+}
+export interface CreationTrace {
+  readonly requestedProvider: string;
+  readonly policyId?: string;
+  readonly policyVersion?: number;
+  readonly orderedCandidates: readonly string[];
+  readonly attempts: readonly CreationAttempt[];
+  readonly selectedProvider?: string;
+}
+export interface ExecutionInfo {
+  readonly requestedProvider: ExecutionProvider;
+  readonly sessionFallback: SessionFallback;
+  readonly cpuPartition: CpuPartition;
+  readonly deviceId?: number;
+  readonly performanceHint: PerformanceHint;
+  readonly requestedPrecision: Precision;
+  readonly providerCapabilities: readonly ProviderCapabilityInfo[];
+  readonly selectionTrace: CreationTrace;
+  readonly sessions: {
+    readonly detection: SessionExecutionInfo;
+    readonly recognition: SessionExecutionInfo;
+  };
+}
 export interface EngineInfo {
   readonly coreVersion: string;
   readonly modelBundleId: string;
   readonly modelBundleSchemaVersion: string;
   readonly normalizedConfigSchemaVersion: string;
   readonly backend: string;
+  /** @deprecated Use execution.sessions for stage-specific provider details. */
   readonly executionProvider: string;
+  readonly execution: ExecutionInfo;
   readonly capabilities: {
     readonly detection: boolean;
     readonly recognition: boolean;
@@ -166,13 +257,28 @@ export class OcrError extends Error {
   readonly name: 'OcrError';
   readonly code: OcrErrorCode;
   readonly detail?: string;
+  readonly creationTrace?: CreationTrace;
 }
 
 export interface OcrEngine {
   readonly info: EngineInfo;
   recognize(image: RawImage, options?: RecognizeOptions): Promise<OcrResult>;
   recognizeEncoded(data: Uint8Array, options?: RecognizeOptions): Promise<OcrResult>;
+  detect(data: Uint8Array, options?: RecognizeOptions): Promise<DetectionResult>;
   close(): Promise<void>;
 }
 
+export interface DetectionBox {
+  readonly score: number;
+  readonly box: readonly [Point, Point, Point, Point];
+}
+
+export interface DetectionResult {
+  readonly boxes: readonly DetectionBox[];
+  readonly imageWidth: number;
+  readonly imageHeight: number;
+  readonly modelBundleId: string;
+  readonly timingUs: TimingUs;
+}
+
 export function createEngine(options?: CreateEngineOptions): Promise<OcrEngine>;

package/js/load-native.cjs

@@ -1,26 +1,9 @@
 'use strict';
 
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 
-function candidatePaths() {
-  const candidates = [];
-  if (process.env.LIGHT_OCR_NODE_BINARY) {
-    candidates.push(path.resolve(process.env.LIGHT_OCR_NODE_BINARY));
-  }
-  candidates.push(path.join(__dirname, 'native', 'light_ocr_node.node'));
-  candidates.push(
-    path.join(
-      __dirname,
-      '..',
-      'prebuilds',
-      `${process.platform}-${process.arch}`,
-      'light_ocr_node.node',
-    ),
-  );
-  return candidates;
-}
-
 function adapterError(code, message, detail, cause) {
   const error = new Error(message, cause === undefined ? undefined : { cause });
   error.name = 'OcrError';
@@ -29,52 +12,488 @@ function adapterError(code, message, detail, cause) {
   return error;
 }
 
-function platformPackage() {
+function platformIdentity() {
   const key = `${process.platform}-${process.arch}`;
-  const packages = {
-    'darwin-arm64': '@arcships/light-ocr-darwin-arm64',
-    'darwin-x64': '@arcships/light-ocr-darwin-x64',
-    'win32-x64': '@arcships/light-ocr-win32-x64',
+  const identities = {
+    'darwin-arm64': { id: 'macos-arm64', os: 'darwin', architecture: 'arm64' },
+    'darwin-x64': { id: 'macos-x64', os: 'darwin', architecture: 'x86_64' },
+    'win32-arm64': { id: 'windows-arm64', os: 'win32', architecture: 'arm64' },
+    'win32-x64': { id: 'windows-x64', os: 'win32', architecture: 'x86_64' },
   };
   if (key === 'linux-x64') {
     const report = process.report?.getReport?.();
     if (report?.header?.glibcVersionRuntime) {
-      return '@arcships/light-ocr-linux-x64-gnu';
+      return { id: 'linux-x64', os: 'linux', architecture: 'x86_64', libc: 'glibc' };
     }
     throw adapterError(
       'unsupported_platform',
       'light-ocr currently supports Linux x64 with glibc only',
-      `${process.platform}-${process.arch}`,
+      key,
     );
   }
-  const packageName = packages[key];
-  if (!packageName) {
+  if (key === 'linux-arm64') {
+    const report = process.report?.getReport?.();
+    if (report?.header?.glibcVersionRuntime) {
+      return { id: 'linux-arm64', os: 'linux', architecture: 'arm64', libc: 'glibc' };
+    }
     throw adapterError(
       'unsupported_platform',
-      `light-ocr does not support ${key}`,
+      'light-ocr currently supports Linux arm64 with glibc only',
       key,
     );
   }
-  return packageName;
+  const identity = identities[key];
+  if (!identity) {
+    throw adapterError('unsupported_platform', `light-ocr does not support ${key}`, key);
+  }
+  return identity;
 }
 
-function loadNative() {
-  const candidates = candidatePaths();
-  const binary = candidates.find((candidate) => fs.existsSync(candidate));
-  if (binary) return require(binary);
+function platformPackage() {
+  const packages = {
+    'macos-arm64': '@arcships/light-ocr-darwin-arm64',
+    'macos-x64': '@arcships/light-ocr-darwin-x64',
+    'windows-arm64': '@arcships/light-ocr-win32-arm64',
+    'windows-x64': '@arcships/light-ocr-win32-x64',
+    'linux-x64': '@arcships/light-ocr-linux-x64-gnu',
+    'linux-arm64': '@arcships/light-ocr-linux-arm64-gnu',
+  };
+  return packages[platformIdentity().id];
+}
+
+function exactKeys(value, expected, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw adapterError('package_load_failed', `${field} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw adapterError('package_load_failed', `${field} fields are invalid`);
+  }
+}
+
+function safeArtifactPath(root, value, field) {
+  if (typeof value !== 'string' || value === '' || value.includes('\0')) {
+    throw adapterError('package_load_failed', `${field} must be a package-relative path`);
+  }
+  const normalized = value.replaceAll('\\', '/');
+  if (
+    path.posix.isAbsolute(normalized) ||
+    /^[A-Za-z]:/.test(normalized) ||
+    normalized.split('/').some((part) => part === '..' || part === '' || part === '.')
+  ) {
+    throw adapterError('package_load_failed', `${field} escapes the native package`, value);
+  }
+  const resolved = path.resolve(root, ...normalized.split('/'));
+  const relative = path.relative(path.resolve(root), resolved);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw adapterError('package_load_failed', `${field} escapes the native package`, value);
+  }
+  return resolved;
+}
 
-  const packageName = platformPackage();
+function sha256(filename) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filename)).digest('hex');
+}
+
+function verifyArtifact(root, artifact, field) {
+  exactKeys(artifact, ['path', 'bytes', 'sha256'], field);
+  const filename = safeArtifactPath(root, artifact.path, `${field}.path`);
+  let stats;
   try {
-    return require(packageName);
+    stats = fs.lstatSync(filename);
   } catch (cause) {
+    throw adapterError('package_load_failed', 'Descriptor artifact is missing', artifact.path, cause);
+  }
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw adapterError('package_load_failed', 'Descriptor artifact is not a regular file', artifact.path);
+  }
+  if (!Number.isSafeInteger(artifact.bytes) || artifact.bytes < 1 || stats.size !== artifact.bytes) {
+    throw adapterError('package_load_failed', 'Descriptor artifact byte count mismatch', artifact.path);
+  }
+  if (!/^[a-f0-9]{64}$/.test(artifact.sha256 || '') || sha256(filename) !== artifact.sha256) {
+    throw adapterError('package_load_failed', 'Descriptor artifact hash mismatch', artifact.path);
+  }
+  return filename;
+}
+
+function sameArtifact(left, right) {
+  return left?.path === right?.path && left?.bytes === right?.bytes &&
+    left?.sha256 === right?.sha256;
+}
+
+function validateRuntimeDescriptor(descriptorPath) {
+  const absoluteDescriptor = path.resolve(descriptorPath);
+  const nativeDirectory = path.dirname(absoluteDescriptor);
+  if (
+    path.basename(absoluteDescriptor) !== 'runtime-descriptor.json' ||
+    path.basename(nativeDirectory) !== 'native'
+  ) {
     throw adapterError(
       'package_load_failed',
-      `Unable to load ${packageName}`,
-      'Reinstall @arcships/light-ocr without --omit=optional and verify that the ' +
-        'current platform is supported.',
+      'Native runtime descriptor must use the package native/runtime-descriptor.json path',
+      absoluteDescriptor,
+    );
+  }
+  let descriptor;
+  try {
+    const nativeStats = fs.lstatSync(nativeDirectory);
+    if (!nativeStats.isDirectory() || nativeStats.isSymbolicLink()) {
+      throw new Error('native payload root is not a regular directory');
+    }
+    const stats = fs.lstatSync(absoluteDescriptor);
+    if (!stats.isFile() || stats.isSymbolicLink()) throw new Error('not a regular file');
+    descriptor = JSON.parse(fs.readFileSync(absoluteDescriptor, 'utf8'));
+  } catch (cause) {
+    throw adapterError(
+      'package_load_failed',
+      'Unable to read the native runtime descriptor',
+      absoluteDescriptor,
       cause,
     );
   }
+  exactKeys(
+    descriptor,
+    ['schemaVersion', 'platform', 'runtime', 'qualificationOnly', 'released',
+      'autoPolicy', 'providers', 'addon'],
+    'runtime descriptor',
+  );
+  if (descriptor.schemaVersion !== '2.0') {
+    throw adapterError('package_load_failed', 'Unsupported native runtime descriptor schema');
+  }
+  const root = path.dirname(path.dirname(absoluteDescriptor));
+  const expected = platformIdentity();
+  const expectedPlatformKeys = expected.libc
+    ? ['id', 'os', 'architecture', 'libc']
+    : ['id', 'os', 'architecture'];
+  exactKeys(descriptor.platform, expectedPlatformKeys, 'platform');
+  const actual = descriptor.platform;
+  if (
+    actual.id !== expected.id ||
+    actual.os !== expected.os ||
+    actual.architecture !== expected.architecture ||
+    (expected.libc && actual.libc !== expected.libc)
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor platform mismatch');
+  }
+  if (
+    typeof descriptor.released !== 'boolean' ||
+    typeof descriptor.qualificationOnly !== 'boolean' ||
+    descriptor.qualificationOnly === descriptor.released
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor release flags are invalid');
+  }
+
+  exactKeys(descriptor.autoPolicy, ['id', 'version', 'providers'], 'autoPolicy');
+  const policy = descriptor.autoPolicy;
+  if (
+    typeof policy.id !== 'string' || policy.id === '' ||
+    !Number.isSafeInteger(policy.version) || policy.version < 1 || policy.version > 0xffffffff ||
+    !Array.isArray(policy.providers) || policy.providers.length === 0 ||
+    policy.providers.length > 3 || policy.providers.at(-1) !== 'cpu' ||
+    new Set(policy.providers).size !== policy.providers.length
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor Auto policy is invalid');
+  }
+
+  exactKeys(descriptor.runtime, ['flavor', 'kind', 'version', 'abi', 'artifacts'], 'runtime');
+  const runtime = descriptor.runtime;
+  const expectedRuntimes = {
+    cpu: { kind: 'onnxruntime-cpu', version: '1.22.0', abi: 'onnxruntime-c-api-22' },
+    webgpu: {
+      kind: 'onnxruntime-plugin-webgpu',
+      version: '1.24.4',
+      abi: 'onnxruntime-c-api-24-plugin-ep-0.1',
+    },
+  };
+  const expectedRuntime = expectedRuntimes[runtime.flavor];
+  if (
+    !expectedRuntime || runtime.kind !== expectedRuntime.kind ||
+    runtime.version !== expectedRuntime.version || runtime.abi !== expectedRuntime.abi ||
+    !Array.isArray(runtime.artifacts) || runtime.artifacts.length === 0
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor ABI identity is invalid');
+  }
+  if (runtime.flavor === 'webgpu' && !['linux', 'win32'].includes(actual.os)) {
+    throw adapterError('package_load_failed', 'WebGPU runtime is not supported on this platform');
+  }
+  if (runtime.flavor !== 'webgpu' && descriptor.qualificationOnly) {
+    throw adapterError('package_load_failed', 'CPU runtime cannot be qualification-only');
+  }
+
+  const addon = verifyArtifact(root, descriptor.addon, 'addon');
+  const runtimePaths = new Set();
+  const verifiedRuntime = new Map();
+  runtime.artifacts.forEach((artifact, index) => {
+    const filename = verifyArtifact(root, artifact, `runtime.artifacts[${index}]`);
+    if (runtimePaths.has(artifact.path)) {
+      throw adapterError('package_load_failed', 'Runtime artifact inventory contains a duplicate path');
+    }
+    runtimePaths.add(artifact.path);
+    verifiedRuntime.set(artifact.path, filename);
+  });
+
+  exactKeys(descriptor.providers, Object.keys(descriptor.providers), 'providers');
+  const availableProviders = Object.keys(descriptor.providers);
+  if (
+    availableProviders.length === 0 ||
+    new Set(availableProviders).size !== availableProviders.length ||
+    availableProviders.some((provider) => !['cpu', 'apple', 'webgpu'].includes(provider)) ||
+    !descriptor.providers.cpu
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor provider policy is invalid');
+  }
+  let webgpuLibrary = '';
+  let webgpuProviderBytes = 0;
+  let webgpuProviderSha256 = '';
+  for (const [providerId, provider] of Object.entries(descriptor.providers)) {
+    const expectedKeys = providerId === 'webgpu'
+      ? ['runtimeProvider', 'providerVersion', 'qualificationId', 'providerLibrary', 'artifacts']
+      : ['runtimeProvider', 'qualificationId', 'artifacts'];
+    exactKeys(provider, expectedKeys, `providers.${providerId}`);
+    if (
+      typeof provider.qualificationId !== 'string' || provider.qualificationId === '' ||
+      !Array.isArray(provider.artifacts) || provider.artifacts.length === 0
+    ) {
+      throw adapterError('package_load_failed', `Provider ${providerId} identity is invalid`);
+    }
+    const expectedProviderName = {
+      cpu: 'CPUExecutionProvider',
+      apple: 'CoreML',
+      webgpu: 'WebGpuExecutionProvider',
+    }[providerId];
+    if (provider.runtimeProvider !== expectedProviderName) {
+      throw adapterError('package_load_failed', `Provider ${providerId} runtime identity is invalid`);
+    }
+    const providerPaths = new Set();
+    provider.artifacts.forEach((artifact, index) => {
+      verifyArtifact(root, artifact, `providers.${providerId}.artifacts[${index}]`);
+      if (providerPaths.has(artifact.path)) {
+        throw adapterError('package_load_failed', `Provider ${providerId} has duplicate artifacts`);
+      }
+      providerPaths.add(artifact.path);
+      if (providerId !== 'apple' && !runtimePaths.has(artifact.path)) {
+        throw adapterError('package_load_failed', `Provider ${providerId} artifact is outside runtime inventory`);
+      }
+      if (providerId === 'apple' && artifact.path !== descriptor.addon.path) {
+        throw adapterError('package_load_failed', 'Apple provider artifact must be the native addon');
+      }
+    });
+    if (providerId === 'webgpu') {
+      if (provider.providerVersion !== '0.1.0') {
+        throw adapterError('package_load_failed', 'WebGPU provider version is invalid');
+      }
+      webgpuLibrary = verifyArtifact(root, provider.providerLibrary, 'providers.webgpu.providerLibrary');
+      const declared = provider.artifacts.find(
+        (artifact) => artifact.path === provider.providerLibrary.path,
+      );
+      const expectedBasename = actual.os === 'win32'
+        ? 'onnxruntime_providers_webgpu.dll'
+        : 'libonnxruntime_providers_webgpu.so';
+      if (
+        !declared || !sameArtifact(declared, provider.providerLibrary) ||
+        path.basename(webgpuLibrary) !== expectedBasename
+      ) {
+        throw adapterError('package_load_failed', 'WebGPU provider library contract is invalid');
+      }
+      webgpuProviderBytes = provider.providerLibrary.bytes;
+      webgpuProviderSha256 = provider.providerLibrary.sha256;
+    }
+  }
+
+  const coreName = actual.os === 'win32'
+    ? 'onnxruntime.dll'
+    : actual.os === 'darwin'
+      ? 'libonnxruntime.1.22.0.dylib'
+      : 'libonnxruntime.so.1';
+  const runtimeNames = [...verifiedRuntime.values()].map((filename) => path.basename(filename)).sort();
+  const expectedRuntimeNames = runtime.flavor === 'webgpu'
+    ? actual.os === 'win32'
+      ? ['dxcompiler.dll', 'dxil.dll', 'onnxruntime.dll', 'onnxruntime_providers_webgpu.dll']
+      : ['libonnxruntime.so.1', 'libonnxruntime_providers_webgpu.so']
+    : [coreName];
+  if (
+    runtimeNames.length !== expectedRuntimeNames.length ||
+    runtimeNames.some((name, index) => name !== expectedRuntimeNames[index])
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime artifact set is incomplete');
+  }
+  const cpuArtifacts = descriptor.providers.cpu.artifacts;
+  if (
+    cpuArtifacts.length !== 1 ||
+    path.basename(safeArtifactPath(root, cpuArtifacts[0].path, 'CPU artifact path')) !== coreName
+  ) {
+    throw adapterError('package_load_failed', 'CPU provider does not reference the core runtime');
+  }
+
+  const actualPayload = new Set();
+  const inventory = (directory, relativeDirectory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const relative = `${relativeDirectory}/${entry.name}`;
+      const filename = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw adapterError('package_load_failed', 'Native runtime payload contains a symlink', relative);
+      }
+      if (entry.isDirectory()) {
+        inventory(filename, relative);
+      } else if (entry.isFile() && relative !== 'native/runtime-descriptor.json') {
+        actualPayload.add(relative);
+      } else if (!entry.isFile()) {
+        throw adapterError('package_load_failed', 'Native runtime payload is not a regular file', relative);
+      }
+    }
+  };
+  inventory(nativeDirectory, 'native');
+  const referenced = new Set([descriptor.addon.path, ...runtimePaths]);
+  if (
+    actualPayload.size !== referenced.size ||
+    [...actualPayload].some((filename) => !referenced.has(filename))
+  ) {
+    throw adapterError('package_load_failed', 'Native runtime descriptor payload inventory mismatch');
+  }
+
+  const expectedPolicy = runtime.flavor === 'webgpu'
+    ? ['webgpu', 'cpu']
+    : actual.id === 'macos-arm64'
+      ? ['apple', 'cpu']
+      : ['cpu'];
+  const expectedAvailable = runtime.flavor === 'webgpu'
+    ? ['cpu', 'webgpu']
+    : actual.id === 'macos-arm64'
+      ? ['apple', 'cpu']
+      : ['cpu'];
+  const sortedAvailable = [...availableProviders].sort();
+  if (
+    policy.providers.length !== expectedPolicy.length ||
+    policy.providers.some((provider, index) => provider !== expectedPolicy[index]) ||
+    sortedAvailable.length !== expectedAvailable.length ||
+    sortedAvailable.some((provider, index) => provider !== expectedAvailable[index]) ||
+    policy.providers.some((provider) => !availableProviders.includes(provider))
+  ) {
+    throw adapterError(
+      'package_load_failed',
+      'Native runtime descriptor providers disagree with platform capabilities',
+    );
+  }
+  const providerQualificationIds = sortedAvailable.map(
+    (providerId) => descriptor.providers[providerId].qualificationId,
+  );
+  const runtimePolicy = Object.freeze({
+    id: policy.id,
+    version: policy.version,
+    platformId: actual.id,
+    runtimeFlavor: runtime.flavor,
+    runtimeVersion: runtime.version,
+    runtimeAbi: runtime.abi,
+    qualificationOnly: descriptor.qualificationOnly,
+    released: descriptor.released,
+    orderedCandidates: Object.freeze([...policy.providers]),
+    availableProviders: Object.freeze(sortedAvailable),
+    providerQualificationIds: Object.freeze(providerQualificationIds),
+    webgpuProviderLibrary: webgpuLibrary,
+    webgpuProviderBytes,
+    webgpuProviderSha256,
+  });
+  return {
+    addon,
+    descriptor: Object.freeze(descriptor),
+    descriptorPath: absoluteDescriptor,
+    runtimePolicy,
+  };
+}
+
+function resolveDevelopmentInput() {
+  if (!process.env.LIGHT_OCR_NODE_BINARY) return undefined;
+  const binary = path.resolve(process.env.LIGHT_OCR_NODE_BINARY);
+  const descriptor = process.env.LIGHT_OCR_RUNTIME_DESCRIPTOR
+    ? path.resolve(process.env.LIGHT_OCR_RUNTIME_DESCRIPTOR)
+    : path.join(path.dirname(binary), 'runtime-descriptor.json');
+  return { binary, descriptor };
+}
+
+function validateNativeContract(binding, runtimePolicy) {
+  const contract = binding?.runtimeContract;
+  const fields = [
+    'policyId',
+    'policyVersion',
+    'platformId',
+    'runtimeFlavor',
+    'runtimeVersion',
+    'runtimeAbi',
+    'qualificationOnly',
+    'released',
+  ];
+  const policyFields = {
+    policyId: runtimePolicy.id,
+    policyVersion: runtimePolicy.version,
+    platformId: runtimePolicy.platformId,
+    runtimeFlavor: runtimePolicy.runtimeFlavor,
+    runtimeVersion: runtimePolicy.runtimeVersion,
+    runtimeAbi: runtimePolicy.runtimeAbi,
+    qualificationOnly: runtimePolicy.qualificationOnly,
+    released: runtimePolicy.released,
+  };
+  if (
+    !contract ||
+    typeof contract !== 'object' ||
+    fields.some((field) => contract[field] !== policyFields[field]) ||
+    !Array.isArray(contract.orderedCandidates) ||
+    !Array.isArray(contract.availableProviders) ||
+    !Array.isArray(contract.providerQualificationIds) ||
+    contract.orderedCandidates.length !== runtimePolicy.orderedCandidates.length ||
+    contract.orderedCandidates.some(
+      (provider, index) => provider !== runtimePolicy.orderedCandidates[index],
+    ) ||
+    contract.availableProviders.length !== runtimePolicy.availableProviders.length ||
+    contract.availableProviders.some(
+      (provider, index) => provider !== runtimePolicy.availableProviders[index],
+    ) ||
+    contract.providerQualificationIds.length !== runtimePolicy.providerQualificationIds.length ||
+    contract.providerQualificationIds.some(
+      (qualificationId, index) => qualificationId !== runtimePolicy.providerQualificationIds[index],
+    )
+  ) {
+    throw adapterError(
+      'package_load_failed',
+      'Runtime descriptor is incompatible with the native addon ABI or capabilities',
+    );
+  }
+}
+
+function loadNative() {
+  const development = resolveDevelopmentInput();
+  let input;
+  if (development) {
+    input = development;
+  } else {
+    const packageName = platformPackage();
+    try {
+      const binary = require.resolve(packageName);
+      input = { binary, descriptor: path.join(path.dirname(binary), 'runtime-descriptor.json') };
+    } catch (cause) {
+      throw adapterError(
+        'package_load_failed',
+        `Unable to locate ${packageName}`,
+        'Reinstall @arcships/light-ocr without --omit=optional and verify that the current platform is supported.',
+        cause,
+      );
+    }
+  }
+
+  if (!fs.existsSync(input.binary)) {
+    throw adapterError('package_load_failed', 'Native addon is missing', input.binary);
+  }
+  const verified = validateRuntimeDescriptor(input.descriptor);
+  if (path.resolve(input.binary) !== path.resolve(verified.addon)) {
+    throw adapterError('package_load_failed', 'Runtime descriptor addon path mismatch', input.binary);
+  }
+  try {
+    const binding = require(verified.addon);
+    validateNativeContract(binding, verified.runtimePolicy);
+    return Object.freeze({ binding, runtimePolicy: verified.runtimePolicy });
+  } catch (cause) {
+    throw adapterError('package_load_failed', 'Unable to load the verified native addon', '', cause);
+  }
 }
 
-module.exports = { loadNative };
+module.exports = { loadNative, validateRuntimeDescriptor };

package/package.json

@@ -3,7 +3,7 @@
     "url": "https://github.com/arcships/light-ocr/issues"
   },
   "dependencies": {
-    "@arcships/light-ocr-model-ppocrv6-small": "0.2.0"
+    "@arcships/light-ocr-model-ppocrv6-small": "0.3.2"
   },
   "description": "Offline PP-OCRv6 OCR for Node.js, powered by an embeddable C++ core",
   "engines": {
@@ -36,10 +36,12 @@
   "module": "./js/index.mjs",
   "name": "@arcships/light-ocr",
   "optionalDependencies": {
-    "@arcships/light-ocr-darwin-arm64": "0.2.0",
-    "@arcships/light-ocr-darwin-x64": "0.2.0",
-    "@arcships/light-ocr-linux-x64-gnu": "0.2.0",
-    "@arcships/light-ocr-win32-x64": "0.2.0"
+    "@arcships/light-ocr-darwin-arm64": "0.3.2",
+    "@arcships/light-ocr-darwin-x64": "0.3.2",
+    "@arcships/light-ocr-linux-arm64-gnu": "0.3.2",
+    "@arcships/light-ocr-linux-x64-gnu": "0.3.2",
+    "@arcships/light-ocr-win32-arm64": "0.3.2",
+    "@arcships/light-ocr-win32-x64": "0.3.2"
   },
   "publishConfig": {
     "access": "public",
@@ -51,5 +53,5 @@
   },
   "type": "commonjs",
   "types": "./js/index.d.ts",
-  "version": "0.2.0"
+  "version": "0.3.2"
 }