@firela/hk-hsbc-credit 0.1.0

package/index-node.cjs

@@ -0,0 +1,159 @@
+'use strict';
+// _loader-template-node.cjs
+//
+// Phase 74 npm-package Node loader TEMPLATE. At package-assembly time,
+// scripts/assemble-npm-packages.sh sed-substitutes hk_hsbc_credit.opt.wasm with the
+// crate's underscored .opt.wasm name (e.g. eu_deutsche_bank.opt.wasm) and
+// writes the result as `index-node.cjs` into dist/@firela/<name>/. One
+// template serves all 7 publishable packages.
+//
+// This is a rename + templating of the PROVEN loaders/node.js FFI cycle
+// (26 MB/s flat on Node V8 — the run that isolated the wasmi 0.31 superlinear
+// root cause). DO NOT add new behavior here; if the cycle needs to change,
+// change loaders/node.js first and re-template.
+//
+// Contract (docs/WASM_BOUNDARY.md §4): every parser .wasm exports
+//   alloc(size)->ptr, parse(inputPtr,inputLen)->u64, detect(inputPtr,inputLen)->u8,
+//   free_result(ptr,len), + linear `memory`, with ZERO imports.
+// `WebAssembly.instantiate(bytes, {})` — the empty import object encodes that.
+//
+// FFI cycle (identical to the Worker branch — only the module-load differs):
+//   alloc(inputLen) → inputPtr; on 0 return ProcessFailure INTERNAL OOM
+//   RE-FETCH view: new Uint8Array(ex.memory.buffer).set(input, inputPtr)
+//     (a grow inside parse/alloc invalidates any cached ArrayBuffer —
+//      RESEARCH Pitfall 3; must re-fetch every cycle)
+//   ex.parse(inputPtr, inputLen) → BigInt packed; trap caught → ProcessFailure
+//     INTERNAL, free input best-effort, do NOT rethrow
+//   ptr = Number(packed & 0xffffffffn); len = Number((packed >> 32n) & 0xffffffffn)
+//   decode JSON from memory.buffer slice [ptr, ptr+len]
+//   ex.free_result(inputPtr, inputLen); ex.free_result(ptr, len) — BOTH buffers
+//
+// CF Worker BRANCHES ONLY at module-load (workerd blocks instantiate(bytes));
+// see _loader-template-worker.js. After instantiation the FFI cycle is identical.
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_EXPORTS = ['alloc', 'parse', 'detect', 'free_result', 'memory'];
+
+/// Build a ProcessFailure-shaped object matching the sdk-core wire envelope
+/// `{success:false, errors:[{code, message}]}`. Used when the HOST catches a
+/// trap / OOM (the parser's own failures arrive as normal ProcessFailure JSON).
+function processFailure(code, message) {
+    return { success: false, errors: [{ code, message }] };
+}
+
+// The wasm bytes are read ONCE at module load (not per-call) — Node caches the
+// file read, and the bytes are immutable. WebAssembly instantiation is deferred
+// to first use (lazy _exports cache below) so the module is cheap to require.
+const wasmBytes = fs.readFileSync(path.join(__dirname, 'hk_hsbc_credit.opt.wasm'));
+
+let _exports;
+
+/// Lazily instantiate the wasm module ONCE. Cached so the cold-start cost is
+/// paid only on the first parse/detect call. Returns the exports object.
+async function getExports() {
+    if (!_exports) {
+        const { instance } = await WebAssembly.instantiate(wasmBytes, {}); // {} = zero imports
+        _exports = instance.exports;
+    }
+    return _exports;
+}
+
+function makeParse(ex) {
+    return async function parse(bytes) {
+        const input = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        const inputLen = input.length;
+
+        const inputPtr = ex.alloc(inputLen);
+        if (inputPtr === 0) {
+            // OOM: nothing was allocated, nothing to free.
+            return processFailure('INTERNAL', 'alloc returned 0 (OOM) for ' + inputLen + ' bytes');
+        }
+        // Re-fetch the view EVERY cycle: a grow inside parse/alloc invalidates
+        // any cached ArrayBuffer over ex.memory.buffer (RESEARCH Pitfall 3).
+        new Uint8Array(ex.memory.buffer).set(input, inputPtr);
+
+        let packed;
+        try {
+            packed = ex.parse(inputPtr, inputLen); // arrives as BigInt (i64)
+        } catch (e) {
+            // WASM trap (RuntimeError): free the input buffer, surface as
+            // ProcessFailure — do NOT rethrow. Instance stays reusable.
+            try {
+                ex.free_result(inputPtr, inputLen);
+            } catch {
+                /* allocator already torn down — best-effort free */
+            }
+            return processFailure(
+                'INTERNAL',
+                'wasm trap: ' + ((e && e.message) || String(e))
+            );
+        }
+
+        const ptr = Number(packed & 0xffffffffn); // low 32 = result ptr
+        const len = Number((packed >> 32n) & 0xffffffffn); // high 32 = result len
+        if (ptr === 0 || len === 0) {
+            try {
+                ex.free_result(inputPtr, inputLen);
+            } catch {
+                /* best-effort */
+            }
+            return processFailure('INTERNAL', 'parse returned empty result');
+        }
+
+        const resultBytes = Buffer.from(new Uint8Array(ex.memory.buffer, ptr, len));
+        const json = JSON.parse(resultBytes.toString('utf8'));
+
+        // Free BOTH buffers every cycle (input + result) per the FFI contract.
+        ex.free_result(inputPtr, inputLen);
+        ex.free_result(ptr, len);
+        return json;
+    };
+}
+
+function makeDetect(ex) {
+    return async function detect(bytes) {
+        const input = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+        const inputLen = input.length;
+        const inputPtr = ex.alloc(inputLen);
+        if (inputPtr === 0) return 0;
+        new Uint8Array(ex.memory.buffer).set(input, inputPtr);
+        let conf;
+        try {
+            conf = ex.detect(inputPtr, inputLen); // u8 confidence (0/50/100)
+        } catch (e) {
+            try {
+                ex.free_result(inputPtr, inputLen);
+            } catch {
+                /* best-effort */
+            }
+            return 0; // a trap in detect → treat as "no match"
+        }
+        ex.free_result(inputPtr, inputLen);
+        return conf;
+    };
+}
+
+/// Parse CSV/JSON bytes into structured JSON. Returns the parser's own envelope
+/// (ProcessSuccess `{success:true, data, warnings?}` or ProcessFailure). A WASM
+/// trap during parse() is caught and surfaced as ProcessFailure — the host
+/// never crashes and the instance stays reusable (RUNT-02).
+async function parse(bytes) {
+    const ex = await getExports();
+    const missing = REQUIRED_EXPORTS.filter((name) => !ex[name]);
+    if (missing.length) {
+        throw new Error(
+            'createParser: missing required WASM exports: ' + missing.join(', ')
+        );
+    }
+    return makeParse(ex)(bytes);
+}
+
+/// Detection confidence (0/50/100) for bytes.
+async function detect(bytes) {
+    const ex = await getExports();
+    return makeDetect(ex)(bytes);
+}
+
+module.exports = { parse, detect };

