@sorisdk/matcher 0.6.9 → 0.6.10

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/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;
@@ -251,6 +278,7 @@ declare class MatcherSession {
     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 +304,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, 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 };

package/dist/index.js

@@ -715,6 +715,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 +795,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 +943,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 +1007,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 +1058,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;
   }
@@ -1293,15 +1370,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 +1404,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 +1412,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.10",
   "description": "Browser WASM SDK for audio fingerprint matching",
   "type": "module",
   "main": "./dist/index.js",