@rosepetal/barcode-engine-client 0.2.0

package/lib/format.js

@@ -0,0 +1,22 @@
+'use strict';
+/**
+ * The `format` name of a schema-1.0 symbol, as node-red-contrib-barcode-reader has always printed it
+ * (compat/barcode-reader.md §3 of rosepetal-barcode-sdk): ZXing's spelling for the symbologies; the add-ons, which
+ * ZXing does not report on their own, take ZBar's (EAN-2 / EAN-5). Shared here so that the reader and the verifier
+ * print the same `format` for the same symbol.
+ */
+
+// symbology (schema 1.0 identifier) → the name the nodes print
+const FORMAT_NAMES = {
+    EAN13: 'EAN-13', EAN8: 'EAN-8', UPCA: 'UPC-A', UPCE: 'UPC-E',
+    Code128: 'Code128', Code39: 'Code39', Code93: 'Code93', Codabar: 'Codabar', ITF: 'ITF'
+};
+// The identifier is read before the symbology: an add-on carries its main's symbology
+const ADDON_NAMES = { ']E1': 'EAN-2', ']E2': 'EAN-5' };
+
+/** The `format` the nodes print for a schema-1.0 symbol; an unknown symbology keeps the SDK's name. */
+function formatName(symbol) {
+    return ADDON_NAMES[symbol.identifier] || FORMAT_NAMES[symbol.symbology] || String(symbol.symbology);
+}
+
+module.exports = { FORMAT_NAMES, ADDON_NAMES, formatName };

package/lib/framing.js