package/index-worker.js

@@ -0,0 +1,134 @@
+// _loader-template-worker.js
+//
+// Phase 74 npm-package CF Worker loader TEMPLATE. At package-assembly time,
+// scripts/assemble-npm-packages.sh sed-substitutes hk_hsbc_credit.opt.wasm with the
+// crate's underscored .opt.wasm name (e.g. eu_deutsche_bank.opt.wasm) and
+// writes the result as `index-worker.js` into dist/@firela/<name>/. One
+// template serves all 7 publishable packages.
+//
+// HARD CONSTRAINT (Cloudflare Workers runtime): dynamic WASM *compilation* is
+// BLOCKED (like eval). A parser .wasm MUST be loaded as a Wrangler-bundled,
+// pre-compiled ES-module Module:
+//
+//     import mod from "./eu_deutsche_bank.wasm";   // mod is a WebAssembly.Module
+//
+// ...NOT `fs.readFileSync(...)` + `WebAssembly.instantiate(bytes)`. There is no
+// Node `fs` here and `WebAssembly.instantiate(bytes)` is disallowed at runtime.
+// (https://developers.cloudflare.com/workers/runtime-apis/webassembly/)
+//
+// FFI contract (docs/WASM_BOUNDARY.md §4): every parser .wasm exports
+//   alloc(size)->ptr, parse(inputPtr,inputLen)->u64, detect(inputPtr,inputLen)->u8,
+//   free_result(ptr,len), + linear `memory`, with ZERO imports. The empty import
+//   object `{}` below encodes that.
+//
+// This is the ES-import-constrained variant of the Node loader's FFI cycle
+// (loaders/node.js). The alloc → re-fetch view → set → parse (trap-safe)
+// → unpack packed ptr/len → decode → JSON → free BOTH buffers cycle is IDENTICAL
+// to the Node branch; only the WASM entry differs (pre-compiled Module vs raw
+// bytes). The branch is ONLY at module-load.
+
+import mod from "./hk_hsbc_credit.opt.wasm";
+
+const REQUIRED_EXPORTS = ['alloc', 'parse', 'detect', 'free_result', 'memory'];
+
+// Instantiate ONCE, lazily on first request (per CF official guidance — top-level
+// instantiation; the result is cached so the cold-start cost is paid once). `mod`
+// is a pre-compiled WebAssembly.Module, so instantiate() returns an Instance
+// (unlike the bytes overload, which returns {module, instance}) — handle both.
+let _exports;
+async function getExports() {
+    if (!_exports) {
+        const result = await WebAssembly.instantiate(mod, {}); // {} = zero imports
+        const instance = result.instance || result; // bytes→{instance}, Module→Instance
+        _exports = instance.exports;
+    }
+    return _exports;
+}
+
+function processFailure(code, message) {
+    return { success: false, errors: [{ code, message }] };
+}
+
+/// Parse CSV/JSON bytes into structured JSON. Returns the parser's own envelope
+/// (ProcessSuccess `{success:true, data, warnings?}` or ProcessFailure). A WASM
+/// trap during parse() is caught and surfaced as ProcessFailure — the Worker
+/// never crashes and the instance stays reusable (RUNT-02 CF half).
+export async function parse(bytes) {
+    const ex = await getExports();
+    const input = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const inputLen = input.length;
+
+    const inputPtr = ex.alloc(inputLen);
+    if (inputPtr === 0) {
+        // OOM: nothing allocated, nothing to free.
+        return processFailure(
+            'INTERNAL',
+            'alloc returned 0 (OOM) for ' + inputLen + ' bytes'
+        );
+    }
+    // Re-fetch the view EVERY cycle: a grow inside parse/alloc invalidates any
+    // cached ArrayBuffer over ex.memory.buffer (stale-view hazard).
+    new Uint8Array(ex.memory.buffer).set(input, inputPtr);
+
+    let packed;
+    try {
+        packed = ex.parse(inputPtr, inputLen); // arrives as BigInt (i64)
+    } catch (e) {
+        // WASM trap (RuntimeError): free the input buffer, surface as
+        // ProcessFailure — do NOT rethrow. Instance stays reusable.
+        try {
+            ex.free_result(inputPtr, inputLen);
+        } catch {
+            /* allocator already torn down — best-effort free */
+        }
+        return processFailure(
+            'INTERNAL',
+            'wasm trap: ' + ((e && e.message) || String(e))
+        );
+    }
+
+    const ptr = Number(packed & 0xffffffffn); // low 32 = result ptr
+    const len = Number((packed >> 32n) & 0xffffffffn); // high 32 = result len
+    if (ptr === 0 || len === 0) {
+        try {
+            ex.free_result(inputPtr, inputLen);
+        } catch {
+            /* best-effort */
+        }
+        return processFailure('INTERNAL', 'parse returned empty result');
+    }
+
+    const resultBytes = new Uint8Array(ex.memory.buffer, ptr, len);
+    const json = JSON.parse(new TextDecoder().decode(resultBytes));
+
+    // Free BOTH buffers every cycle (input + result) per the FFI contract.
+    ex.free_result(inputPtr, inputLen);
+    ex.free_result(ptr, len);
+    return json;
+}
+
+/// Detection confidence (0/50/100) for bytes.
+export async function detect(bytes) {
+    const ex = await getExports();
+    const input = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const inputLen = input.length;
+    const inputPtr = ex.alloc(inputLen);
+    if (inputPtr === 0) return 0;
+    new Uint8Array(ex.memory.buffer).set(input, inputPtr);
+    let conf;
+    try {
+        conf = ex.detect(inputPtr, inputLen);
+    } catch (e) {
+        try {
+            ex.free_result(inputPtr, inputLen);
+        } catch {
+            /* best-effort */
+        }
+        return 0; // a trap in detect → treat as "no match"
+    }
+    ex.free_result(inputPtr, inputLen);
+    return conf;
+}
+
+export { parse, detect };
+export default { parse, detect };

