@forgecart/sdk 1.202610171250.0 → 1.202610231804.0

package/dist/experiment-assignment.d.ts

@@ -47,10 +47,17 @@
  *
  * 6. EXPOSURE EVENT ID. `deriveExposureEventId` = RFC 4122 UUID version 5
  *    (SHA-1 name-based) with the fixed ForgeCart namespace
- *    `EXPOSURE_EVENT_ID_NAMESPACE` over the name
- *    `"{salt}:{subjectKey}:{utcDay}"`, where `utcDay` is the calendar date
- *    (`YYYY-MM-DD`) of the exposure's `occurredAt` instant in UTC. This gives
- *    every client an identical, idempotent exposure id per subject per UTC day.
+ *    `EXPOSURE_EVENT_ID_NAMESPACE` over a name keyed on the exposure's
+ *    assignment source (rule 5b/5c): `"{salt}:{subjectKey}:{utcDay}"` for a
+ *    hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ *    one, where `utcDay` is the calendar date (`YYYY-MM-DD`) of the
+ *    exposure's `occurredAt` instant in UTC. This gives every client an
+ *    identical, idempotent exposure id per subject per UTC day per source:
+ *    re-renders under one source resubmit one id, while a subject hashed
+ *    into a variant who follows a `?fc-exp=` campaign link the same UTC day
+ *    mints a second id, so the forced exposure reaches the forced cohort
+ *    instead of being deduped onto the hashed one. A hashed name ends in its
+ *    date and a forced name in `:forced`, so the two never collide.
  *
  * Zero imports by design: the module must stay portable, tree-shakeable, and
  * runnable in browsers, Node, and edge runtimes alike.
@@ -66,6 +73,8 @@ export declare const EXPERIMENT_MAX_VARIANT_WEIGHT = 1000000;
 export declare const EXPOSURE_EVENT_ID_NAMESPACE = "7d9f1c34-8a52-4b6e-9f0d-2c5e8a713b46";
 export type ExperimentLifecycle = 'draft' | 'running' | 'paused' | 'completed';
 export type AssignmentSource = 'lifecycle' | 'forced' | 'hashed';
