@sorisdk/matcher 0.6.9 → 0.6.11

package/README.md

@@ -121,6 +121,44 @@ per-entry limits remain independently enforced.
 
 If you want campaign events and browser recognition flow on top of matching, use `@sorisdk/web-audio`.
 
+## Audio-marker default policy (0.6.10)
+
+`session.detectAudioMarker(pcm16Le, actualSampleRate)` and
+`detectAudioMarkerWithLimits` now select the shared level-robust v1 policy.
+An empty config or waveform/search-only config also uses this default. No PCM
+amplification is applied: `score`, `syncScore`, `margin`, and runner-up scores
+remain in raw input-amplitude units. `confidence` uses the v1 calibration.
+
+Results keep the existing flat detection shape and add `levelPolicy`,
+`diagnostics`, `candidateEligible`, and `materialFallbackGuardEligible`.
+Eligibility flags come directly from the shared DSP. They do not authorize a
+marker hit: only a non-null accepted `code` is eligible for activity enrichment.
+The Web path does not apply extra legacy raw-score gates or implement native
+SDK temporal voting/material-fallback heuristics. Early JS input rejections
+include false eligibility flags and may omit DSP diagnostics.
+
+For compatibility, explicitly setting any of `minSyncScore`, `minScore`,
+`minMargin`, `minRatio`, `minConfidence`, or `minVotes` retains legacy behavior.
+Choose `levelPolicy` explicitly to override this compatibility rule:
+
+```ts
+await session.detectAudioMarker(pcm, rate, { levelPolicy: "legacy" });
+await session.detectAudioMarker(pcm, rate, {
+  levelPolicy: "levelRobust", minVotes: 2
+});
+```
+
+With explicit robust policy, shared v1 amplitude gates replace `minSyncScore`,
+`minScore`, and `minMargin`; waveform/search/codebook/vote parameters and stricter
+ratio/confidence requirements retain the shared Rust semantics. The generated
+low-level `detectAudioMarker` / `detectPatternMark` exports and their bounded
+variants remain legacy APIs; `detectAudioMarkerLevelRobust` returns the shared
+nested envelope. Rust, C, Python, and native Node legacy APIs are unchanged.
+
+Upgrade the JS package and its generated WASM together. A custom loader lacking
+the robust export fails with an upgrade error on the default path; it never
+silently downgrades. An explicit legacy config remains supported with old WASM.
+
 ## Audio-marker detection limits
 
 `MatcherSession.detectAudioMarker(...)` preserves its existing signature and