@@ -0,0 +1,174 @@
+'use strict';
+/**
+ * Frame codec of the `rp-barcode serve` protocol, version 1 (docs/service.md §3.1 of rosepetal-barcode-sdk, the
+ * repository this package lives in; the plan: docs/plans/fase2/00-overview.md §3.1). Shared by every client of
+ * the engine (@rosepetal/barcode-engine-client) and by the fake engine of test/fake-engine.js:
+ *
+ *   u32 big-endian headerLen | u32 big-endian payloadLen | header (headerLen bytes, UTF-8 JSON object) | payload
+ *
+ * headerLen is >= 2 and <= maxHeader (1 MiB by default), payloadLen <= maxPayload (256 MiB by default) and the
+ * header must be a JSON object. Anything else is a protocol violation: the parser emits one FramingError and
+ * ignores every later chunk, because the byte stream can no longer be delimited (the caller restarts the process).
+ *
+ * The parser copies every byte exactly once, into a buffer sized from the prefix, so a payload never lives twice
+ * in memory and the emitted Buffer is independent of the chunks pushed in.
+ */
+const { EventEmitter } = require('node:events');
+
+const PREFIX_BYTES = 8;
+const MIN_HEADER = 2;                    // "{}"
+const MAX_U32 = 0xffffffff;
+const DEFAULT_MAX_HEADER = 1 << 20;      // 1 MiB
+const DEFAULT_MAX_PAYLOAD = 256 << 20;   // 256 MiB
+const EMPTY = Buffer.alloc(0);
+
+class FramingError extends Error {
+    /**
+     * @param {'bad_frame'|'bad_header'|'bad_payload'} code
+     * @param {string} message
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'FramingError';
+        this.code = code;
+    }
+}
+
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Encodes one frame as [head, payload]: head is the 8-byte prefix followed by the UTF-8 JSON header and payload
+ * is the caller's buffer untouched, so the two go out in two writes and the pixels are never copied.
+ *
+ * @param {object} header a JSON object (control characters such as GS 0x1D survive as \u001d escapes)
+ * @param {Buffer|Uint8Array} [payload] optional (payloadLen 0)
+ * @returns {[Buffer, Buffer|Uint8Array]}
+ */
+function encodeFrame(header, payload = EMPTY) {
+    if (!isJsonObject(header)) {
+        throw new FramingError('bad_header', 'header must be a JSON object');
+    }
+    if (!(payload instanceof Uint8Array)) {          // a Buffer is a Uint8Array
+        throw new FramingError('bad_payload', 'payload must be a Buffer or Uint8Array');
+    }
+    if (payload.length > MAX_U32) {
+        throw new FramingError('bad_payload', `payload length ${payload.length} does not fit in u32`);
+    }
+    const json = Buffer.from(JSON.stringify(header), 'utf8');
+    if (json.length > MAX_U32) {
+        throw new FramingError('bad_header', `header length ${json.length} does not fit in u32`);
+    }
+    const head = Buffer.allocUnsafe(PREFIX_BYTES + json.length);
+    head.writeUInt32BE(json.length, 0);
+    head.writeUInt32BE(payload.length, 4);
+    json.copy(head, PREFIX_BYTES);
+    return [head, payload];
+}
+
+/**
+ * Incremental parser over arbitrary chunks (any split, one byte at a time or several frames at once).
+ *
+ * Events:
+ *   'frame' (header: object, payload: Buffer)   payload is an empty Buffer when payloadLen is 0
+ *   'error' (FramingError)                       emitted once; afterwards push() is a no-op and `failed` holds the error
+ */
+class FrameParser extends EventEmitter {
+    constructor({ maxHeader = DEFAULT_MAX_HEADER, maxPayload = DEFAULT_MAX_PAYLOAD } = {}) {
+        super();
+        this.maxHeader = maxHeader;
+        this.maxPayload = maxPayload;
+        this.failed = null;
+        this.headerLen = 0;
+        this.payloadLen = 0;
+        this.header = null;
+        this.prefix = Buffer.alloc(PREFIX_BYTES);
+        this._expect('prefix', this.prefix);
+    }
+
+    /** @param {Buffer|Uint8Array} chunk */
+    push(chunk) {
+        if (this.failed) return;
+        if (!(chunk instanceof Uint8Array)) {
+            throw new TypeError('FrameParser.push expects a Buffer or Uint8Array');
+        }
+        let offset = 0;
+        while (offset < chunk.length) {
+            const n = Math.min(this.target.length - this.filled, chunk.length - offset);
+            this.target.set(chunk.subarray(offset, offset + n), this.filled);
+            this.filled += n;
+            offset += n;
+            if (this.filled === this.target.length && !this._complete()) return;
+        }
+    }
+
+    _expect(state, target) {
+        this.state = state;
+        this.target = target;
+        this.filled = 0;
+    }
+
+    /** The current target is full: validate it and move to the next state. Returns false once the parser is dead. */
+    _complete() {
+        switch (this.state) {
+            case 'prefix': {
+                this.headerLen = this.prefix.readUInt32BE(0);
+                this.payloadLen = this.prefix.readUInt32BE(4);
+                if (this.headerLen < MIN_HEADER || this.headerLen > this.maxHeader) {
+                    return this._fail('bad_frame', `header length ${this.headerLen} outside ${MIN_HEADER}..${this.maxHeader}`);
+                }
+                if (this.payloadLen > this.maxPayload) {
+                    return this._fail('bad_frame', `payload length ${this.payloadLen} exceeds ${this.maxPayload}`);
+                }
+                this._expect('header', Buffer.allocUnsafe(this.headerLen));
+                return true;
+            }
+            case 'header': {
+                let header;
+                try {
+                    header = JSON.parse(this.target.toString('utf8'));
+                } catch (err) {
+                    return this._fail('bad_header', `header is not JSON: ${err.message}`);
+                }
+                if (!isJsonObject(header)) {
+                    return this._fail('bad_header', 'header is not a JSON object');
+                }
+                this.header = header;
+                if (this.payloadLen === 0) return this._emitFrame(EMPTY);
+                this._expect('payload', Buffer.allocUnsafe(this.payloadLen));
+                return true;
+            }
+            case 'payload':
+                return this._emitFrame(this.target);
+            default:
+                return this._fail('bad_frame', `unexpected parser state ${this.state}`);
+        }
+    }
+
+    _emitFrame(payload) {
+        const header = this.header;
+        this.header = null;
+        this._expect('prefix', this.prefix);     // consistent state before listeners run
+        this.emit('frame', header, payload);
+        return !this.failed;
+    }
+
+    _fail(code, message) {
+        this.failed = new FramingError(code, message);
+        this.header = null;
+        this._expect('dead', EMPTY);
+        this.emit('error', this.failed);
+        return false;
+    }
+}
+
+module.exports = {
+    encodeFrame,
+    FrameParser,
+    FramingError,
+    PREFIX_BYTES,
+    MIN_HEADER,
+    DEFAULT_MAX_HEADER,
+    DEFAULT_MAX_PAYLOAD
+};

package/lib/index.js

@@ -0,0 +1,18 @@
+'use strict';
+/**
+ * @rosepetal/barcode-engine-client: the Node client of `rp-barcode serve`, the persistent decode service of
+ * rosepetal-barcode-sdk. One module, one shared engine: every package that requires this one and calls acquire()
+ * shares the same rp-barcode process of the Node-RED runtime (node-red-contrib-barcode-reader and
+ * node-red-contrib-barcode-verifier). See README.md.
+ */
+const engine = require('./engine');
+const framing = require('./framing');
+const format = require('./format');
+
+// The fake `rp-barcode serve` of this package's tests (protocol 1, one fixed EAN-13 per decode, the canned
+// VerifyResults of test/fixtures/*.json for verify/analyze, knobs through FAKE_* environment variables), shipped so
+// that the tests of the nodes can point RP_BARCODE_ENGINE, or an Engine's `command`/`args`, at it instead of a
+// real binary
+const FAKE_ENGINE = require.resolve('../test/fake-engine.js');
+
+module.exports = { ...engine, ...framing, ...format, FAKE_ENGINE };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@rosepetal/barcode-engine-client",
+  "version": "0.2.0",
+  "description": "Node client of rp-barcode serve, the persistent decode and verify service of rosepetal-barcode-sdk: one shared engine process per Node-RED runtime, framed requests over stdio, timeouts, bounded queue, restart with backoff",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rosepetal-ai/rosepetal-barcode-sdk.git",
+    "directory": "clients/node"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "lib/",
+    "test/fake-engine.js",
+    "test/fixtures/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "optionalDependencies": {
+    "@rosepetal/barcode-engine-linux-x64": "0.2.0",
+    "@rosepetal/barcode-engine-linux-arm64": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/test/fake-engine.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Fake `rp-barcode serve` for the tests: protocol 1 over stdio (rosepetal-barcode-sdk docs/service.md; the plan:
+ * docs/plans/fase2/00-overview.md §3, 04-subfase-2D.md §3.5), one fixed EAN-13 per decode, canned VerifyResults
+ * for verify/analyze (test/fixtures/*.json: what the CLI printed for the synthetic renders of
+ * test/tools/make-verify-fixtures.sh), knobs through environment variables (tasks 2B-T2 and 2D-T2). Executable with
+ * a shebang so it also works as RP_BARCODE_ENGINE (the client spawns `<path> serve`). Never matched by `npm test`
+ * (`test/*.test.js`).
+ *
+ * Knobs (environment of the child):
+ *   FAKE_DELAY_MS=n          every decode/verify/analyze answers after n ms
+ *   FAKE_CRASH_AFTER=n       exits with status 7 on receiving decode/verify/analyze n+1, without answering it
+ *   FAKE_PROTOCOL=n          the `protocol` number of the hello (default 1)
+ *   FAKE_GARBAGE=1           writes text outside any frame right after the hello
+ *   FAKE_OVERLOAD=1          answers `overloaded` to every decode/verify/analyze
+ *   FAKE_NO_HELLO=1          never greets, never answers, ignores SIGTERM (the client has to SIGKILL)
+ *   FAKE_IGNORE_STOP=1       works but ignores `shutdown` and SIGTERM
+ *   FAKE_MAX_PAYLOAD=n       the `limits.maxPayload` advertised in the hello (default 256 MiB, like `--max-payload`)
+ *   FAKE_REPLY_PAYLOAD=1     attaches a payload to every decode/verify/analyze reply (a protocol violation seen from
+ *                            the client)
+ *   FAKE_STALL=1             greets, then never reads stdin (the client's writes pile up); with FAKE_IGNORE_STOP the
+ *                            client has to SIGKILL it
+ *   FAKE_VERIFY_STATUS=s     the canned result of verify/analyze: pass (default), fail or not_detected
+ *   FAKE_DECODE_SYMBOLS=n    copies of the fixed EAN-13 a decode answers (default 1; 0 = no symbol)
+ *   FAKE_OPS=a,b,c           the ops the hello announces (default decode,ping,shutdown,verify,analyze); an op left
+ *                            out is answered `unsupported`, as by a 2A engine (an SDK 0.2.0 built before 2D)
+ *
+ * Like the real server it takes `image.encoding` `raw` (payload.length === width·height·channels) or `encoded` (a
+ * non-empty PNG, JPEG, BMP or TIFF file, told by its magic bytes; the size answered is the PNG's IHDR, else the
+ * header's width/height, where the real server reports the decoded size; with no size at all, 0×0, the bounds
+ * check is skipped, where the real server checks against the decoded size), rejects unknown keys inside `image`,
+ * `region`, `options` (`spec` included) and `acquisition` (`calibration` included) with `invalid_input` and the
+ * server's own wording (`json: unknown field "x"`; `plain.x` for a region value that is not an integer, as its
+ * encoding/json names the field), a region under 2 px, an orientation that is not a multiple of 90, a region
+ * outside the image (`barcode: region {…} outside image WxH`), and a `deadlineMs` that is not an integer.
+ * verify/analyze answer the canned result of FAKE_VERIFY_STATUS with the request's region echoed in
+ * `result.symbol.region` (orientation normalised to 0/90/180/270); `analyze` answers analyze-pass.json under
+ * `pass` and the verify fixture plus `scans: []` otherwise (the real Analyze returns the scans it measured even
+ * when nothing decodes).
+ *
+ * Known simplifications: `shutdown` and EOF on stdin exit at once, without answering the requests still delayed
+ * by FAKE_DELAY_MS (the real server finishes what is in flight first, §3.1/§3.2); keys are matched
+ * case-sensitively (`TryInvert` is an unknown key here, the real server's encoding/json takes it for `tryInvert`);
+ * the raw length message reads `imgio: data length N does not match W×H×C` (the server's: `imgio: GRAY WxH needs
+ * N bytes, got M`); option values are not checked against their vocabularies (`edition: "2020"` or a GS1 table
+ * `42` pass here and are `invalid_input` on the server); `options`, `spec`, `acquisition` and `calibration` that
+ * are not objects pass here (the server: `cannot unmarshal string into Go value of type barcode.VerifyOptions`).
+ * Logs go to stderr, one line per event.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { FrameParser, encodeFrame } = require('../lib/framing');
+
+const env = process.env;
+const delayMs = Number(env.FAKE_DELAY_MS || 0);
+const crashAfter = env.FAKE_CRASH_AFTER === undefined ? -1 : Number(env.FAKE_CRASH_AFTER);
+const protocol = env.FAKE_PROTOCOL === undefined ? 1 : Number(env.FAKE_PROTOCOL);
+const garbage = env.FAKE_GARBAGE === '1';
+const overload = env.FAKE_OVERLOAD === '1';
+const noHello = env.FAKE_NO_HELLO === '1';
+const ignoreStop = env.FAKE_IGNORE_STOP === '1';
+const maxPayload = env.FAKE_MAX_PAYLOAD === undefined ? 268435456 : Number(env.FAKE_MAX_PAYLOAD);
+const replyPayload = env.FAKE_REPLY_PAYLOAD === '1';
+const stall = env.FAKE_STALL === '1';
+const verifyStatus = env.FAKE_VERIFY_STATUS || 'pass';
+const decodeSymbols = env.FAKE_DECODE_SYMBOLS === undefined ? 1 : Number(env.FAKE_DECODE_SYMBOLS);
+const ops = env.FAKE_OPS ? env.FAKE_OPS.split(',') : ['decode', 'ping', 'shutdown', 'verify', 'analyze'];
+
+// The key sets the server accepts (DisallowUnknownFields on the SDK's structs): anything else is invalid_input.
+// image: docs/service.md §3.2; decodeOptions: docs/schema/result-1.0.md §12.1; verifyOptions §12.2 (its spec
+// {kind, table}); acquisition §12.3 and its calibration §12.4; region: docs/service.md §3.5
+const KNOWN_IMAGE = new Set(['width', 'height', 'channels', 'colorSpace', 'encoding']);
+const KNOWN_DECODE_OPTIONS = new Set(['symbologies', 'region', 'scanStep', 'horizontal', 'vertical', 'quietZone', 'optionalChecksum',
+    'minLines', 'tryInvert', 'maxSymbols', 'addOn', 'effort', 'upcaAsEan13', 'code39FullAscii']);
+const KNOWN_VERIFY_OPTIONS = new Set(['symbology', 'edition', 'scanCount', 'topMargin', 'bottomMargin', 'spec', 'failUnder', 'warnUnder',
+    'readOnly', 'heightErrors', 'xDimErrors', 'structureErrors', 'enforceAssociations', 'quietZoneRule', 'parameterSummary', 'apertureMils',
+    'noDenseScans']);
+const KNOWN_SPEC = new Set(['kind', 'table']);
+const KNOWN_ACQUISITION = new Set(['milsPerPixel', 'wavelengthNm', 'calibration']);
+const KNOWN_CALIBRATION = new Set(['mode', 'black', 'white', 'cardRmax', 'cardContrast']);
+const KNOWN_REGION = new Set(['x', 'y', 'w', 'h', 'orientation']);
+
+// The canned results: what rp-barcode verify/analyze print for the synthetic renders of test/tools/make-verify-fixtures.sh
+// (verify-pass, verify-fail, verify-not-detected, analyze-pass), read afresh per request so a reply never shares state
+const FIXTURES = path.join(__dirname, 'fixtures');
+const canned = (name) => JSON.parse(fs.readFileSync(path.join(FIXTURES, `${name}.json`), 'utf8'));
+
+// The symbol rp-barcode decode reads from test/fixtures/ean13.png of the reader (347×68, X = 3 px, bars 60 px high);
+// region is what `rp-barcode decode --robust` reports for it
+const SYMBOL = {
+    symbology: 'EAN13', identifier: ']E0', value: '4006381333931', bytes: 'NDAwNjM4MTMzMzkzMQ==', gs1: true,
+    corners: [{ x: 37, y: 4 }, { x: 322, y: 4 }, { x: 322, y: 64 }, { x: 37, y: 64 }],
+    orientation: 0, confidence: 1, lines: 40, checksum: 'valid', region: { x: 1, y: 0, w: 346, h: 68, orientation: 0 }
+};
+
+function log(line) {
+    process.stderr.write(`fake-engine: ${line}\n`);
+}
+function write(header, payload, onDone) {
+    const [head, body] = encodeFrame(header, payload);
+    if (body.length === 0) return process.stdout.write(head, onDone);
+    process.stdout.write(head);
+    process.stdout.write(body, onDone);
+}
+function fail(id, code, message) {
+    write({ id, ok: false, error: { code, message } });
+}
+// A successful reply, after FAKE_DELAY_MS, with a payload under FAKE_REPLY_PAYLOAD
+function reply(id, body) {
+    setTimeout(() => write({ id, ok: true, ...body }, replyPayload ? Buffer.from([1, 2, 3, 4]) : undefined), delayMs);
+}
+
+// What a JSON value is called in encoding/json's "cannot unmarshal … into" messages
+function jsonKind(value) {
+    if (typeof value === 'number') return `number ${value}`;
+    if (typeof value === 'boolean') return 'bool';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+}
+// The first key of obj outside known, as the server's decoder (DisallowUnknownFields) names it; null when all are
+// known or obj is not an object
+function unknownField(obj, known) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+    for (const key of Object.keys(obj)) {
+        if (!known.has(key)) return `json: unknown field ${JSON.stringify(key)}`;
+    }
+    return null;
+}
+
+// The format of an encoded payload by its magic bytes (the ones imgio decodes), or null
+function imageFormat(buf) {
+    if (buf.length >= 8 && buf.readUInt32BE(0) === 0x89504e47) return 'png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'jpeg';
+    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d) return 'bmp';
+    if (buf.length >= 4 && (buf.readUInt32BE(0) === 0x49492a00 || buf.readUInt32BE(0) === 0x4d4d002a)) return 'tiff';
+    return null;
+}
+// What the server's loadImage makes of the header and the payload: {width, height}, or {error} with its wording.
+// raw: the packed rows, checked by length; encoded: a file of one of the formats above (the PNG's IHDR gives the
+// size; for the others the header's width/height stand in for the decoded size the real server reports)
+function loadImage(img, payload) {
+    img = img || {};
+    const unknown = unknownField(img, KNOWN_IMAGE);
+    if (unknown) return { error: `image: ${unknown}` };
+    const encoding = String(img.encoding === undefined ? '' : img.encoding).toLowerCase();
+    if (encoding === '' || encoding === 'raw') {
+        if (payload.length === 0) return { error: 'image: decode needs a raw payload of width*height*channels bytes (encoding raw)' };
+        const expected = (img.width | 0) * (img.height | 0) * (img.channels | 0);
+        if (payload.length !== expected) {
+            return { error: `imgio: data length ${payload.length} does not match ${img.width}×${img.height}×${img.channels}` };
+        }
+        return { width: img.width, height: img.height };
+    }
+    if (encoding === 'encoded') {
+        if (payload.length === 0) return { error: 'image: decode needs an encoded payload, a PNG, JPEG, BMP or TIFF file (encoding encoded)' };
+        const format = imageFormat(payload);
+        if (!format) return { error: 'imgio: image: unknown format' };
+        if (format === 'png' && payload.length >= 24) return { width: payload.readUInt32BE(16), height: payload.readUInt32BE(20) };
+        return { width: img.width | 0, height: img.height | 0 };
+    }
+    return { error: `image: unknown encoding ${JSON.stringify(img.encoding)} (raw or encoded)` };
+}
+
+// The server's region checks (RegionSpec.UnmarshalJSON, regionFrom; docs/service.md §3.5) with their wording:
+// {error}, or the region with its orientation normalised to 0/90/180/270. The bounds are checked against the image
+// once it is loaded, as Verify does
+function checkRegion(region) {
+    if (region === undefined || region === null) {
+        return { error: 'region: required for verify and analyze ({x, y, w, h, orientation} in image pixels)' };
+    }
+    if (typeof region !== 'object' || Array.isArray(region)) {
+        // the type without the value, as encoding/json names a whole value of the wrong kind
+        return { error: `region: json: cannot unmarshal ${typeof region === 'number' ? 'number' : jsonKind(region)} into Go value of type serve.plain` };
+    }
+    const unknown = unknownField(region, KNOWN_REGION);
+    if (unknown) return { error: `region: ${unknown}` };
+    for (const key of KNOWN_REGION) {
+        const value = region[key];
+        if (value !== undefined && value !== null && !Number.isInteger(value)) {
+            return { error: `region: json: cannot unmarshal ${jsonKind(value)} into Go struct field plain.${key} of type int` };
+        }
+    }
+    const [x, y, w, h, o] = ['x', 'y', 'w', 'h', 'orientation'].map((key) => region[key] || 0);
+    if (w < 2 || h < 2) return { error: `region: width ${w} and height ${h} must be positive and at least 2 px` };
+    if (o % 90 !== 0) return { error: `region: orientation ${o} is not a multiple of 90` };
+    return { x, y, w, h, orientation: ((o % 360) + 360) % 360 };
+}
+
+process.stdout.on('error', () => process.exit(1));            // broken pipe: the parent is gone (§3.1: status 1)
+
+if (!['pass', 'fail', 'not_detected'].includes(verifyStatus)) {
+    log(`FAKE_VERIFY_STATUS ${JSON.stringify(verifyStatus)} is not pass, fail or not_detected`);
+    process.exit(2);
+}
+
+if (noHello) {
+    process.on('SIGTERM', () => { /* ignored: the client has to SIGKILL */ });
+    process.stdin.resume();                                    // reads and never answers
+} else {
+    if (ignoreStop) process.on('SIGTERM', () => { /* ignored */ });
+    write({
+        id: 0, op: 'hello', protocol, sdk: '0.2.0-fake', engineVersion: '0.2.0+fake', schema: '1.0',
+        ops, workers: 1, queue: 64,
+        limits: { maxHeader: 1048576, maxPayload, maxSide: 32768, maxPixels: 268435456 }
+    });
+    log(`hello sent (pid ${process.pid})`);
+    if (garbage) process.stdout.write('this is not a frame\n');
+
+    // FAKE_CRASH_AFTER counts decode, verify and analyze alike: request n+1 dies mid-flight, without an answer
+    let requests = 0;
+    function countOrCrash() {
+        if (crashAfter >= 0 && requests >= crashAfter) process.exit(7);
+        requests += 1;
+    }
+
+    const parser = new FrameParser({ maxPayload });
+    parser.on('error', (err) => {
+        fail(0, 'bad_frame', err.message);
+        log(`bad frame: ${err.message}`);
+        process.exit(3);
+    });
+    parser.on('frame', (req, payload) => {
+        // As the binary's parseRequest: a non-integer deadlineMs fails the whole request before its op is looked at
+        if (req.deadlineMs !== undefined && req.deadlineMs !== null && !Number.isInteger(req.deadlineMs)) {
+            const what = typeof req.deadlineMs === 'number' ? `number ${req.deadlineMs}` : typeof req.deadlineMs;
+            return fail(req.id, 'invalid_input', `json: cannot unmarshal ${what} into Go struct field Request.deadlineMs of type int`);
+        }
+        switch (req.op) {
+            case 'ping':
+                write({ id: req.id, ok: true });
+                break;
+            case 'shutdown':
+                if (ignoreStop) break;
+                write({ id: req.id, ok: true }, undefined, () => process.exit(0));
+                break;
+            case 'decode': {
+                countOrCrash();
+                if (overload) return fail(req.id, 'overloaded', 'queue full');
+                const img = loadImage(req.image, payload);
+                if (img.error) return fail(req.id, 'invalid_input', img.error);
+                const unknown = unknownField(req.options, KNOWN_DECODE_OPTIONS);
+                if (unknown) return fail(req.id, 'invalid_input', `options: ${unknown}`);
+                reply(req.id, {
+                    image: img,
+                    symbols: Array.from({ length: decodeSymbols }, () => ({ ...SYMBOL, region: { ...SYMBOL.region } })),
+                    timing: { totalMs: delayMs, decodeMs: delayMs, queuedMs: 0 }
+                });
+                break;
+            }
+            case 'verify':
+            case 'analyze': {
+                // The server's order (handleVerify): region, options, acquisition, image, then Verify's bounds check
+                if (!ops.includes(req.op)) return fail(req.id, 'unsupported', `op ${JSON.stringify(req.op)} is not supported (ops: ${ops.join(', ')})`);
+                countOrCrash();
+                if (overload) return fail(req.id, 'overloaded', 'queue full');
+                const region = checkRegion(req.region);
+                if (region.error) return fail(req.id, 'invalid_input', region.error);
+                const unknownOpt = unknownField(req.options, KNOWN_VERIFY_OPTIONS) || unknownField(req.options && req.options.spec, KNOWN_SPEC);
+                if (unknownOpt) return fail(req.id, 'invalid_input', `options: ${unknownOpt}`);
+                const acq = req.acquisition || {};
+                const unknownAcq = unknownField(acq, KNOWN_ACQUISITION) || unknownField(acq.calibration, KNOWN_CALIBRATION);
+                if (unknownAcq) return fail(req.id, 'invalid_input', `acquisition: ${unknownAcq}`);
+                const img = loadImage(req.image, payload);
+                if (img.error) return fail(req.id, 'invalid_input', img.error);
+                // Verify's bounds check, when the size is known (an encoded payload that is not a PNG and declares no size is 0×0 here)
+                if (img.width > 0 && img.height > 0 && (region.x < 0 || region.y < 0 || region.x + region.w > img.width || region.y + region.h > img.height)) {
+                    return fail(req.id, 'invalid_input', `barcode: region {X:${region.x} Y:${region.y} W:${region.w} H:${region.h} ` +
+                        `Orientation:${region.orientation}} outside image ${img.width}x${img.height}`);
+                }
+                let result;
+                if (verifyStatus === 'pass') {
+                    result = canned(req.op === 'analyze' ? 'analyze-pass' : 'verify-pass');
+                } else {
+                    result = canned(verifyStatus === 'fail' ? 'verify-fail' : 'verify-not-detected');
+                    if (req.op === 'analyze') result.scans = [];
+                }
+                if (result.symbol) result.symbol.region = region;
+                reply(req.id, { image: img, result, timing: { totalMs: delayMs, verifyMs: delayMs, queuedMs: 0 } });
+                break;
+            }
+            default:
+                fail(req.id, 'unsupported', `op ${JSON.stringify(req.op)} is not supported (ops: ${ops.join(', ')})`);
+        }
+    });
+    if (stall) {
+        setInterval(() => { /* alive, deaf: stdin is never read */ }, 1 << 30);
+    } else {
+        process.stdin.on('data', (chunk) => parser.push(chunk));
+        process.stdin.on('end', () => process.exit(0));        // EOF: the parent closed the pipe (§3.1: status 0)
+    }
+}

