@fabricorg/experiments-assignment 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+// src/hash.ts
+function murmur3_x86_32(key, seed = 0) {
+  const data = utf8Bytes(key);
+  const len = data.length;
+  const nblocks = len >>> 2;
+  let h1 = seed >>> 0;
+  const c1 = 3432918353;
+  const c2 = 461845907;
+  for (let i = 0; i < nblocks; i++) {
+    const o = i * 4;
+    let k12 = data[o] & 255 | (data[o + 1] & 255) << 8 | (data[o + 2] & 255) << 16 | (data[o + 3] & 255) << 24;
+    k12 = mul32(k12, c1);
+    k12 = rotl32(k12, 15);
+    k12 = mul32(k12, c2);
+    h1 ^= k12;
+    h1 = rotl32(h1, 13);
+    h1 = mul32(h1, 5) + 3864292196 >>> 0;
+  }
+  let k1 = 0;
+  const tail = len & 3;
+  const tailStart = nblocks * 4;
+  if (tail >= 3) k1 ^= (data[tailStart + 2] & 255) << 16;
+  if (tail >= 2) k1 ^= (data[tailStart + 1] & 255) << 8;
+  if (tail >= 1) {
+    k1 ^= data[tailStart] & 255;
+    k1 = mul32(k1, c1);
+    k1 = rotl32(k1, 15);
+    k1 = mul32(k1, c2);
+    h1 ^= k1;
+  }
+  h1 ^= len;
+  h1 = fmix32(h1);
+  return h1 >>> 0;
+}
+function rotl32(x, r) {
+  return (x << r | x >>> 32 - r) >>> 0;
+}
+function mul32(a, b) {
+  const aHi = a >>> 16 & 65535;
+  const aLo = a & 65535;
+  const bHi = b >>> 16 & 65535;
+  const bLo = b & 65535;
+  return aLo * bLo + (aHi * bLo + aLo * bHi << 16 >>> 0 | 0) >>> 0 >>> 0;
+}
+function fmix32(h) {
+  let x = h >>> 0;
+  x ^= x >>> 16;
+  x = mul32(x, 2246822507);
+  x ^= x >>> 13;
+  x = mul32(x, 3266489909);
+  x ^= x >>> 16;
+  return x >>> 0;
+}
+function utf8Bytes(s) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s);
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i);
+    if (c < 128) {
+      out.push(c);
+    } else if (c < 2048) {
+      out.push(192 | c >> 6, 128 | c & 63);
+    } else if (c >= 55296 && c <= 56319 && i + 1 < s.length) {
+      const c2 = s.charCodeAt(i + 1);
+      if (c2 >= 56320 && c2 <= 57343) {
+        c = 65536 + ((c & 1023) << 10 | c2 & 1023);
+        i++;
+        out.push(
+          240 | c >> 18,
+          128 | c >> 12 & 63,
+          128 | c >> 6 & 63,
+          128 | c & 63
+        );
+      }
+    } else {
+      out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+    }
+  }
+  return new Uint8Array(out);
+}
+
+// src/bucket.ts
+var BUCKET_PRECISION = 1e4;
+function bucketFor(experimentId, salt, subjectId) {
+  const key = `${experimentId}:${salt}:${subjectId}`;
+  return murmur3_x86_32(key) % BUCKET_PRECISION;
+}
+
+// src/assign.ts
+function assign(args) {
+  const bucket = bucketFor(args.experimentId, args.salt, args.subjectId);
+  if (args.forcedVariantKey && args.variants.some((v) => v.key === args.forcedVariantKey)) {
+    return { variantKey: args.forcedVariantKey, bucket, reason: "forced" };
+  }
+  if (args.stickyVariantKey && args.variants.some((v) => v.key === args.stickyVariantKey)) {
+    return { variantKey: args.stickyVariantKey, bucket, reason: "sticky" };
+  }
+  const sampleRate = args.sampleRate ?? 1;
+  if (sampleRate < 1) {
+    const sampleBucket = bucketFor(`${args.experimentId}:sample`, args.salt, args.subjectId) / BUCKET_PRECISION;
+    if (sampleBucket >= sampleRate) {
+      return { variantKey: null, bucket, reason: "ineligible" };
+    }
+  }
+  const totalDeclared = args.variants.reduce((s, v) => s + (v.weight ?? 0), 0);
+  if (totalDeclared > 0) {
+    if (totalDeclared !== BUCKET_PRECISION) {
+      throw new Error(
+        `experiment ${args.experimentId}: variant weights must sum to ${BUCKET_PRECISION}, got ${totalDeclared}`
+      );
+    }
+    let cumulative = 0;
+    for (const v of args.variants) {
+      cumulative += v.weight ?? 0;
+      if (bucket < cumulative) return { variantKey: v.key, bucket, reason: "eligible" };
+    }
+    return {
+      variantKey: args.variants[args.variants.length - 1].key,
+      bucket,
+      reason: "eligible"
+    };
+  }
+  const idx = Math.floor(bucket / BUCKET_PRECISION * args.variants.length);
+  const safeIdx = Math.min(idx, args.variants.length - 1);
+  return { variantKey: args.variants[safeIdx].key, bucket, reason: "eligible" };
+}
+
+exports.BUCKET_PRECISION = BUCKET_PRECISION;
+exports.assign = assign;
+exports.bucketFor = bucketFor;
+exports.murmur3_x86_32 = murmur3_x86_32;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/bucket.ts","../src/assign.ts"],"names":["k1"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * MurmurHash3 x86 32-bit. The deterministic bucketing primitive for every\n * Fabric Experiments SDK. See docs/adr/0001-assignment-hash.md.\n *\n * Inputs are hashed as their UTF-8 byte representation.\n * Output is treated as uint32 (sign-fixed via `>>> 0`).\n */\nexport function murmur3_x86_32(key: string, seed = 0): number {\n  const data = utf8Bytes(key);\n  const len = data.length;\n  const nblocks = len >>> 2;\n  let h1 = seed >>> 0;\n  const c1 = 0xcc9e2d51;\n  const c2 = 0x1b873593;\n\n  for (let i = 0; i < nblocks; i++) {\n    const o = i * 4;\n    let k1 =\n      (data[o]! & 0xff) |\n      ((data[o + 1]! & 0xff) << 8) |\n      ((data[o + 2]! & 0xff) << 16) |\n      ((data[o + 3]! & 0xff) << 24);\n\n    k1 = mul32(k1, c1);\n    k1 = rotl32(k1, 15);\n    k1 = mul32(k1, c2);\n\n    h1 ^= k1;\n    h1 = rotl32(h1, 13);\n    h1 = (mul32(h1, 5) + 0xe6546b64) >>> 0;\n  }\n\n  let k1 = 0;\n  const tail = len & 3;\n  const tailStart = nblocks * 4;\n  if (tail >= 3) k1 ^= (data[tailStart + 2]! & 0xff) << 16;\n  if (tail >= 2) k1 ^= (data[tailStart + 1]! & 0xff) << 8;\n  if (tail >= 1) {\n    k1 ^= data[tailStart]! & 0xff;\n    k1 = mul32(k1, c1);\n    k1 = rotl32(k1, 15);\n    k1 = mul32(k1, c2);\n    h1 ^= k1;\n  }\n\n  h1 ^= len;\n  h1 = fmix32(h1);\n  return h1 >>> 0;\n}\n\nfunction rotl32(x: number, r: number): number {\n  return ((x << r) | (x >>> (32 - r))) >>> 0;\n}\n\nfunction mul32(a: number, b: number): number {\n  const aHi = (a >>> 16) & 0xffff;\n  const aLo = a & 0xffff;\n  const bHi = (b >>> 16) & 0xffff;\n  const bLo = b & 0xffff;\n  return ((aLo * bLo + ((((aHi * bLo + aLo * bHi) << 16) >>> 0) | 0)) >>> 0) >>> 0;\n}\n\nfunction fmix32(h: number): number {\n  let x = h >>> 0;\n  x ^= x >>> 16;\n  x = mul32(x, 0x85ebca6b);\n  x ^= x >>> 13;\n  x = mul32(x, 0xc2b2ae35);\n  x ^= x >>> 16;\n  return x >>> 0;\n}\n\nfunction utf8Bytes(s: string): Uint8Array {\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(s);\n  // Fallback for environments without TextEncoder.\n  const out: number[] = [];\n  for (let i = 0; i < s.length; i++) {\n    let c = s.charCodeAt(i);\n    if (c < 0x80) {\n      out.push(c);\n    } else if (c < 0x800) {\n      out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));\n    } else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {\n      const c2 = s.charCodeAt(i + 1);\n      if (c2 >= 0xdc00 && c2 <= 0xdfff) {\n        c = 0x10000 + (((c & 0x3ff) << 10) | (c2 & 0x3ff));\n        i++;\n        out.push(\n          0xf0 | (c >> 18),\n          0x80 | ((c >> 12) & 0x3f),\n          0x80 | ((c >> 6) & 0x3f),\n          0x80 | (c & 0x3f),\n        );\n      }\n    } else {\n      out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));\n    }\n  }\n  return new Uint8Array(out);\n}\n","import { murmur3_x86_32 } from './hash.js';\n\nexport const BUCKET_PRECISION = 10000 as const;\n\n/**\n * Returns an integer in [0, BUCKET_PRECISION) deterministic in (experimentId, salt, subjectId).\n * Contract: see docs/adr/0001-assignment-hash.md.\n */\nexport function bucketFor(experimentId: string, salt: string, subjectId: string): number {\n  const key = `${experimentId}:${salt}:${subjectId}`;\n  return murmur3_x86_32(key) % BUCKET_PRECISION;\n}\n","import { BUCKET_PRECISION, bucketFor } from './bucket.js';\n\nexport interface ManifestVariant {\n  key: string;\n  /** Optional explicit weight; if any variant declares one, weights of all others are required. */\n  weight?: number;\n}\n\nexport interface AssignArgs {\n  experimentId: string;\n  salt: string;\n  subjectId: string;\n  variants: readonly ManifestVariant[];\n  /** Sample rate in [0, 1] of eligible traffic the experiment applies to. */\n  sampleRate?: number;\n  /** Pre-existing sticky assignment — if set and matches a current variant, returned as-is. */\n  stickyVariantKey?: string;\n  /** Forced override (preview / QA). Highest priority. */\n  forcedVariantKey?: string;\n}\n\nexport type AssignmentReason = 'eligible' | 'sticky' | 'forced' | 'ineligible';\n\nexport interface AssignmentResult {\n  variantKey: string | null;\n  bucket: number;\n  reason: AssignmentReason;\n}\n\n/**\n * Returns deterministic assignment for a subject. `null` variant + reason `ineligible`\n * means the subject was sampled out and the SDK must NOT log an exposure.\n */\nexport function assign(args: AssignArgs): AssignmentResult {\n  const bucket = bucketFor(args.experimentId, args.salt, args.subjectId);\n\n  if (args.forcedVariantKey && args.variants.some((v) => v.key === args.forcedVariantKey)) {\n    return { variantKey: args.forcedVariantKey, bucket, reason: 'forced' };\n  }\n\n  if (args.stickyVariantKey && args.variants.some((v) => v.key === args.stickyVariantKey)) {\n    return { variantKey: args.stickyVariantKey, bucket, reason: 'sticky' };\n  }\n\n  const sampleRate = args.sampleRate ?? 1;\n  if (sampleRate < 1) {\n    // Use a separate hash-derived value for sampling so it's independent of variant assignment.\n    const sampleBucket =\n      bucketFor(`${args.experimentId}:sample`, args.salt, args.subjectId) / BUCKET_PRECISION;\n    if (sampleBucket >= sampleRate) {\n      return { variantKey: null, bucket, reason: 'ineligible' };\n    }\n  }\n\n  const totalDeclared = args.variants.reduce((s, v) => s + (v.weight ?? 0), 0);\n  if (totalDeclared > 0) {\n    if (totalDeclared !== BUCKET_PRECISION) {\n      throw new Error(\n        `experiment ${args.experimentId}: variant weights must sum to ${BUCKET_PRECISION}, got ${totalDeclared}`,\n      );\n    }\n    let cumulative = 0;\n    for (const v of args.variants) {\n      cumulative += v.weight ?? 0;\n      if (bucket < cumulative) return { variantKey: v.key, bucket, reason: 'eligible' };\n    }\n    // Numerical safety net.\n    return {\n      variantKey: args.variants[args.variants.length - 1]!.key,\n      bucket,\n      reason: 'eligible',\n    };\n  }\n\n  // Even split.\n  const idx = Math.floor((bucket / BUCKET_PRECISION) * args.variants.length);\n  const safeIdx = Math.min(idx, args.variants.length - 1);\n  return { variantKey: args.variants[safeIdx]!.key, bucket, reason: 'eligible' };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+/**
+ * MurmurHash3 x86 32-bit. The deterministic bucketing primitive for every
+ * Fabric Experiments SDK. See docs/adr/0001-assignment-hash.md.
+ *
+ * Inputs are hashed as their UTF-8 byte representation.
+ * Output is treated as uint32 (sign-fixed via `>>> 0`).
+ */
+declare function murmur3_x86_32(key: string, seed?: number): number;
+
+declare const BUCKET_PRECISION: 10000;
+/**
+ * Returns an integer in [0, BUCKET_PRECISION) deterministic in (experimentId, salt, subjectId).
+ * Contract: see docs/adr/0001-assignment-hash.md.
+ */
+declare function bucketFor(experimentId: string, salt: string, subjectId: string): number;
+
+interface ManifestVariant {
+    key: string;
+    /** Optional explicit weight; if any variant declares one, weights of all others are required. */
+    weight?: number;
+}
+interface AssignArgs {
+    experimentId: string;
+    salt: string;
+    subjectId: string;
+    variants: readonly ManifestVariant[];
+    /** Sample rate in [0, 1] of eligible traffic the experiment applies to. */
+    sampleRate?: number;
+    /** Pre-existing sticky assignment — if set and matches a current variant, returned as-is. */
+    stickyVariantKey?: string;
+    /** Forced override (preview / QA). Highest priority. */
+    forcedVariantKey?: string;
+}
+type AssignmentReason = 'eligible' | 'sticky' | 'forced' | 'ineligible';
+interface AssignmentResult {
+    variantKey: string | null;
+    bucket: number;
+    reason: AssignmentReason;
+}
+/**
+ * Returns deterministic assignment for a subject. `null` variant + reason `ineligible`
+ * means the subject was sampled out and the SDK must NOT log an exposure.
+ */
+declare function assign(args: AssignArgs): AssignmentResult;
+
+export { type AssignArgs, type AssignmentResult, BUCKET_PRECISION, type ManifestVariant, assign, bucketFor, murmur3_x86_32 };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MurmurHash3 x86 32-bit. The deterministic bucketing primitive for every
+ * Fabric Experiments SDK. See docs/adr/0001-assignment-hash.md.
+ *
+ * Inputs are hashed as their UTF-8 byte representation.
+ * Output is treated as uint32 (sign-fixed via `>>> 0`).
+ */
+declare function murmur3_x86_32(key: string, seed?: number): number;
+
+declare const BUCKET_PRECISION: 10000;
+/**
+ * Returns an integer in [0, BUCKET_PRECISION) deterministic in (experimentId, salt, subjectId).
+ * Contract: see docs/adr/0001-assignment-hash.md.
+ */
+declare function bucketFor(experimentId: string, salt: string, subjectId: string): number;
+
+interface ManifestVariant {
+    key: string;
+    /** Optional explicit weight; if any variant declares one, weights of all others are required. */
+    weight?: number;
+}
+interface AssignArgs {
+    experimentId: string;
+    salt: string;
+    subjectId: string;
+    variants: readonly ManifestVariant[];
+    /** Sample rate in [0, 1] of eligible traffic the experiment applies to. */
+    sampleRate?: number;
+    /** Pre-existing sticky assignment — if set and matches a current variant, returned as-is. */
+    stickyVariantKey?: string;
+    /** Forced override (preview / QA). Highest priority. */
+    forcedVariantKey?: string;
+}
+type AssignmentReason = 'eligible' | 'sticky' | 'forced' | 'ineligible';
+interface AssignmentResult {
+    variantKey: string | null;
+    bucket: number;
+    reason: AssignmentReason;
+}
+/**
+ * Returns deterministic assignment for a subject. `null` variant + reason `ineligible`
+ * means the subject was sampled out and the SDK must NOT log an exposure.
+ */
+declare function assign(args: AssignArgs): AssignmentResult;
+
+export { type AssignArgs, type AssignmentResult, BUCKET_PRECISION, type ManifestVariant, assign, bucketFor, murmur3_x86_32 };