@@ -149,7 +187,9 @@ const detection = await session.detectAudioMarkerWithLimits(
 ```
 
 The generated WASM module exposes the corresponding
-`detectAudioMarkerWithLimits` function and method. It inspects the JavaScript
+`detectAudioMarkerWithLimits` legacy function and method, and the robust
+`detectAudioMarkerLevelRobust(pcm, rate, config, limits)` function. The session
+selects the correct export from the policy above. Each inspects the JavaScript
 `Uint8Array` length before allocating a Rust-owned copy. Raising these budgets
 permits greater memory and CPU use; it does not protect an untrusted host after
 the caller opts into the larger envelope.

package/dist/generated/core.d.ts

@@ -22,6 +22,7 @@ export class WasmMatcherEngine {
     free(): void;
     [Symbol.dispose](): void;
     bestMatch(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    bestMatchChecked(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
     bestMatchWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     detectAudioMarker(pcm16_le: Uint8Array, sample_rate: number, config?: any | null): any;
     detectAudioMarkerWithLimits(pcm16_le: Uint8Array, sample_rate: number, config?: any | null, limits?: any | null): any;
@@ -33,6 +34,7 @@ export class WasmMatcherEngine {
     extractPitchReference(pcm16_le: Uint8Array, sample_rate: number): any;
     extractSpectralShiftReference(pcm16_le: Uint8Array, sample_rate: number): any;
     matchQuery(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
+    matchQueryChecked(database: WasmMatcherDatabase, query: Uint8Array, config?: any | null): any;
     matchQueryWithVariants(database: WasmMatcherDatabase, query: Uint8Array, pitch_query: any, config?: any | null, variant_config?: any | null): any;
     constructor();
     /**

package/dist/generated/core_bg.js

@@ -170,6 +170,22 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any | null} [config]
+     * @returns {any}
+     */
+    bestMatchChecked(database, query, config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_bestMatchChecked(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, isLikeNone(config) ? 0 : addToExternrefTable0(config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {WasmMatcherDatabase} database
      * @param {Uint8Array} query
@@ -335,6 +351,22 @@ export class WasmMatcherEngine {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * @param {WasmMatcherDatabase} database
+     * @param {Uint8Array} query
+     * @param {any | null} [config]
+     * @returns {any}
+     */
+    matchQueryChecked(database, query, config) {
+        _assertClass(database, WasmMatcherDatabase);
+        const ptr0 = passArray8ToWasm0(query, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmatcherengine_matchQueryChecked(this.__wbg_ptr, database.__wbg_ptr, ptr0, len0, isLikeNone(config) ? 0 : addToExternrefTable0(config));
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {WasmMatcherDatabase} database
      * @param {Uint8Array} query

package/dist/generated/core_bg.wasm.d.ts

@@ -25,6 +25,7 @@ export const wasmmatcherdatabase_new: () => number;
 export const wasmmatcherdatabase_removeEntry: (a: number, b: number, c: number) => [number, number];
 export const wasmmatcherdatabase_setEntryVariantMetadata: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const wasmmatcherengine_bestMatch: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_bestMatchChecked: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const wasmmatcherengine_bestMatchWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
 export const wasmmatcherengine_detectAudioMarker: (a: number, b: any, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_detectAudioMarkerWithLimits: (a: number, b: any, c: number, d: number, e: number) => [number, number, number];
@@ -35,9 +36,10 @@ export const wasmmatcherengine_estimatePitchRatioAgainstSpectralFeatures: (a: nu
 export const wasmmatcherengine_extractPitchReference: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_extractSpectralShiftReference: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const wasmmatcherengine_matchQuery: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+export const wasmmatcherengine_matchQueryChecked: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const wasmmatcherengine_matchQueryWithVariants: (a: number, b: number, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
-export const wasmmatcherengine_resetDistinctMatchState: (a: number) => void;
 export const wasmmatcherengine_new: () => number;
+export const wasmmatcherengine_resetDistinctMatchState: (a: number) => void;
 export const init_matcher_wasm: () => void;
 export const detectPatternMark: (a: any, b: number, c: number) => [number, number, number];
 export const wasmmatcherengine_detectPatternMark: (a: number, b: any, c: number, d: number) => [number, number, number];

package/dist/index.d.ts

@@ -20,7 +20,10 @@ declare const DEFAULT_MAX_AUDIO_MARKER_WORK_UNITS = 1000000000;
 declare const AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON = "pcm_input_budget_exceeded";
 declare const AUDIO_MARKER_WORK_BUDGET_EXCEEDED_REASON = "detector_work_budget_exceeded";
 declare const AUDIO_MARKER_WORK_OVERFLOW_REASON = "detector_work_overflow";
+type AudioMarkerLevelPolicy = "levelRobust" | "legacy";
 interface AudioMarkerConfig {
+    /** Defaults to levelRobust; explicit thresholds retain legacy semantics unless overridden. */
+    levelPolicy?: AudioMarkerLevelPolicy;
     bandLowHz?: number;
     bandHighHz?: number;
     syncDurationMillis?: number;
@@ -43,7 +46,31 @@ interface AudioMarkerLimits {
     maxDurationMillis?: number;
     maxWorkUnits?: number;
 }
+/** Shared v1 diagnostics; levels are band estimates, not calibrated SPL or SNR. */
+interface AudioMarkerLevelDiagnostics {
+    policyVersion: number;
+    markerBandDbfs: number;
+    lowerNeighborDbfs: number;
+    upperNeighborDbfs: number;
+    normalizationRms: number;
+    effectiveGain: number;
+    normalizedSyncScore: number;
+    normalizedScore: number;
+    normalizedMargin: number;
+    policyConfidence: number;
+    codeHalfBalance: number | null;
+    effectiveMinSyncScore: number;
+    effectiveMinScore: number;
+    effectiveMinMargin: number;
+    qualityReason: string | null;
+}
 interface AudioMarkerDetection {
+    /** Present on level-robust session results; raw score units below are unchanged. */
+    levelPolicy?: AudioMarkerLevelPolicy;
+    diagnostics?: AudioMarkerLevelDiagnostics;
+    /** Shared eligibility only; a candidate is not an accepted marker identity. */
+    candidateEligible?: boolean;
+    materialFallbackGuardEligible?: boolean;
     pattern?: string | null;
     code?: string | null;
     confidence?: number | null;
@@ -115,6 +142,24 @@ interface MatchResult {
     durationMillis?: number;
     afpType: AudioFingerprintType;
 }
+type TimingCoordinateSpace = "entry_local" | "segment_local" | "unavailable";
+type TimingUnavailableReason = "rejected_metadata" | "invalidated_metadata" | "incompatible_geometry" | "ambiguous_clock" | "out_of_range" | "window_origin_underflow" | "inconsistent_windows";
+interface MatchTiming {
+    coordinateSpace: TimingCoordinateSpace;
+    /** Null when timing normalization failed. */
+    positionMillis: number | null;
+    durationMillis: number | null;
+    segmentIndex: number | null;
+    reason: TimingUnavailableReason | null;
+}
+interface CheckedMatchResult {
+    name: string;
+    score: number;
+    afpType: AudioFingerprintType;
+    /** Diagnostic entry offset only; consumers should use timing. */
+    rawPositionMillis: number;
+    timing: MatchTiming;
+}
 interface VariantMatch {
     matchResult: MatchResult;
     variant: VariantDecision;
@@ -246,11 +291,17 @@ declare class MatcherSession {
     clear(): Promise<void>;
     getEntryMetadata(name: string): Promise<EntryMetadata | null>;
     match(query: Uint8Array, config?: MatchConfig): Promise<MatchResult[]>;
+    /**
+     * Read one observation with explicit timing coordinates. This direct accessor
+     * does not emit legacy match events or update recognition deduplication state.
+     */
+    bestMatchChecked(query: Uint8Array, config?: MatchConfig): Promise<CheckedMatchResult | null>;
     bestMatch(query: Uint8Array, config?: MatchConfig): Promise<MatchResult | null>;
     estimatePitchRatio(pcm16Le: Uint8Array, sampleRate: number): Promise<PitchRatioEstimate>;
     extractPitchReference(pcm16Le: Uint8Array, sampleRate: number): Promise<PitchReferenceEstimate>;
     estimatePitchRatioAgainstReference(pcm16Le: Uint8Array, sampleRate: number, referencePitchHz: number, referenceConfidence?: number | null): Promise<PitchRatioEstimate>;
     estimatePitchRatioAgainstReferenceFeatures(pcm16Le: Uint8Array, sampleRate: number, referenceFeatures: string, referencePositionMillis: number, referenceConfidence?: number | null): Promise<PitchRatioEstimate>;
+    /** Uses level-robust detection by default, preserving explicit legacy thresholds. */
     detectAudioMarker(pcm16Le: Uint8Array, sampleRate: number, config?: AudioMarkerConfig): Promise<AudioMarkerDetection>;
     /** Detect an audio marker with explicit limits for trusted offline input. */
     detectAudioMarkerWithLimits(pcm16Le: Uint8Array, sampleRate: number, config: AudioMarkerConfig | undefined, limits: AudioMarkerLimits): Promise<AudioMarkerDetection>;
@@ -276,4 +327,4 @@ declare function __resetMatcherWasmForTests(): void;
 /** Maximum gap between successful observations in one continuous material run. */
 declare const MATCH_CONTINUITY_GAP_MS = 30000;
 
-export { AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_OVERFLOW_REASON, AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, type AudioMarkerLimits, DEFAULT_MAX_AUDIO_MARKER_DURATION_MILLIS, DEFAULT_MAX_AUDIO_MARKER_PCM_BYTES, DEFAULT_MAX_AUDIO_MARKER_SAMPLES, DEFAULT_MAX_AUDIO_MARKER_WORK_UNITS, DEFAULT_MAX_PACK_BYTES, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, MATCH_CONTINUITY_GAP_MS, type MatchConfig, type MatchResult, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };
+export { AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_BUDGET_EXCEEDED_REASON, AUDIO_MARKER_WORK_OVERFLOW_REASON, AudioFingerprintType, type AudioMarkerCode, type AudioMarkerConfig, type AudioMarkerDetection, type AudioMarkerLevelDiagnostics, type AudioMarkerLevelPolicy, type AudioMarkerLimits, type CheckedMatchResult, DEFAULT_MAX_AUDIO_MARKER_DURATION_MILLIS, DEFAULT_MAX_AUDIO_MARKER_PCM_BYTES, DEFAULT_MAX_AUDIO_MARKER_SAMPLES, DEFAULT_MAX_AUDIO_MARKER_WORK_UNITS, DEFAULT_MAX_PACK_BYTES, type EntryMetadata, type InitMatcherOptions, type InitMatcherResult, MATCH_CONTINUITY_GAP_MS, type MatchConfig, type MatchResult, type MatchTiming, type MatcherEphemeralAuthOptions, type MatcherEphemeralAuthResult, type MatcherEphemeralKeyExchangeMetadata, type MatcherEphemeralKeyExchangeOptions, MatcherSession, type MatcherSessionEventMap, type MatcherSessionEventName, type MatcherSessionListener, type MatcherSessionOptions, type PackSource, type PitchRatioEstimate, type PitchReferenceEstimate, type TimingCoordinateSpace, type TimingUnavailableReason, type VariantDecision, type VariantDecisionStatus, type VariantMatch, type VariantMatchConfig, type VariantMatchQuery, __resetMatcherWasmForTests, __setMatcherEmbeddedPackForTests, __setMatcherWasmModuleForTests, initMatcher };

package/dist/index.js

@@ -478,6 +478,28 @@ var WrappedDatabase = class {
 var WrappedMatcher = class {
   constructor(inner) {
     this.inner = inner;
+    const findMatchesCheckedFn = getCallable(this.inner, [
+      "findMatchesChecked",
+      "find_matches_checked",
+      "matchQueryChecked",
+      "match_query_checked"
+    ]);
+    if (findMatchesCheckedFn) {
+      this.findMatchesChecked = (database, query, config) => {
+        const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+        const raw = findMatchesCheckedFn.call(this.inner, dbRecord, query, config);
+        if (!Array.isArray(raw)) throw new Error("Invalid checked match results");
+        return raw.map(normalizeCheckedResult);
+      };
+    }
+    const bestMatchCheckedFn = getCallable(this.inner, ["bestMatchChecked", "best_match_checked"]);
+    if (bestMatchCheckedFn) {
+      this.bestMatchChecked = (database, query, config) => {
+        const dbRecord = typeof database.raw === "function" ? database.raw() : database;
+        const raw = bestMatchCheckedFn.call(this.inner, dbRecord, query, config);
+        return raw == null ? null : normalizeCheckedResult(raw);
+      };
+    }
     const estimatePitchRatioFn = getCallable(this.inner, [
       "estimatePitchRatio",
       "estimate_pitch_ratio"
@@ -555,6 +577,8 @@ var WrappedMatcher = class {
     }
   }
   inner;
+  findMatchesChecked;
+  bestMatchChecked;
   estimatePitchRatio;
   extractPitchReference;
   estimatePitchRatioAgainstReference;
@@ -645,6 +669,56 @@ function normalizeResult(raw) {
   }
   return result;
 }
+var TIMING_UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([
+  "rejected_metadata",
+  "invalidated_metadata",
+  "incompatible_geometry",
+  "ambiguous_clock",
+  "out_of_range",
+  "window_origin_underflow",
+  "inconsistent_windows"
+]);
+function normalizeCheckedResult(raw) {
+  const invalid = () => new Error("Invalid checked match result");
+  if (!raw || typeof raw !== "object") {
+    throw invalid();
+  }
+  const record = raw;
+  if (!record.timing || typeof record.timing !== "object") {
+    throw invalid();
+  }
+  const source = record.timing;
+  const integer = (camel, snake) => {
+    const value = camel ?? snake;
+    if (value == null) return null;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      throw invalid();
+    }
+    return value;
+  };
+  const coordinateSpace = source.coordinateSpace ?? source.coordinate_space;
+  const timing = {
+    coordinateSpace,
+    positionMillis: integer(source.positionMillis, source.position_millis),
+    durationMillis: integer(source.durationMillis, source.duration_millis),
+    segmentIndex: integer(source.segmentIndex, source.segment_index),
+    reason: source.reason ?? null
+  };
+  const available = timing.reason === null && timing.positionMillis !== null;
+  const validTiming = coordinateSpace === "unavailable" ? timing.positionMillis === null && timing.durationMillis === null && timing.segmentIndex === null && TIMING_UNAVAILABLE_REASONS.has(timing.reason) : coordinateSpace === "entry_local" ? available && timing.durationMillis === null && timing.segmentIndex === null : coordinateSpace === "segment_local" && available && timing.durationMillis !== null && timing.segmentIndex !== null && timing.positionMillis < timing.durationMillis;
+  const rawPositionMillis = integer(record.rawPositionMillis, record.raw_position_millis);
+  const afpType = record.afpType ?? record.afp_type;
+  if (!validTiming || typeof record.name !== "string" || record.name.length === 0 || typeof record.score !== "number" || !Number.isFinite(record.score) || record.score < 0 || ![1, 2, 4].includes(afpType) || rawPositionMillis === null) {
+    throw invalid();
+  }
+  return {
+    name: record.name,
+    score: record.score,
+    afpType,
+    rawPositionMillis,
+    timing
+  };
+}
 function normalizeVariantMatch(raw) {
   const rawMatch = raw.matchResult ?? raw.match;
   const rawVariant = raw.variant ?? {};
@@ -715,6 +789,19 @@ function normalizeAudioMarkerDetection(raw) {
     runnerUpAccuracy: normalizeOptionalNumber(record.runnerUpAccuracy, record.runner_up_accuracy)
   };
 }
+function normalizeLevelRobustDetection(raw) {
+  const envelope = raw;
+  if (!envelope || typeof envelope.detection !== "object" || !envelope.detection || typeof envelope.diagnostics !== "object" || !envelope.diagnostics || typeof envelope.candidateEligible !== "boolean" || typeof envelope.materialFallbackGuardEligible !== "boolean") {
+    throw new Error("Invalid level-robust marker result envelope");
+  }
+  return {
+    ...normalizeAudioMarkerDetection(envelope.detection),
+    levelPolicy: "levelRobust",
+    diagnostics: { ...envelope.diagnostics },
+    candidateEligible: envelope.candidateEligible,
+    materialFallbackGuardEligible: envelope.materialFallbackGuardEligible
+  };
+}
 function isMapLike(raw) {
   return raw instanceof Map || Object.prototype.toString.call(raw) === "[object Map]" && typeof raw.entries === "function";
 }
@@ -782,6 +869,10 @@ function createBindingsFromModule(moduleLike) {
     "estimatePitchRatioAgainstReferenceFeatures",
     "estimate_pitch_ratio_against_reference_features"
   ]);
+  const detectAudioMarkerLevelRobustFn = resolveFactory(mod, [
+    "detectAudioMarkerLevelRobust",
+    "detect_audio_marker_level_robust"
+  ]);
   const detectAudioMarkerFn = resolveFactory(mod, [
     "detectAudioMarker",
     "detect_audio_marker",
@@ -926,6 +1017,26 @@ function createBindingsFromModule(moduleLike) {
         destroy?.call(matcher);
       }
     },
+    detectAudioMarkerLevelRobust(pcm16Le, sampleRate, config, limits) {
+      if (detectAudioMarkerLevelRobustFn) {
+        return normalizeLevelRobustDetection(
+          detectAudioMarkerLevelRobustFn(pcm16Le, sampleRate, config, limits)
+        );
+      }
+      const matcher = createMatcherFactory ? createMatcherFactory() : new MatcherCtor();
+      try {
+        const fn = getCallable(matcher, [
+          "detectAudioMarkerLevelRobust",
+          "detect_audio_marker_level_robust"
+        ]);
+        if (!fn) {
+          throw new Error("WASM matcher is missing detectAudioMarkerLevelRobust; upgrade the WASM assets or explicitly select levelPolicy: legacy");
+        }
+        return normalizeLevelRobustDetection(fn.call(matcher, pcm16Le, sampleRate, config, limits));
+      } finally {
+        getCallable(matcher, ["destroy", "free"])?.call(matcher);
+      }
+    },
     detectAudioMarkerWithLimits(pcm16Le, sampleRate, config, limits) {
       if (detectAudioMarkerWithLimitsFn) {
         return normalizeAudioMarkerDetection(
@@ -970,6 +1081,42 @@ async function getBindings(options) {
 function toUint8ArrayCopy(input) {
   return new Uint8Array(input);
 }
+var typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+var typedArrayByteLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength").get;
+var typedArrayTag = Object.getOwnPropertyDescriptor(typedArrayPrototype, Symbol.toStringTag).get;
+var typedArraySet = Uint8Array.prototype.set;
+function markerByteLength(input) {
+  if (typedArrayTag.call(input) !== "Uint8Array") {
+    throw new TypeError("Audio marker PCM must be a Uint8Array");
+  }
+  return typedArrayByteLength.call(input);
+}
+function copyMarkerPcm(input) {
+  const copy = new Uint8Array(markerByteLength(input));
+  typedArraySet.call(copy, input);
+  return copy;
+}
+function usesLevelRobust(config) {
+  if (config?.levelPolicy !== void 0) {
+    if (config.levelPolicy !== "levelRobust" && config.levelPolicy !== "legacy") {
+      throw new RangeError("Invalid audio marker levelPolicy");
+    }
+    return config.levelPolicy === "levelRobust";
+  }
+  return ![
+    config?.minSyncScore,
+    config?.minScore,
+    config?.minMargin,
+    config?.minRatio,
+    config?.minConfidence,
+    config?.minVotes
+  ].some((value) => value !== void 0);
+}
+function detectorConfig(config) {
+  if (!config || config.levelPolicy === void 0) return config;
+  const { levelPolicy: _policy, ...rest } = config;
+  return rest;
+}
 function resolveAudioMarkerLimits(limits) {
   const resolved = {
     maxPcmBytes: limits?.maxPcmBytes ?? DEFAULT_MAX_AUDIO_MARKER_PCM_BYTES,
@@ -985,13 +1132,17 @@ function resolveAudioMarkerLimits(limits) {
   return resolved;
 }
 function audioMarkerInputFailureReason(pcm16Le, sampleRate, limits) {
-  if (pcm16Le.byteLength > limits.maxPcmBytes) {
+  const byteLength = markerByteLength(pcm16Le);
+  if (byteLength > limits.maxPcmBytes) {
     return AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON;
   }
-  if (pcm16Le.byteLength % 2 !== 0) {
+  if (byteLength % 2 !== 0) {
     return "invalid_pcm16_byte_length";
   }
-  const sampleCount = pcm16Le.byteLength / 2;
+  if (!Number.isInteger(sampleRate) || sampleRate <= 0 || sampleRate > 4294967295) {
+    return "invalid_sample_rate";
+  }
+  const sampleCount = byteLength / 2;
   if (sampleCount > limits.maxSamples) {
     return AUDIO_MARKER_INPUT_BUDGET_EXCEEDED_REASON;
   }
@@ -1188,6 +1339,26 @@ var MatcherSession = class {
       handleError(this.events, "match", error);
     }
   }
+  /**
+   * Read one observation with explicit timing coordinates. This direct accessor
+   * does not emit legacy match events or update recognition deduplication state.
+   */
+  async bestMatchChecked(query, config) {
+    const generation = this.recognitionGeneration;
+    try {
+      await this.ensureLiveReady();
+      if (generation !== this.recognitionGeneration) return null;
+      const safeQuery = toUint8ArrayCopy(query);
+      const matcher = this.matcherOrThrow();
+      if (!matcher.bestMatchChecked) {
+        throw new Error("WASM matcher is missing bestMatchChecked; upgrade the WASM assets");
+      }
+      if (generation !== this.recognitionGeneration || this.destroyed) return null;
+      return matcher.bestMatchChecked(this.databaseOrThrow(), safeQuery, config);
+    } catch (error) {
+      handleError(this.events, "bestMatchChecked", error);
+    }
+  }
   async bestMatch(query, config) {
     const generation = this.recognitionGeneration;
     try {
@@ -1293,15 +1464,24 @@ var MatcherSession = class {
       handleError(this.events, "estimatePitchRatioAgainstReferenceFeatures", error);
     }
   }
+  /** Uses level-robust detection by default, preserving explicit legacy thresholds. */
   async detectAudioMarker(pcm16Le, sampleRate, config) {
     try {
       await this.ensureLiveReady();
+      const robust = usesLevelRobust(config);
       const limits = resolveAudioMarkerLimits();
       const failureReason = audioMarkerInputFailureReason(pcm16Le, sampleRate, limits);
       if (failureReason) {
-        return absentAudioMarkerDetection(config, failureReason);
+        return {
+          ...absentAudioMarkerDetection(config, failureReason),
+          ...robust ? { levelPolicy: "levelRobust", candidateEligible: false, materialFallbackGuardEligible: false } : {}
+        };
+      }
+      const safePcm = copyMarkerPcm(pcm16Le);
+      config = detectorConfig(config);
+      if (robust) {
+        return this.bindings.detectAudioMarkerLevelRobust(safePcm, sampleRate, config);
       }
-      const safePcm = toUint8ArrayCopy(pcm16Le);
       const matcher = this.matcherOrThrow();
       if (matcher.detectAudioMarker) {
         return matcher.detectAudioMarker(safePcm, sampleRate, config);
@@ -1318,6 +1498,7 @@ var MatcherSession = class {
   async detectAudioMarkerWithLimits(pcm16Le, sampleRate, config, limits) {
     try {
       await this.ensureLiveReady();
+      const robust = usesLevelRobust(config);
       const resolvedLimits = resolveAudioMarkerLimits(limits);
       const failureReason = audioMarkerInputFailureReason(
         pcm16Le,
@@ -1325,9 +1506,16 @@ var MatcherSession = class {
         resolvedLimits
       );
       if (failureReason) {
-        return absentAudioMarkerDetection(config, failureReason);
+        return {
+          ...absentAudioMarkerDetection(config, failureReason),
+          ...robust ? { levelPolicy: "levelRobust", candidateEligible: false, materialFallbackGuardEligible: false } : {}
+        };
+      }
+      const safePcm = copyMarkerPcm(pcm16Le);
+      config = detectorConfig(config);
+      if (robust) {
+        return this.bindings.detectAudioMarkerLevelRobust(safePcm, sampleRate, config, resolvedLimits);
       }
-      const safePcm = toUint8ArrayCopy(pcm16Le);
       const matcher = this.matcherOrThrow();
       if (matcher.detectAudioMarkerWithLimits) {
         return matcher.detectAudioMarkerWithLimits(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/matcher",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "Browser WASM SDK for audio fingerprint matching",
   "type": "module",
   "main": "./dist/index.js",