package/test/fixtures/analyze-pass.json

@@ -0,0 +1 @@
+{"status":"pass","reasons":[],"warnings":[],"symbol":{"symbology":"EAN13","identifier":"]E0","value":"4006381333931","bytes":"NDAwNjM4MTMzMzkzMQ==","gs1":true,"corners":[{"x":37,"y":4},{"x":322,"y":4},{"x":322,"y":64},{"x":37,"y":64}],"orientation":0,"confidence":1,"lines":60,"checksum":"valid","region":{"x":4,"y":4,"w":339,"h":60,"orientation":0}},"quality":{"overall":{"value":0,"grade":4,"letter":"A","worst":0,"mean":0,"hasValue":true},"text":"4.0/00/660","decode":{"pass":true,"value":60,"detail":""},"decodedLines":60,"edgeDetermination":{"pass":true,"value":0,"detail":""},"minReflectance":{"pass":true,"value":5.098,"detail":""},"minEdgeContrast":{"pass":true,"value":80,"detail":""},"symbolContrast":{"value":80,"grade":4,"letter":"A","worst":4,"mean":80,"hasValue":true},"modulation":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"defects":{"value":0,"grade":4,"letter":"A","worst":4,"mean":0,"hasValue":true},"decodability":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"rmin":5.098,"rmax":85.098,"gt":45.098,"quietZone":{"leftX":11,"rightX":7,"leftPct":110,"rightPct":112.9032,"requiredLeftX":10,"requiredRightX":6.2,"pass":true},"additional":{"pass":true,"value":0,"detail":""},"decodabilityProvisional":false,"inconsistent":false,"limiting":"","scanGrades":[4,4,4]},"dimensions":{"evaluated":false,"xDimPx":3,"xDimMils":0,"xDimMm":0,"nominalXMm":0,"magnification":0,"barHeightPx":60,"barHeightMm":0,"barGrowthPct":0,"narrowBarPx":3,"narrowSpacePx":3,"symbolWidthPx":285,"quietZoneLeftX":11,"quietZoneRightX":7,"ratio":0},"gs1":{"identifier":"]E0","hri":"(01)04006381333931","elements":[{"ai":"01","value":"04006381333931","title":"GTIN"}],"structure":"pass","dataStructure":"pass","errors":[],"table":"","limits":[],"dictionary":"2026-01-27"},"application":{"spec":{"kind":"iso","table":""},"tableTitle":"","limitAction":"","apertureRef":0,"apertureMils":0,"wavelengthNm":660,"edition":"2016","calibration":"none"},"version":{"sdk":"0.2.0","schema":"1.0","dictionary":"2026-01-27"},"timing":{"totalMs":2.411,"measureMs":1.258,"decodeMs":0.4,"gradeMs":0.012,"gs1Ms":0.714},"report":[{"category":0,"name":"Overall grade","value":"4.0/00/660"},{"category":2,"name":"Symbology","value":"EAN-13"},{"category":2,"name":"Decoded text","value":"4006381333931"},{"category":2,"name":"Xdim","value":"3.00 px"},{"category":2,"name":"Edge determ","value":"PASS"},{"category":2,"name":"Min Reflect","value":"PASS"},{"category":2,"name":"Minimum EC","value":"PASS"},{"category":2,"name":"Decode","value":"PASS 60"},{"category":2,"name":"Quiet zone","value":"PASS"},{"category":2,"name":"Contrast","value":"4.0  80%"},{"category":2,"name":"Modulation","value":"4.0  100%"},{"category":2,"name":"Decodability","value":"4.0  100%"},{"category":2,"name":"Defects","value":"4.0  0%"},{"category":2,"name":"Rmin","value":"5.1%"},{"category":2,"name":"Rmax","value":"85.1%"},{"category":2,"name":"GT","value":"45.1%"},{"category":2,"name":"Bar height","value":"60.0 px"},{"category":2,"name":"Bar growth","value":"0%"},{"category":2,"name":"Structure","value":"PASS"},{"category":6,"name":"GS1 Data","value":"(01)04006381333931"},{"category":6,"name":"GS1 Data Structure Pass/Fail","value":"PASS"},{"category":6,"name":"Letter Grade","value":"A"},{"category":6,"name":"Application standard","value":"ISO/IEC 15416"},{"category":6,"name":"Effective aperture","value":"n/a"},{"category":6,"name":"Lighting","value":"660"},{"category":6,"name":"Software product and version","value":"rosepetal-barcode-sdk 0.2.0 (schema 1.0)"}],"scans":[{"index":0,"y":14,"grade":4,"decoded":true,"value":"4006381333931","reason":"","rmax":85.098,"rmin":5.098,"gt":45.098,"sc":80,"ecmin":80,"mod":1,"ernmax":0,"defects":0,"decodability":1,"quietZoneLeftX":11,"quietZoneRightX":7,"profile":[85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098],"edges":[33,36,39,42,51,57,60,63,66,69,75,84,87,90,93,105,108,120,123,126,135,138,144,147,150,156,162,168,171,174,177,180,183,186,198,201,204,207,219,222,225,228,240,243,246,255,258,261,267,270,282,285,288,294,300,306,309,312,315,318]},{"index":1,"y":30,"grade":4,"decoded":true,"value":"4006381333931","reason":"","rmax":85.098,"rmin":5.098,"gt":45.098,"sc":80,"ecmin":80,"mod":1,"ernmax":0,"defects":0,"decodability":1,"quietZoneLeftX":11,"quietZoneRightX":7,"profile":[85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098],"edges":[33,36,39,42,51,57,60,63,66,69,75,84,87,90,93,105,108,120,123,126,135,138,144,147,150,156,162,168,171,174,177,180,183,186,198,201,204,207,219,222,225,228,240,243,246,255,258,261,267,270,282,285,288,294,300,306,309,312,315,318]},{"index":2,"y":46,"grade":4,"decoded":true,"value":"4006381333931","reason":"","rmax":85.098,"rmin":5.098,"gt":45.098,"sc":80,"ecmin":80,"mod":1,"ernmax":0,"defects":0,"decodability":1,"quietZoneLeftX":11,"quietZoneRightX":7,"profile":[85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,77.098,45.098,13.098,5.098,5.098,5.098,13.098,45.098,77.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098,85.098],"edges":[33,36,39,42,51,57,60,63,66,69,75,84,87,90,93,105,108,120,123,126,135,138,144,147,150,156,162,168,171,174,177,180,183,186,198,201,204,207,219,222,225,228,240,243,246,255,258,261,267,270,282,285,288,294,300,306,309,312,315,318]}]}

