disarm 0.16.0 → 0.17.0

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Lexicon, Pipeline } from './binding';
+import { Lexicon as NativeLexicon, Pipeline } from './binding';
 import type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, ConfusableCoverage, Finding as NativeFinding, AnomalyReport as NativeAnomalyReport, HostnameAnalysis as NativeHostnameAnalysis } from './binding';
 export type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, ConfusableCoverage, };
 /** Findings from {@link analyzeHostname}. `suspicious` is a maximally
@@ -9,8 +9,13 @@ export type HostnameAnalysis = NativeHostnameAnalysis;
  * `inspectAnomalies` rebuild an internal set from the caller's word array on
  * every call; constructing a `Lexicon` once (`new Lexicon([...])`) and passing
  * it instead builds that set a single time and reuses it across calls.
+ *
+ * A thin subclass of the native handle, so a bad argument to the constructor throws a
+ * {@link DisarmError} like every other entry point (`formal/bindings`, N2).
  */
-export { Lexicon };
+export declare class Lexicon extends NativeLexicon {
+    constructor(words: string[]);
+}
 /**
  * A reusable, opaque named-policy-profile pipeline handle (#404). Build it once
  * with {@link getPipeline} for a named profile, then apply it to any number of
@@ -47,14 +52,17 @@ export declare class DisarmInvalidArgument extends DisarmError {
 }
 /** Transliteration scheme: the general-purpose default, ISO 9-style ASCII, or GOST R 7.0.34. */
 export type Scheme = 'default' | 'strict_iso9' | 'gost7034';
-/** Confusable-folding target script. */
-export type TargetScript = 'latin' | 'cyrillic';
+/**
+ * Confusable-folding target script. `'arabic'` and `'hebrew'` fold toward those scripts
+ * (#792); the runtime accepted them before this type admitted them.
+ */
+export type TargetScript = 'latin' | 'cyrillic' | 'arabic' | 'hebrew';
 /**
  * How the fold treats non-Latin digits.
  *
  * `'numeric'` (default) sends them to the ASCII digit — `०` becomes `0` — which is right
  * for prose. `'tr39'` uses upstream's targets, which send most of them to a Latin letter
- * (`०` → `o`), and that is what an identifier *skeleton* wants. The two differ on 45 rows.
+ * (`०` → `o`), and that is what an identifier *skeleton* wants. The two differ on 47 rows.
  *
  * Three of those rows do not land on a letter: `٠` and `۰` fold to `.`, and `𑣣` folds to
  * the two characters `rn`. A skeleton feeding a label- or path-shaped key has to allow
@@ -80,13 +88,16 @@ export interface TransliterateOptions {
     /** A language profile applied on top of the scheme (e.g. `'uk'`, `'de'`, or `'auto'`). */
     lang?: string;
 }
-/** Romanize Unicode text to ASCII. */
+/** Romanize Unicode text to ASCII. An unknown `lang` throws {@link DisarmInvalidArgument}. */
 export declare function transliterate(text: string, options?: TransliterateOptions): string;
 /** Reverse-transliterate Latin back to a native script (`'el'`, `'ru'`, or `'uk'`). */
 export declare function reverseTransliterate(text: string, options: {
     lang: ReverseLang;
 }): string;