package/dist/index.js

@@ -0,0 +1,130 @@
+// src/hash.ts
+function murmur3_x86_32(key, seed = 0) {
+  const data = utf8Bytes(key);
+  const len = data.length;
+  const nblocks = len >>> 2;
+  let h1 = seed >>> 0;
+  const c1 = 3432918353;
+  const c2 = 461845907;
+  for (let i = 0; i < nblocks; i++) {
+    const o = i * 4;
+    let k12 = data[o] & 255 | (data[o + 1] & 255) << 8 | (data[o + 2] & 255) << 16 | (data[o + 3] & 255) << 24;
+    k12 = mul32(k12, c1);
+    k12 = rotl32(k12, 15);
+    k12 = mul32(k12, c2);
+    h1 ^= k12;
+    h1 = rotl32(h1, 13);
+    h1 = mul32(h1, 5) + 3864292196 >>> 0;
+  }
+  let k1 = 0;
+  const tail = len & 3;
+  const tailStart = nblocks * 4;
+  if (tail >= 3) k1 ^= (data[tailStart + 2] & 255) << 16;
+  if (tail >= 2) k1 ^= (data[tailStart + 1] & 255) << 8;
+  if (tail >= 1) {
+    k1 ^= data[tailStart] & 255;
+    k1 = mul32(k1, c1);
+    k1 = rotl32(k1, 15);
+    k1 = mul32(k1, c2);
+    h1 ^= k1;
+  }
+  h1 ^= len;
+  h1 = fmix32(h1);
+  return h1 >>> 0;
+}
+function rotl32(x, r) {
+  return (x << r | x >>> 32 - r) >>> 0;
+}
+function mul32(a, b) {
+  const aHi = a >>> 16 & 65535;
+  const aLo = a & 65535;
+  const bHi = b >>> 16 & 65535;
+  const bLo = b & 65535;
+  return aLo * bLo + (aHi * bLo + aLo * bHi << 16 >>> 0 | 0) >>> 0 >>> 0;
+}
+function fmix32(h) {
+  let x = h >>> 0;
+  x ^= x >>> 16;
+  x = mul32(x, 2246822507);
+  x ^= x >>> 13;
+  x = mul32(x, 3266489909);
+  x ^= x >>> 16;
+  return x >>> 0;
+}
+function utf8Bytes(s) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(s);
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i);
+    if (c < 128) {
+      out.push(c);
+    } else if (c < 2048) {
+      out.push(192 | c >> 6, 128 | c & 63);
+    } else if (c >= 55296 && c <= 56319 && i + 1 < s.length) {
+      const c2 = s.charCodeAt(i + 1);
+      if (c2 >= 56320 && c2 <= 57343) {
+        c = 65536 + ((c & 1023) << 10 | c2 & 1023);
+        i++;
+        out.push(
+          240 | c >> 18,
+          128 | c >> 12 & 63,
+          128 | c >> 6 & 63,
+          128 | c & 63
+        );
+      }
+    } else {
+      out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+    }
+  }
+  return new Uint8Array(out);
+}
+
+// src/bucket.ts
+var BUCKET_PRECISION = 1e4;
+function bucketFor(experimentId, salt, subjectId) {
+  const key = `${experimentId}:${salt}:${subjectId}`;
+  return murmur3_x86_32(key) % BUCKET_PRECISION;
+}
+
+// src/assign.ts
+function assign(args) {
+  const bucket = bucketFor(args.experimentId, args.salt, args.subjectId);
+  if (args.forcedVariantKey && args.variants.some((v) => v.key === args.forcedVariantKey)) {
+    return { variantKey: args.forcedVariantKey, bucket, reason: "forced" };
+  }
+  if (args.stickyVariantKey && args.variants.some((v) => v.key === args.stickyVariantKey)) {
+    return { variantKey: args.stickyVariantKey, bucket, reason: "sticky" };
+  }
+  const sampleRate = args.sampleRate ?? 1;
+  if (sampleRate < 1) {
+    const sampleBucket = bucketFor(`${args.experimentId}:sample`, args.salt, args.subjectId) / BUCKET_PRECISION;
+    if (sampleBucket >= sampleRate) {
+      return { variantKey: null, bucket, reason: "ineligible" };
+    }
+  }
+  const totalDeclared = args.variants.reduce((s, v) => s + (v.weight ?? 0), 0);
+  if (totalDeclared > 0) {
+    if (totalDeclared !== BUCKET_PRECISION) {
+      throw new Error(
+        `experiment ${args.experimentId}: variant weights must sum to ${BUCKET_PRECISION}, got ${totalDeclared}`
+      );
+    }
+    let cumulative = 0;
+    for (const v of args.variants) {
+      cumulative += v.weight ?? 0;
+      if (bucket < cumulative) return { variantKey: v.key, bucket, reason: "eligible" };
+    }
+    return {
+      variantKey: args.variants[args.variants.length - 1].key,
+      bucket,
+      reason: "eligible"
+    };
+  }
+  const idx = Math.floor(bucket / BUCKET_PRECISION * args.variants.length);
+  const safeIdx = Math.min(idx, args.variants.length - 1);
+  return { variantKey: args.variants[safeIdx].key, bucket, reason: "eligible" };
+}
+
+export { BUCKET_PRECISION, assign, bucketFor, murmur3_x86_32 };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/bucket.ts","../src/assign.ts"],"names":["k1"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * MurmurHash3 x86 32-bit. The deterministic bucketing primitive for every\n * Fabric Experiments SDK. See docs/adr/0001-assignment-hash.md.\n *\n * Inputs are hashed as their UTF-8 byte representation.\n * Output is treated as uint32 (sign-fixed via `>>> 0`).\n */\nexport function murmur3_x86_32(key: string, seed = 0): number {\n  const data = utf8Bytes(key);\n  const len = data.length;\n  const nblocks = len >>> 2;\n  let h1 = seed >>> 0;\n  const c1 = 0xcc9e2d51;\n  const c2 = 0x1b873593;\n\n  for (let i = 0; i < nblocks; i++) {\n    const o = i * 4;\n    let k1 =\n      (data[o]! & 0xff) |\n      ((data[o + 1]! & 0xff) << 8) |\n      ((data[o + 2]! & 0xff) << 16) |\n      ((data[o + 3]! & 0xff) << 24);\n\n    k1 = mul32(k1, c1);\n    k1 = rotl32(k1, 15);\n    k1 = mul32(k1, c2);\n\n    h1 ^= k1;\n    h1 = rotl32(h1, 13);\n    h1 = (mul32(h1, 5) + 0xe6546b64) >>> 0;\n  }\n\n  let k1 = 0;\n  const tail = len & 3;\n  const tailStart = nblocks * 4;\n  if (tail >= 3) k1 ^= (data[tailStart + 2]! & 0xff) << 16;\n  if (tail >= 2) k1 ^= (data[tailStart + 1]! & 0xff) << 8;\n  if (tail >= 1) {\n    k1 ^= data[tailStart]! & 0xff;\n    k1 = mul32(k1, c1);\n    k1 = rotl32(k1, 15);\n    k1 = mul32(k1, c2);\n    h1 ^= k1;\n  }\n\n  h1 ^= len;\n  h1 = fmix32(h1);\n  return h1 >>> 0;\n}\n\nfunction rotl32(x: number, r: number): number {\n  return ((x << r) | (x >>> (32 - r))) >>> 0;\n}\n\nfunction mul32(a: number, b: number): number {\n  const aHi = (a >>> 16) & 0xffff;\n  const aLo = a & 0xffff;\n  const bHi = (b >>> 16) & 0xffff;\n  const bLo = b & 0xffff;\n  return ((aLo * bLo + ((((aHi * bLo + aLo * bHi) << 16) >>> 0) | 0)) >>> 0) >>> 0;\n}\n\nfunction fmix32(h: number): number {\n  let x = h >>> 0;\n  x ^= x >>> 16;\n  x = mul32(x, 0x85ebca6b);\n  x ^= x >>> 13;\n  x = mul32(x, 0xc2b2ae35);\n  x ^= x >>> 16;\n  return x >>> 0;\n}\n\nfunction utf8Bytes(s: string): Uint8Array {\n  if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(s);\n  // Fallback for environments without TextEncoder.\n  const out: number[] = [];\n  for (let i = 0; i < s.length; i++) {\n    let c = s.charCodeAt(i);\n    if (c < 0x80) {\n      out.push(c);\n    } else if (c < 0x800) {\n      out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));\n    } else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {\n      const c2 = s.charCodeAt(i + 1);\n      if (c2 >= 0xdc00 && c2 <= 0xdfff) {\n        c = 0x10000 + (((c & 0x3ff) << 10) | (c2 & 0x3ff));\n        i++;\n        out.push(\n          0xf0 | (c >> 18),\n          0x80 | ((c >> 12) & 0x3f),\n          0x80 | ((c >> 6) & 0x3f),\n          0x80 | (c & 0x3f),\n        );\n      }\n    } else {\n      out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));\n    }\n  }\n  return new Uint8Array(out);\n}\n","import { murmur3_x86_32 } from './hash.js';\n\nexport const BUCKET_PRECISION = 10000 as const;\n\n/**\n * Returns an integer in [0, BUCKET_PRECISION) deterministic in (experimentId, salt, subjectId).\n * Contract: see docs/adr/0001-assignment-hash.md.\n */\nexport function bucketFor(experimentId: string, salt: string, subjectId: string): number {\n  const key = `${experimentId}:${salt}:${subjectId}`;\n  return murmur3_x86_32(key) % BUCKET_PRECISION;\n}\n","import { BUCKET_PRECISION, bucketFor } from './bucket.js';\n\nexport interface ManifestVariant {\n  key: string;\n  /** Optional explicit weight; if any variant declares one, weights of all others are required. */\n  weight?: number;\n}\n\nexport interface AssignArgs {\n  experimentId: string;\n  salt: string;\n  subjectId: string;\n  variants: readonly ManifestVariant[];\n  /** Sample rate in [0, 1] of eligible traffic the experiment applies to. */\n  sampleRate?: number;\n  /** Pre-existing sticky assignment — if set and matches a current variant, returned as-is. */\n  stickyVariantKey?: string;\n  /** Forced override (preview / QA). Highest priority. */\n  forcedVariantKey?: string;\n}\n\nexport type AssignmentReason = 'eligible' | 'sticky' | 'forced' | 'ineligible';\n\nexport interface AssignmentResult {\n  variantKey: string | null;\n  bucket: number;\n  reason: AssignmentReason;\n}\n\n/**\n * Returns deterministic assignment for a subject. `null` variant + reason `ineligible`\n * means the subject was sampled out and the SDK must NOT log an exposure.\n */\nexport function assign(args: AssignArgs): AssignmentResult {\n  const bucket = bucketFor(args.experimentId, args.salt, args.subjectId);\n\n  if (args.forcedVariantKey && args.variants.some((v) => v.key === args.forcedVariantKey)) {\n    return { variantKey: args.forcedVariantKey, bucket, reason: 'forced' };\n  }\n\n  if (args.stickyVariantKey && args.variants.some((v) => v.key === args.stickyVariantKey)) {\n    return { variantKey: args.stickyVariantKey, bucket, reason: 'sticky' };\n  }\n\n  const sampleRate = args.sampleRate ?? 1;\n  if (sampleRate < 1) {\n    // Use a separate hash-derived value for sampling so it's independent of variant assignment.\n    const sampleBucket =\n      bucketFor(`${args.experimentId}:sample`, args.salt, args.subjectId) / BUCKET_PRECISION;\n    if (sampleBucket >= sampleRate) {\n      return { variantKey: null, bucket, reason: 'ineligible' };\n    }\n  }\n\n  const totalDeclared = args.variants.reduce((s, v) => s + (v.weight ?? 0), 0);\n  if (totalDeclared > 0) {\n    if (totalDeclared !== BUCKET_PRECISION) {\n      throw new Error(\n        `experiment ${args.experimentId}: variant weights must sum to ${BUCKET_PRECISION}, got ${totalDeclared}`,\n      );\n    }\n    let cumulative = 0;\n    for (const v of args.variants) {\n      cumulative += v.weight ?? 0;\n      if (bucket < cumulative) return { variantKey: v.key, bucket, reason: 'eligible' };\n    }\n    // Numerical safety net.\n    return {\n      variantKey: args.variants[args.variants.length - 1]!.key,\n      bucket,\n      reason: 'eligible',\n    };\n  }\n\n  // Even split.\n  const idx = Math.floor((bucket / BUCKET_PRECISION) * args.variants.length);\n  const safeIdx = Math.min(idx, args.variants.length - 1);\n  return { variantKey: args.variants[safeIdx]!.key, bucket, reason: 'eligible' };\n}\n"]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@fabricorg/experiments-assignment",
+  "version": "0.0.1",
+  "description": "Deterministic, cross-language bucketing primitives for Fabric Experiments SDKs.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "fast-check": "^3.23.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}