package/test/fixtures/verify-fail.json

@@ -0,0 +1 @@
+{"status":"fail","reasons":["overall grade 0.0 below fail threshold 1.5 (limiting: Min Reflect)"],"warnings":[],"symbol":{"symbology":"Code128","identifier":"]C0","value":"ROSEPETAL-ISO","bytes":"Uk9TRVBFVEFMLUlTTw==","gs1":false,"corners":[{"x":44,"y":4},{"x":756,"y":4},{"x":756,"y":64},{"x":44,"y":64}],"orientation":0,"confidence":1,"lines":60,"checksum":"valid","region":{"x":4,"y":4,"w":792,"h":60,"orientation":0}},"quality":{"overall":{"value":0,"grade":0,"letter":"F","worst":0,"mean":0,"hasValue":true},"text":"0.0/00/660","decode":{"pass":true,"value":60,"detail":""},"decodedLines":60,"edgeDetermination":{"pass":true,"value":0,"detail":""},"minReflectance":{"pass":false,"value":70.1961,"detail":""},"minEdgeContrast":{"pass":false,"value":9.8039,"detail":""},"symbolContrast":{"value":9.8039,"grade":0,"letter":"F","worst":0,"mean":9.8039,"hasValue":true},"modulation":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"defects":{"value":0,"grade":4,"letter":"A","worst":4,"mean":0,"hasValue":true},"decodability":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"rmin":70.1961,"rmax":80,"gt":75.098,"quietZone":{"leftX":10,"rightX":10,"leftPct":100,"rightPct":100,"requiredLeftX":10,"requiredRightX":10,"pass":true},"additional":{"pass":true,"value":0,"detail":""},"decodabilityProvisional":false,"inconsistent":false,"limiting":"MinReflectance","scanGrades":[0,0,0,0,0,0,0,0,0,0]},"dimensions":{"evaluated":false,"xDimPx":4,"xDimMils":0,"xDimMm":0,"nominalXMm":0,"magnification":0,"barHeightPx":60,"barHeightMm":0,"barGrowthPct":0,"narrowBarPx":4,"narrowSpacePx":4,"symbolWidthPx":712,"quietZoneLeftX":10,"quietZoneRightX":10,"ratio":0},"gs1":null,"application":{"spec":{"kind":"iso","table":""},"tableTitle":"","limitAction":"","apertureRef":0,"apertureMils":0,"wavelengthNm":660,"edition":"2016","calibration":"none"},"version":{"sdk":"0.2.0","schema":"1.0","dictionary":"2026-01-27"},"timing":{"totalMs":7.238,"measureMs":5.092,"decodeMs":0.971,"gradeMs":0.024,"gs1Ms":1.126},"report":[{"category":0,"name":"Overall grade","value":"0.0/00/660"},{"category":2,"name":"Symbology","value":"Code 128"},{"category":2,"name":"Decoded text","value":"ROSEPETAL-ISO"},{"category":2,"name":"Xdim","value":"4.00 px"},{"category":2,"name":"Edge determ","value":"PASS"},{"category":2,"name":"Min Reflect","value":"FAIL"},{"category":2,"name":"Minimum EC","value":"FAIL"},{"category":2,"name":"Decode","value":"PASS 60"},{"category":2,"name":"Quiet zone","value":"PASS"},{"category":2,"name":"Contrast","value":"0.0  9.8%"},{"category":2,"name":"Modulation","value":"4.0  100%"},{"category":2,"name":"Decodability","value":"4.0  100%"},{"category":2,"name":"Defects","value":"4.0  0%"},{"category":2,"name":"Rmin","value":"70.2%"},{"category":2,"name":"Rmax","value":"80%"},{"category":2,"name":"GT","value":"75.1%"},{"category":2,"name":"Bar height","value":"60.0 px"},{"category":2,"name":"Bar growth","value":"0%"},{"category":2,"name":"Structure","value":"PASS"},{"category":6,"name":"Letter Grade","value":"F"},{"category":6,"name":"Application standard","value":"ISO/IEC 15416"},{"category":6,"name":"Effective aperture","value":"n/a"},{"category":6,"name":"Lighting","value":"660"},{"category":6,"name":"Software product and version","value":"rosepetal-barcode-sdk 0.2.0 (schema 1.0)"}]}