-/** Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in order. */
+/**
+ * Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in
+ * order. An unknown `lang` throws {@link DisarmInvalidArgument}.
+ */
 export declare function findUntranslatable(text: string, options?: TransliterateOptions): Untranslatable[];
 /** Fold cross-script confusables toward `target` (default `'latin'`). */
 export declare function normalizeConfusables(text: string, options?: {
@@ -144,7 +155,10 @@ export interface SlugifyOptions {
     hexadecimal?: boolean;
     safeChars?: string;
 }
-/** Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. */
+/**
+ * Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. An unknown `lang`
+ * throws {@link DisarmInvalidArgument}.
+ */
 export declare function slugify(text: string, options?: SlugifyOptions): string;
 /** Strip diacritics (`"café"` → `"cafe"`). */
 export declare function stripAccents(text: string): string;
@@ -183,7 +197,12 @@ export type CollisionKey = 'fold_case' | 'search_key' | 'catalog_key' | 'canonic
 export declare function findKeyCollisions(values: string[], key: CollisionKey, options?: {
     lang?: string;
 }): KeyCollision[];
-/** Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks. */
+/**
+ * Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks.
+ * An emoji CLDR cannot name — a regional indicator or a Plane 14 tag character standing
+ * alone — becomes `'[?]'`, the sentinel {@link transliterate} writes, and the default in
+ * every binding.
+ */
 export declare function demojize(text: string, options?: {
     stripModifiers?: boolean;
 }): string;
@@ -192,8 +211,9 @@ export declare function demojize(text: string, options?: {
  * The counterpart to {@link demojize}, and a different question of a different table.
  * `demojize` asks *what does CLDR call this?*, so its domain is the CLDR name table,
  * which is wider than the emoji: `demojize('x™y')` is `'x trade mark y'`. This asks *is
- * this an emoji by the UCD's properties?* — `Emoji_Presentation=Yes`, an `Emoji=Yes` base
- * carrying `U+FE0F`, and the ZWJ, modifier, keycap and flag sequences on those. Nothing
+ * this an emoji by the UCD's properties?* — `Emoji_Presentation=Yes`, an `Emoji=Yes`
+ * base carrying `U+FE0F` (not an `Extended_Pictographic` one, so `★` + `U+FE0F` stays),
+ * and the ZWJ, modifier, keycap and flag sequences on those. Nothing
  * else moves.
  *
  * `replacement` is inserted exactly as given, with no padding and no whitespace collapse:
@@ -233,11 +253,20 @@ export declare function stripVariationSelectors(text: string): string;
 export declare function stripNoncharacters(text: string): string;
 /** Strip every Private Use Area code point (#413). */
 export declare function stripPua(text: string): string;
-/** Cap combining marks per base character at `maxMarks` (default `2`). */
+/**
+ * Cap the marks of each combining class on one base character at `maxMarks`, a
+ * non-negative integer. The default is the core's, 3 — equal to {@link isZalgo}'s
+ * threshold (#788), so this never strips from text `isZalgo` declines to flag. It is read
+ * from the core rather than restated here: this layer had kept the old cap of 2
+ * (`formal/bindings`, B1).
+ */
 export declare function stripZalgo(text: string, options?: {
     maxMarks?: number;
 }): string;
-/** Whether any base character carries more than `threshold` (default `3`) combining marks. */
+/**
+ * Whether any base character carries more than `threshold` marks of one combining class.
+ * The default is the core's, 3.
+ */
 export declare function isZalgo(text: string, options?: {
     threshold?: number;
 }): boolean;
@@ -264,10 +293,11 @@ export declare function stripObfuscation(text: string, options?: {
     digitPolicy?: DigitPolicy;
 }): string;
 /**
- * Canonicalize text for security-sensitive comparison: NFKC → strip bidi/format
- * → strip invisible classes (#413) → strip control → strip zero-width → collapse
- * whitespace → cap combining marks (anti-zalgo) → NFC → confusables → NFC
- * (confusables sandwiched between NFC passes for idempotency).
+ * Canonicalize text for security-sensitive comparison: resolve deletions → NFKC →
+ * strip bidi/format → strip invisible classes (#413) → strip control → strip
+ * zero-width → collapse whitespace → drop repeated marks → cap combining marks
+ * (anti-zalgo) → NFC → confusables and NFC to a fixed point → drop repeated marks
+ * → cap combining marks again (the fold is iterated with NFC for idempotency).
  *
  * The name describes the mechanism (Unicode canonicalization for matching), not
  * a safety guarantee — this is not an output sanitizer; encode at the sink.
@@ -297,7 +327,13 @@ export interface SanitizeFilenameOptions {
     lang?: string;
     preserveExtension?: boolean;
 }
-/** Turn arbitrary text into a filesystem-safe filename. */
+/**
+ * Turn arbitrary text into a filesystem-safe filename.
+ *
+ * `separator` must be printable, non-space ASCII with no character illegal on
+ * `platform` and no path separator (`/`, `\`); anything else throws
+ * {@link DisarmInvalidArgument}. `''` is allowed.
+ */
 export declare function sanitizeFilename(text: string, options?: SanitizeFilenameOptions): string;
 /**
  * Case/accent/script-insensitive search lookup key (like {@link catalogKey}
@@ -371,8 +407,9 @@ export interface MlNormalizeOptions {
     foldCase?: boolean;
 }
 /**
- * ML/NLP normalization: NFKC → emoji→text → transliterate → strip accents →
- * [case fold] → strip control → strip zero-width → collapse whitespace.
+ * ML/NLP normalization: resolve deletions → NFKC → emoji→text → transliterate →
+ * strip accents → emoji→text → [case fold] → strip control → strip zero-width →
+ * collapse whitespace → NFC.
  *
  * Note this folds no confusables — it is not a homoglyph defence at any setting. Put
  * {@link normalizeConfusables} in front of it when a model needs both.

package/index.js

@@ -108,8 +108,40 @@ exports.inspectAnomalies = inspectAnomalies;
  */
 const native = __importStar(require("./binding"));
 const binding_1 = require("./binding");
-Object.defineProperty(exports, "Lexicon", { enumerable: true, get: function () { return binding_1.Lexicon; } });
 Object.defineProperty(exports, "Pipeline", { enumerable: true, get: function () { return binding_1.Pipeline; } });
+/**
+ * A reusable, opaque lexicon handle (HAI-SDLC 6.1). `hasAnomalies` /
+ * `inspectAnomalies` rebuild an internal set from the caller's word array on
+ * every call; constructing a `Lexicon` once (`new Lexicon([...])`) and passing
+ * it instead builds that set a single time and reuses it across calls.
+ *
+ * A thin subclass of the native handle, so a bad argument to the constructor throws a
+ * {@link DisarmError} like every other entry point (`formal/bindings`, N2).
+ */
+class Lexicon extends binding_1.Lexicon {
+    constructor(words) {
+        try {
+            super(words);
+        }
+        catch (e) {
+            throw translate(e);
+        }
+    }
+}
+exports.Lexicon = Lexicon;
+// The handle's methods are native; route them through `call()` as every function is, so a
+// wrong argument or a refused digit policy throws a `DisarmError` rather than a bare
+// `Error` whose message still carries the shim's tag (`formal/bindings`, N2). Patched on
+// the prototype, so `getPipeline`'s native instances and `instanceof Pipeline` are
+// unchanged.
+const nativeProcess = binding_1.Pipeline.prototype.process;
+const nativeWithDigitPolicy = binding_1.Pipeline.prototype.withDigitPolicy;
+binding_1.Pipeline.prototype.process = function process(text) {
+    return call(() => nativeProcess.call(this, text));
+};
+binding_1.Pipeline.prototype.withDigitPolicy = function withDigitPolicy(digitPolicy) {
+    return call(() => nativeWithDigitPolicy.call(this, digitPolicy));
+};
 // ── Errors ──────────────────────────────────────────────────────────────────
 /** Base class for every error disarm raises, so callers can `catch (e) { if (e instanceof DisarmError) … }`. */
 class DisarmError extends Error {
@@ -129,33 +161,83 @@ class DisarmInvalidArgument extends DisarmError {
 exports.DisarmInvalidArgument = DisarmInvalidArgument;
 const INVALID_ARG_TAG = 'DisarmInvalidArgument: ';
 const ERROR_TAG = 'DisarmError: ';
+/**
+ * The napi statuses an argument conversion fails with: a value of the wrong JS type
+ * (`transliterate(123)`, `stripAccents(undefined)`). They are invalid arguments, as a
+ * `TypeError` is in the Ruby binding.
+ */
+const NAPI_ARGUMENT_STATUSES = new Set([
+    'InvalidArg',
+    'ObjectExpected',
+    'StringExpected',
+    'NameExpected',
+    'FunctionExpected',
+    'NumberExpected',
+    'BooleanExpected',
+    'ArrayExpected',
+    'BigintExpected',
+]);
 /**
  * Run a native call, re-raising its tagged napi error as the matching
  * `DisarmError` subclass. The native shim prefixes fallible messages with
  * `"DisarmInvalidArgument: "` or `"DisarmError: "`; we strip the matched tag
- * cleanly. Any other throw — an untagged `Error`, or a non-`Error` value — is
- * still wrapped as a `DisarmError` so nothing leaks out unwrapped.
+ * cleanly. An argument napi could not convert is a `DisarmInvalidArgument`. Any
+ * other throw — an untagged `Error`, or a non-`Error` value — is still wrapped as a
+ * `DisarmError` so nothing leaks out unwrapped.
+ *
+ * Every export goes through here, the infallible ones included: they throw on an
+ * argument of the wrong type, and "everything disarm throws is a `DisarmError`" was
+ * false for them while they called the native function directly (`formal/bindings`,
+ * N2).
  */
 function call(fn) {
     try {
         return fn();
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.startsWith(INVALID_ARG_TAG)) {
-            throw new DisarmInvalidArgument(msg.slice(INVALID_ARG_TAG.length));
-        }
-        if (msg.startsWith(ERROR_TAG)) {
-            throw new DisarmError(msg.slice(ERROR_TAG.length));
-        }
-        throw new DisarmError(msg);
+        throw translate(e);
+    }
+}
+/** The {@link DisarmError} a thrown value becomes; see {@link call}. */
+function translate(e) {
+    if (e instanceof DisarmError) {
+        return e;
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.startsWith(INVALID_ARG_TAG)) {
+        return new DisarmInvalidArgument(msg.slice(INVALID_ARG_TAG.length));
+    }
+    if (msg.startsWith(ERROR_TAG)) {
+        return new DisarmError(msg.slice(ERROR_TAG.length));
+    }
+    const code = e?.code;
+    if (typeof code === 'string' && NAPI_ARGUMENT_STATUSES.has(code)) {
+        return new DisarmInvalidArgument(msg);
+    }
+    return new DisarmError(msg);
+}
+/**
+ * Check a size or threshold option before it reaches napi, which converts any JS
+ * number to an integer: `NaN` and `0.9` became 0, `2 ** 64` saturated, so
+ * `stripZalgo('caf\u00e9', { maxMarks: NaN })` stripped the accent (`formal/bindings`, N1).
+ * A size is a non-negative safe integer; anything else throws
+ * {@link DisarmInvalidArgument}.
+ */
+function size(name, value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new DisarmInvalidArgument(`${name} must be a non-negative integer (got ${String(value)})`);
     }
+    return value;
+}
+/** {@link size} for an optional option: `undefined` or `null` stays absent. */
+function optionalSize(name, value) {
+    return value == null ? undefined : size(name, value);
 }
-/** Romanize Unicode text to ASCII. */
+/** Romanize Unicode text to ASCII. An unknown `lang` throws {@link DisarmInvalidArgument}. */
 function transliterate(text, options = {}) {
     const { scheme = 'default', lang } = options;
     if (scheme === 'default' && lang == null) {
-        return native.transliterate(text);
+        return call(() => native.transliterate(text));
     }
     return call(() => native.transliterateOpts(text, scheme, lang ?? undefined));
 }
@@ -163,7 +245,10 @@ function transliterate(text, options = {}) {
 function reverseTransliterate(text, options) {
     return call(() => native.reverseTransliterate(text, options.lang));
 }
-/** Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in order. */
+/**
+ * Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in
+ * order. An unknown `lang` throws {@link DisarmInvalidArgument}.
+ */
 function findUntranslatable(text, options = {}) {
     const { scheme = 'default', lang } = options;
     return call(() => native.findUntranslatable(text, scheme, lang ?? undefined));
@@ -210,12 +295,15 @@ function unmappedConfusables(options = {}) {
 function findUnmappedConfusables(text, options = {}) {
     return call(() => native.findUnmappedConfusables(text, options.target ?? 'latin'));
 }
-/** Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. */
+/**
+ * Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. An unknown `lang`
+ * throws {@link DisarmInvalidArgument}.
+ */
 function slugify(text, options = {}) {
     return call(() => native.slugify(text, {
         separator: options.separator ?? '-',
         lowercase: options.lowercase ?? true,
-        maxLength: options.maxLength ?? 0,
+        maxLength: optionalSize('maxLength', options.maxLength) ?? 0,
         wordBoundary: options.wordBoundary ?? false,
         saveOrder: options.saveOrder ?? false,
         stopwords: options.stopwords ?? [],
@@ -230,11 +318,11 @@ function slugify(text, options = {}) {
 // ── Canonicalization primitives ─────────────────────────────────────────────
 /** Strip diacritics (`"café"` → `"cafe"`). */
 function stripAccents(text) {
-    return native.stripAccents(text);
+    return call(() => native.stripAccents(text));
 }
 /** Full Unicode case fold — more aggressive than `String.toLowerCase()`. */
 function foldCase(text) {
-    return native.foldCase(text);
+    return call(() => native.foldCase(text));
 }
 /**
  * Whether `text` is a stable identity key under case folding — that is, whether
@@ -247,7 +335,7 @@ function foldCase(text) {
  * folded into {@link hasAnomalies}.
  */
 function isCaseFoldStable(text) {
-    return native.isCaseFoldStable(text);
+    return call(() => native.isCaseFoldStable(text));
 }
 /**
  * Which of `values` are the same name under `key` (#620).
@@ -268,24 +356,30 @@ function isCaseFoldStable(text) {
 function findKeyCollisions(values, key, options = {}) {
     return call(() => native.findKeyCollisions(values, key, options.lang));
 }
-/** Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks. */
+/**
+ * Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks.
+ * An emoji CLDR cannot name — a regional indicator or a Plane 14 tag character standing
+ * alone — becomes `'[?]'`, the sentinel {@link transliterate} writes, and the default in
+ * every binding.
+ */
 function demojize(text, options = {}) {
-    return native.demojize(text, options.stripModifiers ?? false);
+    return call(() => native.demojize(text, options.stripModifiers ?? false));
 }
 /** Replace every emoji with `replacement`, verbatim (#972).
  *
  * The counterpart to {@link demojize}, and a different question of a different table.
  * `demojize` asks *what does CLDR call this?*, so its domain is the CLDR name table,
  * which is wider than the emoji: `demojize('x™y')` is `'x trade mark y'`. This asks *is
- * this an emoji by the UCD's properties?* — `Emoji_Presentation=Yes`, an `Emoji=Yes` base
- * carrying `U+FE0F`, and the ZWJ, modifier, keycap and flag sequences on those. Nothing
+ * this an emoji by the UCD's properties?* — `Emoji_Presentation=Yes`, an `Emoji=Yes`
+ * base carrying `U+FE0F` (not an `Extended_Pictographic` one, so `★` + `U+FE0F` stays),
+ * and the ZWJ, modifier, keycap and flag sequences on those. Nothing
  * else moves.
  *
  * `replacement` is inserted exactly as given, with no padding and no whitespace collapse:
  * `''` closes an intra-word split (`aa🔥bb` → `aabb`) and `' '` keeps two words apart
  * (`stop🛑now` → `stop now`), and no rule serves both. */
 function replaceEmoji(text, replacement = '') {
-    return native.replaceEmoji(text, replacement);
+    return call(() => native.replaceEmoji(text, replacement));
 }
 // ── Normalization ───────────────────────────────────────────────────────────
 /** Apply a Unicode normalization `form` (default `'NFC'`). */
@@ -308,43 +402,52 @@ function isNormalized(text, options = {}) {
  * deleting them) means `a\rb` → `a b`, never `ab`.
  */
 function collapseWhitespace(text) {
-    return native.collapseWhitespace(text);
+    return call(() => native.collapseWhitespace(text));
 }
 /** Remove C0/C1 control characters (except tab/newline). */
 function stripControlChars(text) {
-    return native.stripControlChars(text);
+    return call(() => native.stripControlChars(text));
 }
 /** Remove zero-width characters (ZWSP/ZWNJ/ZWJ/word-joiner). */
 function stripZeroWidthChars(text) {
-    return native.stripZeroWidthChars(text);
+    return call(() => native.stripZeroWidthChars(text));
 }
 /** Remove Unicode bidirectional control characters. */
 function stripBidi(text) {
-    return native.stripBidi(text);
+    return call(() => native.stripBidi(text));
 }
 /** Strip the Unicode Tags block (U+E0000–U+E007F), preserving valid emoji flag sequences (#413). */
 function stripTags(text) {
-    return native.stripTags(text);
+    return call(() => native.stripTags(text));
 }
 /** Strip every variation selector (VS1–VS256) (#413). */
 function stripVariationSelectors(text) {
-    return native.stripVariationSelectors(text);
+    return call(() => native.stripVariationSelectors(text));
 }
 /** Strip every Unicode noncharacter (#413). */
 function stripNoncharacters(text) {
-    return native.stripNoncharacters(text);
+    return call(() => native.stripNoncharacters(text));
 }
 /** Strip every Private Use Area code point (#413). */
 function stripPua(text) {
-    return native.stripPua(text);
+    return call(() => native.stripPua(text));
 }
-/** Cap combining marks per base character at `maxMarks` (default `2`). */
+/**
+ * Cap the marks of each combining class on one base character at `maxMarks`, a
+ * non-negative integer. The default is the core's, 3 — equal to {@link isZalgo}'s
+ * threshold (#788), so this never strips from text `isZalgo` declines to flag. It is read
+ * from the core rather than restated here: this layer had kept the old cap of 2
+ * (`formal/bindings`, B1).
+ */
 function stripZalgo(text, options = {}) {
-    return call(() => native.stripZalgo(text, options.maxMarks ?? 2));
+    return call(() => native.stripZalgo(text, optionalSize('maxMarks', options.maxMarks)));
 }
-/** Whether any base character carries more than `threshold` (default `3`) combining marks. */
+/**
+ * Whether any base character carries more than `threshold` marks of one combining class.
+ * The default is the core's, 3.
+ */
 function isZalgo(text, options = {}) {
-    return call(() => native.isZalgo(text, options.threshold ?? 3));
+    return call(() => native.isZalgo(text, optionalSize('threshold', options.threshold)));
 }
 // ── Deobfuscation & security presets ────────────────────────────────────────
 /**
@@ -365,17 +468,18 @@ function canonicalizeStrict(text, options = {}) {
  * it collapses TAB/LF to a space, which the primitives leave alone. Infallible.
  */
 function stripFormat(text) {
-    return native.stripFormat(text);
+    return call(() => native.stripFormat(text));
 }
 /** Remove obfuscation (zero-width, bidi, combining-mark abuse, homoglyphs) while keeping legible content. */
 function stripObfuscation(text, options = {}) {
     return call(() => native.stripObfuscation(text, options.digitPolicy ?? 'numeric'));
 }
 /**
- * Canonicalize text for security-sensitive comparison: NFKC → strip bidi/format
- * → strip invisible classes (#413) → strip control → strip zero-width → collapse
- * whitespace → cap combining marks (anti-zalgo) → NFC → confusables → NFC
- * (confusables sandwiched between NFC passes for idempotency).
+ * Canonicalize text for security-sensitive comparison: resolve deletions → NFKC →
+ * strip bidi/format → strip invisible classes (#413) → strip control → strip
+ * zero-width → collapse whitespace → drop repeated marks → cap combining marks
+ * (anti-zalgo) → NFC → confusables and NFC to a fixed point → drop repeated marks
+ * → cap combining marks again (the fold is iterated with NFC for idempotency).
  *
  * The name describes the mechanism (Unicode canonicalization for matching), not
  * a safety guarantee — this is not an output sanitizer; encode at the sink.
@@ -402,9 +506,15 @@ function securityClean(text) {
 function getPipeline(profile) {
     return call(() => native.getPipeline(profile));
 }
-/** Turn arbitrary text into a filesystem-safe filename. */
+/**
+ * Turn arbitrary text into a filesystem-safe filename.
+ *
+ * `separator` must be printable, non-space ASCII with no character illegal on
+ * `platform` and no path separator (`/`, `\`); anything else throws
+ * {@link DisarmInvalidArgument}. `''` is allowed.
+ */
 function sanitizeFilename(text, options = {}) {
-    return call(() => native.sanitizeFilename(text, options.separator ?? '_', options.maxLength ?? 255, options.platform ?? 'universal', options.lang ?? undefined, options.preserveExtension ?? true));
+    return call(() => native.sanitizeFilename(text, options.separator ?? '_', optionalSize('maxLength', options.maxLength) ?? 255, options.platform ?? 'universal', options.lang ?? undefined, options.preserveExtension ?? true));
 }
 // ── Key-derivation presets ──────────────────────────────────────────────────
 /**
@@ -446,7 +556,7 @@ function skeletonKey(text, options = {}) {
  * equal.
  */
 function editDistance(a, b) {
-    return native.editDistance(a, b);
+    return call(() => native.editDistance(a, b));
 }
 /**
  * The candidate closest to `value`, with its distance, or `null` beyond `maxDistance`
@@ -454,11 +564,12 @@ function editDistance(a, b) {
  * and ties go to the first candidate at the lowest distance (#894).
  */
 function nearestMatch(value, candidates, options = {}) {
-    return call(() => native.nearestMatch(value, candidates, options.maxDistance ?? 1)) ?? null;
+    return (call(() => native.nearestMatch(value, candidates, optionalSize('maxDistance', options.maxDistance) ?? 1)) ?? null);
 }
 /**
- * ML/NLP normalization: NFKC → emoji→text → transliterate → strip accents →
- * [case fold] → strip control → strip zero-width → collapse whitespace.
+ * ML/NLP normalization: resolve deletions → NFKC → emoji→text → transliterate →
+ * strip accents → emoji→text → [case fold] → strip control → strip zero-width →
+ * collapse whitespace → NFC.
  *
  * Note this folds no confusables — it is not a homoglyph defence at any setting. Put
  * {@link normalizeConfusables} in front of it when a model needs both.
@@ -469,28 +580,28 @@ function mlNormalize(text, options = {}) {
 // ── Grapheme clusters ───────────────────────────────────────────────────────
 /** Number of grapheme clusters (user-perceived characters). */
 function graphemeLen(text) {
-    return native.graphemeLen(text);
+    return call(() => native.graphemeLen(text));
 }
 /** Split `text` into grapheme-cluster strings. */
 function graphemeSplit(text) {
-    return native.graphemeSplit(text);
+    return call(() => native.graphemeSplit(text));
 }
 /** Truncate to at most `maxGraphemes` clusters, never cutting through one. */
 function graphemeTruncate(text, maxGraphemes) {
-    return call(() => native.graphemeTruncate(text, maxGraphemes));
+    return call(() => native.graphemeTruncate(text, size('maxGraphemes', maxGraphemes)));
 }
 /** Display width (terminal columns) of a single grapheme `cluster` by East Asian Width. */
 function graphemeWidth(cluster, options = {}) {
-    return native.graphemeWidth(cluster, options.ambiguousWide ?? false);
+    return call(() => native.graphemeWidth(cluster, options.ambiguousWide ?? false));
 }
 /** Total display width (terminal columns) of `text`. */
 function terminalWidth(text, options = {}) {
-    return native.terminalWidth(text, options.ambiguousWide ?? false);
+    return call(() => native.terminalWidth(text, options.ambiguousWide ?? false));
 }
 // ── Hostname / script analysis ──────────────────────────────────────────────
 /** Whether the hostname looks like a mixed-script / confusable IDN spoof (a `false` is not a safety guarantee). */
 function isSuspiciousHostname(host) {
-    return native.isSuspiciousHostname(host);
+    return call(() => native.isSuspiciousHostname(host));
 }
 /**
  * Analyze a hostname for Unicode homoglyph spoofing, returning the full
@@ -502,11 +613,11 @@ function analyzeHostname(host, options = {}) {
 }
 /** The Unicode scripts present, in first-appearance order (Common/Inherited excluded). */
 function detectScripts(text) {
-    return native.detectScripts(text);
+    return call(() => native.detectScripts(text));
 }
 /** Whether `text` mixes characters from more than one script. */
 function isMixedScript(text) {
-    return native.isMixedScript(text);
+    return call(() => native.isMixedScript(text));
 }
 /**
  * All twelve UAX #9 explicit formatting characters, uncontexted.
@@ -517,7 +628,7 @@ function isMixedScript(text) {
  * right-to-left text.
  */
 function hasBidiControl(text) {
-    return native.hasBidiControl(text);
+    return call(() => native.hasBidiControl(text));
 }
 /**
  * Whether `text` mixes strong left-to-right and strong right-to-left characters
@@ -526,11 +637,11 @@ function hasBidiControl(text) {
  * guarantee.
  */
 function hasBidiConflict(text) {
-    return native.hasBidiConflict(text);
+    return call(() => native.hasBidiConflict(text));
 }
 /** Explain how `lang: 'auto'` detection resolves `text`. */
 function inspectAutoLang(text) {
-    return native.inspectAutoLang(text);
+    return call(() => native.inspectAutoLang(text));
 }
 // ── Metadata introspection (#404) ───────────────────────────────────────────
 /**
@@ -572,7 +683,7 @@ function confusableCoverage(script) {
  * because it decides whether disarm's normalization agrees with the host platform's.
  */
 function unicodeVersion() {
-    return native.unicodeVersion();
+    return call(() => native.unicodeVersion());
 }
 /**
  * Whether a key stored under an earlier release still compares equal. A monotonic
@@ -580,7 +691,7 @@ function unicodeVersion() {
  * for the same input. Meaningless in isolation, by design.
  */
 function keySchemaVersion() {
-    return native.keySchemaVersion();
+    return call(() => native.keySchemaVersion());
 }
 /**
  * The Unicode `confusables.txt` release the bundled confusable tables were folded
@@ -591,15 +702,15 @@ function keySchemaVersion() {
  * confusables fold stale?" without inferring it from behaviour.
  */
 function confusablesVersion() {
-    return native.confusablesVersion();
+    return call(() => native.confusablesVersion());
 }
 /** Every Unicode script name known to the transliteration tables. */
 function listScripts() {
-    return native.listScripts();
+    return call(() => native.listScripts());
 }
 /** Every language code that has a context-aware transliteration profile. */
 function listContextLangs() {
-    return native.listContextLangs();
+    return call(() => native.listContextLangs());
 }
 // ── Anomaly detection ───────────────────────────────────────────────────────
 /**
@@ -611,10 +722,10 @@ function listContextLangs() {
  * internal set on every call — used only by the leet and segmentation branches.
  */
 function hasAnomalies(text, lexicon = []) {
-    if (lexicon instanceof binding_1.Lexicon) {
-        return native.hasAnomalies(text, lexicon);
+    if (lexicon instanceof Lexicon) {
+        return call(() => native.hasAnomalies(text, lexicon));
     }
-    return native.hasAnomalies(text, Array.isArray(lexicon) ? lexicon : [...lexicon]);
+    return call(() => native.hasAnomalies(text, Array.isArray(lexicon) ? lexicon : [...lexicon]));
 }
 /**
  * Full anomaly analysis: an `AnomalyReport` with `anomalous`, `kinds` (in
@@ -623,9 +734,8 @@ function hasAnomalies(text, lexicon = []) {
  * `lexicon` may be a `Set`/array of words or a prebuilt {@link Lexicon} handle.
  */
 function inspectAnomalies(text, lexicon = []) {
-    if (lexicon instanceof binding_1.Lexicon) {
-        return native.inspectAnomalies(text, lexicon);
+    if (lexicon instanceof Lexicon) {
+        return call(() => native.inspectAnomalies(text, lexicon));
     }
-    const words = Array.isArray(lexicon) ? lexicon : [...lexicon];
-    return native.inspectAnomalies(text, words);
+    return call(() => native.inspectAnomalies(text, Array.isArray(lexicon) ? lexicon : [...lexicon]));
 }