+/** The assignment sources that emit an exposure (spec rule 5b/5c). */
+export type ExposureAssignmentSource = Extract<AssignmentSource, 'forced' | 'hashed'>;
 export interface ExperimentVariantWeight {
     /** Unique variant key within the experiment. */
     key: string;
@@ -138,7 +147,11 @@ export declare function getUtcDay(occurredAt: Date): string;
  */
 export declare function uuidV5(namespaceUuid: string, name: string): string;
 /**
- * Deterministic exposure event id (spec rule 6):
- * `uuidV5(EXPOSURE_EVENT_ID_NAMESPACE, "{salt}:{subjectKey}:{utcDay}")`.
+ * Deterministic exposure event id (spec rule 6): `uuidV5` under
+ * `EXPOSURE_EVENT_ID_NAMESPACE` over `"{salt}:{subjectKey}:{utcDay}"` for a
+ * hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ * one — idempotent per (subject, UTC day, assignment source). Pass the
+ * exposing `AssignmentResult`'s `assignmentSource`; it defaults to
+ * `'hashed'`, the randomized exposure.
  */
-export declare function deriveExposureEventId(salt: string, subjectKey: string, occurredAt: Date): string;
+export declare function deriveExposureEventId(salt: string, subjectKey: string, occurredAt: Date, assignmentSource?: ExposureAssignmentSource): string;

package/dist/experiment-assignment.js

@@ -48,10 +48,17 @@
  *
  * 6. EXPOSURE EVENT ID. `deriveExposureEventId` = RFC 4122 UUID version 5
  *    (SHA-1 name-based) with the fixed ForgeCart namespace
- *    `EXPOSURE_EVENT_ID_NAMESPACE` over the name
- *    `"{salt}:{subjectKey}:{utcDay}"`, where `utcDay` is the calendar date
- *    (`YYYY-MM-DD`) of the exposure's `occurredAt` instant in UTC. This gives
- *    every client an identical, idempotent exposure id per subject per UTC day.
+ *    `EXPOSURE_EVENT_ID_NAMESPACE` over a name keyed on the exposure's
+ *    assignment source (rule 5b/5c): `"{salt}:{subjectKey}:{utcDay}"` for a
+ *    hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ *    one, where `utcDay` is the calendar date (`YYYY-MM-DD`) of the
+ *    exposure's `occurredAt` instant in UTC. This gives every client an
+ *    identical, idempotent exposure id per subject per UTC day per source:
+ *    re-renders under one source resubmit one id, while a subject hashed
+ *    into a variant who follows a `?fc-exp=` campaign link the same UTC day
+ *    mints a second id, so the forced exposure reaches the forced cohort
+ *    instead of being deduped onto the hashed one. A hashed name ends in its
+ *    date and a forced name in `:forced`, so the two never collide.
  *
  * Zero imports by design: the module must stay portable, tree-shakeable, and
  * runnable in browsers, Node, and edge runtimes alike.
@@ -219,14 +226,19 @@ function uuidV5(namespaceUuid, name) {
     return formatUuidBytes(uuidBytes);
 }
 /**
- * Deterministic exposure event id (spec rule 6):
- * `uuidV5(EXPOSURE_EVENT_ID_NAMESPACE, "{salt}:{subjectKey}:{utcDay}")`.
+ * Deterministic exposure event id (spec rule 6): `uuidV5` under
+ * `EXPOSURE_EVENT_ID_NAMESPACE` over `"{salt}:{subjectKey}:{utcDay}"` for a
+ * hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ * one — idempotent per (subject, UTC day, assignment source). Pass the
+ * exposing `AssignmentResult`'s `assignmentSource`; it defaults to
+ * `'hashed'`, the randomized exposure.
  */
-function deriveExposureEventId(salt, subjectKey, occurredAt) {
+function deriveExposureEventId(salt, subjectKey, occurredAt, assignmentSource = 'hashed') {
     assertNonEmptyString(salt, 'salt');
     assertNonEmptyString(subjectKey, 'subjectKey');
-    const utcDay = getUtcDay(occurredAt);
-    return uuidV5(exports.EXPOSURE_EVENT_ID_NAMESPACE, `${salt}:${subjectKey}:${utcDay}`);
+    assertExposureAssignmentSource(assignmentSource);
+    const subjectDay = `${salt}:${subjectKey}:${getUtcDay(occurredAt)}`;
+    return uuidV5(exports.EXPOSURE_EVENT_ID_NAMESPACE, exposureEventIdName(subjectDay, assignmentSource));
 }
 // ── Internal helpers ────────────────────────────────────────────────────────
 function resolveRunningAssignment(config, subject, controlKey) {
@@ -297,6 +309,19 @@ function assertValidConfig(config) {
         throw new TypeError(`winnerVariantKey ${String(config.winnerVariantKey)} is not a variant of the experiment`);
     }
 }
+const EXPOSURE_ASSIGNMENT_SOURCES = ['hashed', 'forced'];
+function assertExposureAssignmentSource(assignmentSource) {
+    if (!EXPOSURE_ASSIGNMENT_SOURCES.includes(assignmentSource)) {
+        throw new TypeError(`unknown exposure assignment source: ${String(assignmentSource)}`);
+    }
+}
+/** Spec rule 6 name: the hashed exposure's is the subject-day itself. */
+function exposureEventIdName(subjectDay, assignmentSource) {
+    if (assignmentSource === 'hashed') {
+        return subjectDay;
+    }
+    return `${subjectDay}:${assignmentSource}`;
+}
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function parseUuidBytes(uuid) {
     if (!UUID_PATTERN.test(uuid)) {

package/dist/index.d.ts

@@ -22,5 +22,5 @@ export type { AcfFieldType } from './admin-types.generated';
 export { extractErrorCode, extractError, extractErrorMessage, isErrorCode } from './error-utils';
 export type { ExtractedError } from './error-utils';
 export { EXPERIMENT_BUCKET_COUNT, EXPERIMENT_MAX_VARIANT_WEIGHT, EXPOSURE_EVENT_ID_NAMESPACE, murmurHash3x86_32, computeAssignmentBucket, computeTrafficBucket, isSubjectAdmitted, deriveVariantRanges, resolveBucketVariant, resolveExperimentAssignment, getUtcDay, uuidV5, deriveExposureEventId } from './experiment-assignment';
-export type { ExperimentLifecycle, AssignmentSource, ExperimentVariantWeight, VariantRange, ExperimentAssignmentConfig, AssignmentSubject, AssignmentResult } from './experiment-assignment';
+export type { ExperimentLifecycle, AssignmentSource, ExposureAssignmentSource, ExperimentVariantWeight, VariantRange, ExperimentAssignmentConfig, AssignmentSubject, AssignmentResult } from './experiment-assignment';
 export { Observable, firstValueFrom, lastValueFrom } from 'rxjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/sdk",
-  "version": "1.202610171250.0",
+  "version": "1.202610231804.0",
   "description": "ForgeCart Client SDK",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/experiment-assignment.ts

@@ -47,10 +47,17 @@
  *
  * 6. EXPOSURE EVENT ID. `deriveExposureEventId` = RFC 4122 UUID version 5
  *    (SHA-1 name-based) with the fixed ForgeCart namespace
- *    `EXPOSURE_EVENT_ID_NAMESPACE` over the name
- *    `"{salt}:{subjectKey}:{utcDay}"`, where `utcDay` is the calendar date
- *    (`YYYY-MM-DD`) of the exposure's `occurredAt` instant in UTC. This gives
- *    every client an identical, idempotent exposure id per subject per UTC day.
+ *    `EXPOSURE_EVENT_ID_NAMESPACE` over a name keyed on the exposure's
+ *    assignment source (rule 5b/5c): `"{salt}:{subjectKey}:{utcDay}"` for a
+ *    hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ *    one, where `utcDay` is the calendar date (`YYYY-MM-DD`) of the
+ *    exposure's `occurredAt` instant in UTC. This gives every client an
+ *    identical, idempotent exposure id per subject per UTC day per source:
+ *    re-renders under one source resubmit one id, while a subject hashed
+ *    into a variant who follows a `?fc-exp=` campaign link the same UTC day
+ *    mints a second id, so the forced exposure reaches the forced cohort
+ *    instead of being deduped onto the hashed one. A hashed name ends in its
+ *    date and a forced name in `:forced`, so the two never collide.
  *
  * Zero imports by design: the module must stay portable, tree-shakeable, and
  * runnable in browsers, Node, and edge runtimes alike.
@@ -72,6 +79,9 @@ export type ExperimentLifecycle = 'draft' | 'running' | 'paused' | 'completed';
 
 export type AssignmentSource = 'lifecycle' | 'forced' | 'hashed';
 
+/** The assignment sources that emit an exposure (spec rule 5b/5c). */
+export type ExposureAssignmentSource = Extract<AssignmentSource, 'forced' | 'hashed'>;
+
 export interface ExperimentVariantWeight {
   /** Unique variant key within the experiment. */
   key: string;
@@ -280,18 +290,24 @@ export function uuidV5(namespaceUuid: string, name: string): string {
 }
 
 /**
- * Deterministic exposure event id (spec rule 6):
- * `uuidV5(EXPOSURE_EVENT_ID_NAMESPACE, "{salt}:{subjectKey}:{utcDay}")`.
+ * Deterministic exposure event id (spec rule 6): `uuidV5` under
+ * `EXPOSURE_EVENT_ID_NAMESPACE` over `"{salt}:{subjectKey}:{utcDay}"` for a
+ * hashed exposure and `"{salt}:{subjectKey}:{utcDay}:forced"` for a forced
+ * one — idempotent per (subject, UTC day, assignment source). Pass the
+ * exposing `AssignmentResult`'s `assignmentSource`; it defaults to
+ * `'hashed'`, the randomized exposure.
  */
 export function deriveExposureEventId(
   salt: string,
   subjectKey: string,
   occurredAt: Date,
+  assignmentSource: ExposureAssignmentSource = 'hashed',
 ): string {
   assertNonEmptyString(salt, 'salt');
   assertNonEmptyString(subjectKey, 'subjectKey');
-  const utcDay = getUtcDay(occurredAt);
-  return uuidV5(EXPOSURE_EVENT_ID_NAMESPACE, `${salt}:${subjectKey}:${utcDay}`);
+  assertExposureAssignmentSource(assignmentSource);
+  const subjectDay = `${salt}:${subjectKey}:${getUtcDay(occurredAt)}`;
+  return uuidV5(EXPOSURE_EVENT_ID_NAMESPACE, exposureEventIdName(subjectDay, assignmentSource));
 }
 
 // ── Internal helpers ────────────────────────────────────────────────────────
@@ -390,6 +406,25 @@ function assertValidConfig(config: ExperimentAssignmentConfig): void {
   }
 }
 
+const EXPOSURE_ASSIGNMENT_SOURCES: readonly ExposureAssignmentSource[] = ['hashed', 'forced'];
+
+function assertExposureAssignmentSource(assignmentSource: ExposureAssignmentSource): void {
+  if (!EXPOSURE_ASSIGNMENT_SOURCES.includes(assignmentSource)) {
+    throw new TypeError(`unknown exposure assignment source: ${String(assignmentSource)}`);
+  }
+}
+
+/** Spec rule 6 name: the hashed exposure's is the subject-day itself. */
+function exposureEventIdName(
+  subjectDay: string,
+  assignmentSource: ExposureAssignmentSource,
+): string {
+  if (assignmentSource === 'hashed') {
+    return subjectDay;
+  }
+  return `${subjectDay}:${assignmentSource}`;
+}
+
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 

package/src/experiment-assignment.vectors.v1.json

@@ -1024,5 +1024,43 @@
       "utcDay": "2026-01-01",
       "eventId": "47148c15-7472-5c73-bfd6-4d4c304d03e8"
     }
+  ],
+  "forcedExposureEventIds": [
+    {
+      "name": "midday-utc-forced",
+      "salt": "s-hero-2026",
+      "subjectKey": "v_9f3b1c7a",
+      "occurredAt": "2026-07-16T12:34:56.789Z",
+      "utcDay": "2026-07-16",
+      "assignmentSource": "forced",
+      "eventId": "ac4448f7-a1fb-5f3b-a647-9f38926c9be0"
+    },
+    {
+      "name": "same-utc-day-last-millisecond-forced-dedupes",
+      "salt": "s-hero-2026",
+      "subjectKey": "v_9f3b1c7a",
+      "occurredAt": "2026-07-16T23:59:59.999Z",
+      "utcDay": "2026-07-16",
+      "assignmentSource": "forced",
+      "eventId": "ac4448f7-a1fb-5f3b-a647-9f38926c9be0"
+    },
+    {
+      "name": "midnight-utc-crossing-forced-mints-new-id",
+      "salt": "s-hero-2026",
+      "subjectKey": "v_9f3b1c7a",
+      "occurredAt": "2026-07-17T00:00:00.000Z",
+      "utcDay": "2026-07-17",
+      "assignmentSource": "forced",
+      "eventId": "30509c45-8a88-59f9-b036-697a09c15837"
+    },
+    {
+      "name": "year-boundary-after-forced",
+      "salt": "x7f2e9ab4c",
+      "subjectKey": "cust_01H8XGJWBWBAQ4",
+      "occurredAt": "2026-01-01T00:00:00.000Z",
+      "utcDay": "2026-01-01",
+      "assignmentSource": "forced",
+      "eventId": "fdd7d848-180a-5b75-b3c5-cbefd471cb99"
+    }
   ]
 }

package/src/index.ts

@@ -22,5 +22,5 @@ export type { AcfFieldType } from './admin-types.generated';
 export { extractErrorCode, extractError, extractErrorMessage, isErrorCode } from './error-utils';
 export type { ExtractedError } from './error-utils';
 export { EXPERIMENT_BUCKET_COUNT, EXPERIMENT_MAX_VARIANT_WEIGHT, EXPOSURE_EVENT_ID_NAMESPACE, murmurHash3x86_32, computeAssignmentBucket, computeTrafficBucket, isSubjectAdmitted, deriveVariantRanges, resolveBucketVariant, resolveExperimentAssignment, getUtcDay, uuidV5, deriveExposureEventId } from './experiment-assignment';
-export type { ExperimentLifecycle, AssignmentSource, ExperimentVariantWeight, VariantRange, ExperimentAssignmentConfig, AssignmentSubject, AssignmentResult } from './experiment-assignment';
+export type { ExperimentLifecycle, AssignmentSource, ExposureAssignmentSource, ExperimentVariantWeight, VariantRange, ExperimentAssignmentConfig, AssignmentSubject, AssignmentResult } from './experiment-assignment';
 export { Observable, firstValueFrom, lastValueFrom } from 'rxjs';