package/index.d.ts

@@ -0,0 +1,88 @@
+// _index-dts.template.ts
+//
+// Phase 74 npm-package TypeScript declarations TEMPLATE. Hand-written from
+// sdk-core/src/types.rs (the wire-format contract). NOT generated by wasm-bindgen
+// — this SDK uses raw extern "C" + serde_json at the FFI boundary (ERRATUM:
+// ADR-0101; wasm-bindgen/serde-wasm-bindgen are NOT used). The surface is small
+// and stable (parse/detect + wire types), so hand-writing is simpler and keeps
+// the declarations free of wasm-bindgen runtime coupling.
+//
+// Wire-format invariants (types.rs §wire-format contract):
+//   - `success` is a JSON boolean (true/false), never a string. Hence
+//     ProcessSuccess / ProcessFailure use literal `true` / `false` here.
+//   - `amount` is an exact decimal STRING ("128.50"), never a float/number
+//     (WASM-02: preserve precision across the boundary).
+//   - `metadata` is optional; institution-specific fields live there.
+
+/// Parsed transaction in stable JSON wire form.
+///
+/// `date` is an ISO 8601 string, `amount` is an exact decimal string (never
+/// f64 — preserves precision per WASM-02), `currency` is ISO 4217.
+export interface RawTransaction {
+    /** ISO 8601 date, e.g. "2024-01-15". */
+    date: string;
+    /** Exact decimal string ("128.50", "-35.00") — NEVER a number. */
+    amount: string;
+    /** ISO 4217 currency code, e.g. "CNY", "USD", "EUR". */
+    currency: string;
+    /** Transaction description / narration. */
+    description: string;
+    /** Payee / counterparty (optional — omitted from JSON when absent). */
+    payee?: string;
+    /** Institution-specific structured metadata (optional). */
+    metadata?: Record<string, unknown>;
+}
+
+/// Non-fatal warning surfaced alongside a successful result.
+export interface ProcessWarning {
+    message: string;
+}
+
+/// Categorized processing error. Serializes as `{code, message}` matching the
+/// sdk-core ProcessError enum variants.
+export type ProcessError =
+    | { code: 'FORMAT'; message: string }
+    | { code: 'DETECT'; message: string }
+    | { code: 'ENCODING'; message: string }
+    | { code: 'INTERNAL'; message: string };
+
+/// Successful parse/sanitize result.
+///
+/// JSON: `{"success": true, "data": [...], "warnings": [...]}` — the `success`
+/// field is always the boolean literal `true`.
+export interface ProcessSuccess {
+    success: true;
+    data: RawTransaction[];
+    warnings?: ProcessWarning[];
+}
+
+/// Failed parse/sanitize result.
+///
+/// JSON: `{"success": false, "errors": [...]}` — `success` is always `false`.
+export interface ProcessFailure {
+    success: false;
+    errors: ProcessError[];
+}
+
+/// Result envelope returned by `parse()`. Discriminated union on the boolean
+/// `success` field — narrow with `result.success === true`.
+export type ParseResult = ProcessSuccess | ProcessFailure;
+
+/**
+ * Parse CSV/JSON bytes into structured transactions.
+ *
+ * @param bytes - Statement bytes (Uint8Array or Node Buffer).
+ * @returns The parser's wire envelope. On success, `data` is the transaction
+ *          array; on failure (malformed input, encoding error, internal trap),
+ *          `errors` lists the categorized error(s). The host never throws on
+ *          parser-level failures — they arrive as `ProcessFailure`.
+ */
+export declare function parse(bytes: Uint8Array | Buffer): Promise<ParseResult>;
+
+/**
+ * Detection confidence for the given bytes.
+ *
+ * @param bytes - Statement bytes to identify.
+ * @returns Confidence in {0, 50, 100}: 0 = no match, 50 = partial, 100 = definite.
+ */
+export declare function detect(bytes: Uint8Array | Buffer): Promise<number>;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@firela/hk-hsbc-credit",
+  "version": "0.1.0",
+  "description": "firela parser/sanitizer WASM module — isomorphic Node.js + Cloudflare Worker loader (ADR-0101 compiled-only).",
+  "type": "module",
+  "main": "./index-node.cjs",
+  "module": "./index-worker.js",
+  "exports": {
+    ".": {
+      "node": {
+        "require": "./index-node.cjs"
+      },
+      "worker": "./index-worker.js",
+      "default": "./index-worker.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index-node.cjs",
+    "index-worker.js",
+    "index.d.ts",
+    "hk_hsbc_credit.opt.wasm"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "firela",
+    "wasm",
+    "parser",
+    "bank-statement",
+    "isomorphic"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}