package/test/fixtures/verify-not-detected.json

@@ -0,0 +1 @@
+{"status":"not_detected","reasons":["no decode"],"warnings":[],"symbol":null,"quality":{"overall":{"value":0,"grade":0,"letter":"F","worst":0,"mean":0,"hasValue":true},"text":"0.0/00/660","decode":{"pass":false,"value":0,"detail":""},"decodedLines":0,"edgeDetermination":{"pass":false,"value":0,"detail":""},"minReflectance":{"pass":false,"value":59.473,"detail":""},"minEdgeContrast":{"pass":false,"value":12.8125,"detail":""},"symbolContrast":{"value":12.8125,"grade":0,"letter":"F","worst":0,"mean":12.8125,"hasValue":true},"modulation":{"value":0.5,"grade":0,"letter":"F","worst":0,"mean":0.5,"hasValue":true},"defects":{"value":0,"grade":0,"letter":"F","worst":0,"mean":0,"hasValue":true},"decodability":{"value":0,"grade":0,"letter":"","worst":0,"mean":0,"hasValue":false},"rmin":59.473,"rmax":72.2855,"gt":65.8793,"quietZone":{"leftX":0,"rightX":0,"leftPct":0,"rightPct":0,"requiredLeftX":0,"requiredRightX":0,"pass":false},"additional":{"pass":false,"value":0,"detail":""},"decodabilityProvisional":false,"inconsistent":false,"limiting":"Decode","scanGrades":[0,0,0,0,0,0,0,0,0,0]},"dimensions":{"evaluated":false,"xDimPx":0,"xDimMils":0,"xDimMm":0,"nominalXMm":0,"magnification":0,"barHeightPx":0,"barHeightMm":0,"barGrowthPct":0,"narrowBarPx":0,"narrowSpacePx":0,"symbolWidthPx":0,"quietZoneLeftX":0,"quietZoneRightX":0,"ratio":0},"gs1":null,"application":{"spec":{"kind":"iso","table":""},"tableTitle":"","limitAction":"","apertureRef":0,"apertureMils":0,"wavelengthNm":660,"edition":"2016","calibration":"none"},"version":{"sdk":"0.2.0","schema":"1.0","dictionary":"2026-01-27"},"timing":{"totalMs":23.855,"measureMs":23.767,"decodeMs":0.061,"gradeMs":0.022,"gs1Ms":0},"report":[{"category":0,"name":"Overall grade","value":"Bar Code Not Detected"},{"category":2,"name":"Xdim","value":"n/a"},{"category":2,"name":"Edge determ","value":"n/a"},{"category":2,"name":"Min Reflect","value":"FAIL"},{"category":2,"name":"Minimum EC","value":"FAIL"},{"category":2,"name":"Decode","value":"FAIL"},{"category":2,"name":"Quiet zone","value":"n/a"},{"category":2,"name":"Contrast","value":"0.0  12.8%"},{"category":2,"name":"Modulation","value":"0.0  50%"},{"category":2,"name":"Decodability","value":"n/a"},{"category":2,"name":"Defects","value":"0.0  0%"},{"category":2,"name":"Rmin","value":"59.5%"},{"category":2,"name":"Rmax","value":"72.3%"},{"category":2,"name":"GT","value":"65.9%"},{"category":2,"name":"Bar height","value":"n/a"},{"category":2,"name":"Bar growth","value":"n/a"},{"category":2,"name":"Structure","value":"n/a"},{"category":6,"name":"Letter Grade","value":"F"},{"category":6,"name":"Application standard","value":"ISO/IEC 15416"},{"category":6,"name":"Effective aperture","value":"n/a"},{"category":6,"name":"Lighting","value":"660"},{"category":6,"name":"Software product and version","value":"rosepetal-barcode-sdk 0.2.0 (schema 1.0)"}]}

package/test/fixtures/verify-pass.json

@@ -0,0 +1 @@
+{"status":"pass","reasons":[],"warnings":[],"symbol":{"symbology":"EAN13","identifier":"]E0","value":"4006381333931","bytes":"NDAwNjM4MTMzMzkzMQ==","gs1":true,"corners":[{"x":37,"y":4},{"x":322,"y":4},{"x":322,"y":64},{"x":37,"y":64}],"orientation":0,"confidence":1,"lines":60,"checksum":"valid","region":{"x":4,"y":4,"w":339,"h":60,"orientation":0}},"quality":{"overall":{"value":0,"grade":4,"letter":"A","worst":0,"mean":0,"hasValue":true},"text":"4.0/00/660","decode":{"pass":true,"value":60,"detail":""},"decodedLines":60,"edgeDetermination":{"pass":true,"value":0,"detail":""},"minReflectance":{"pass":true,"value":5.098,"detail":""},"minEdgeContrast":{"pass":true,"value":80,"detail":""},"symbolContrast":{"value":80,"grade":4,"letter":"A","worst":4,"mean":80,"hasValue":true},"modulation":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"defects":{"value":0,"grade":4,"letter":"A","worst":4,"mean":0,"hasValue":true},"decodability":{"value":1,"grade":4,"letter":"A","worst":4,"mean":1,"hasValue":true},"rmin":5.098,"rmax":85.098,"gt":45.098,"quietZone":{"leftX":11,"rightX":7,"leftPct":110,"rightPct":112.9032,"requiredLeftX":10,"requiredRightX":6.2,"pass":true},"additional":{"pass":true,"value":0,"detail":""},"decodabilityProvisional":false,"inconsistent":false,"limiting":"","scanGrades":[4,4,4,4,4,4,4,4,4,4]},"dimensions":{"evaluated":false,"xDimPx":3,"xDimMils":0,"xDimMm":0,"nominalXMm":0,"magnification":0,"barHeightPx":60,"barHeightMm":0,"barGrowthPct":0,"narrowBarPx":3,"narrowSpacePx":3,"symbolWidthPx":285,"quietZoneLeftX":11,"quietZoneRightX":7,"ratio":0},"gs1":{"identifier":"]E0","hri":"(01)04006381333931","elements":[{"ai":"01","value":"04006381333931","title":"GTIN"}],"structure":"pass","dataStructure":"pass","errors":[],"table":"","limits":[],"dictionary":"2026-01-27"},"application":{"spec":{"kind":"iso","table":""},"tableTitle":"","limitAction":"","apertureRef":0,"apertureMils":0,"wavelengthNm":660,"edition":"2016","calibration":"none"},"version":{"sdk":"0.2.0","schema":"1.0","dictionary":"2026-01-27"},"timing":{"totalMs":3.515,"measureMs":2.238,"decodeMs":0.526,"gradeMs":0.026,"gs1Ms":0.706},"report":[{"category":0,"name":"Overall grade","value":"4.0/00/660"},{"category":2,"name":"Symbology","value":"EAN-13"},{"category":2,"name":"Decoded text","value":"4006381333931"},{"category":2,"name":"Xdim","value":"3.00 px"},{"category":2,"name":"Edge determ","value":"PASS"},{"category":2,"name":"Min Reflect","value":"PASS"},{"category":2,"name":"Minimum EC","value":"PASS"},{"category":2,"name":"Decode","value":"PASS 60"},{"category":2,"name":"Quiet zone","value":"PASS"},{"category":2,"name":"Contrast","value":"4.0  80%"},{"category":2,"name":"Modulation","value":"4.0  100%"},{"category":2,"name":"Decodability","value":"4.0  100%"},{"category":2,"name":"Defects","value":"4.0  0%"},{"category":2,"name":"Rmin","value":"5.1%"},{"category":2,"name":"Rmax","value":"85.1%"},{"category":2,"name":"GT","value":"45.1%"},{"category":2,"name":"Bar height","value":"60.0 px"},{"category":2,"name":"Bar growth","value":"0%"},{"category":2,"name":"Structure","value":"PASS"},{"category":6,"name":"GS1 Data","value":"(01)04006381333931"},{"category":6,"name":"GS1 Data Structure Pass/Fail","value":"PASS"},{"category":6,"name":"Letter Grade","value":"A"},{"category":6,"name":"Application standard","value":"ISO/IEC 15416"},{"category":6,"name":"Effective aperture","value":"n/a"},{"category":6,"name":"Lighting","value":"660"},{"category":6,"name":"Software product and version","value":"rosepetal-barcode-sdk 0.2.0 (schema 1.0)"}]}