@wardx/core 0.4.0 → 0.7.0

package/README.md

@@ -117,7 +117,7 @@ core.histogram('coins.award_size').observe(80, { grantId: 'g-80' });
 `timer(name, dims)` starts a timer. The returned function records the duration in milliseconds into a histogram. You can add dimensions when you stop the timer.
 
 `distinct(name, dims).add(identifier)` updates a fixed HyperLogLog sketch. The
-engine hashes the identifier as `SHA-256(privacySalt || 0x00 || identifier)` and
+engine hashes the identifier as `XXHash64(privacySalt || 0x00 || identifier)` and
 discards it immediately; the frame contains only 512 HLL registers (`p=9`,
 about 4.6% standard error). Keep `privacySalt` stable across workers and time
 windows so equal identifiers map to equal registers.
@@ -239,7 +239,7 @@ bucket = hash / 2^32
 
 If `bucket >= allocation`, `assignVariant` returns `null`.
 
-`subjectHash` returns 64 lowercase hex digits of `SHA-256(UTF8(privacySalt) || 0x00 || UTF8(subjectId))`.
+`subjectHash` returns 16 lowercase hex digits of `XXHash64(UTF8(privacySalt) || 0x00 || UTF8(subjectId))`.
 
 ## Use case 5: Build a frame for a custom transport
 
@@ -302,3 +302,12 @@ Internal series use the prefix `wardx.internal.`.
 - Ingest server: `@wardx/server`
 
 The wire contract is protocol version 1. A runtime sends `POST /v1/sync` with JSON and gzip. The request header is `X-Wardx-Key`.
+
+## Retention activity
+
+`WardxCore.retentionActivity(userId)` requires an explicit nonblank user ID and
+emits salted `retention.activity` evidence into the existing event buffer. The
+server persists UTC cohorts and exact received-user D1/D7/D30 returns; the core
+does not infer activity or keep a durable client identity/outbox. Use the same
+user ID and privacy salt across sessions and clients. See the
+[Node retention contract](../node/README.md#user-retention-d1--d7--d30).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardx/core",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Runtime-agnostic Wardx engine for metrics, events, logs, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -40,5 +40,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "xxhash-wasm": "1.1.0"
   }
-}
+}

package/src/WardxCore.js

@@ -3,6 +3,7 @@ import { EventBuffer } from './buffers/EventBuffer.js';
 import { LogBuffer } from './buffers/LogBuffer.js';
 import { ConfigStore } from './config/ConfigStore.js';
 import { ExperimentResolver } from './config/ExperimentResolver.js';
+import { subjectHash } from './config/hash.js';
 import { FrameBuilder } from './frame/FrameBuilder.js';
 import { InternalMetrics } from './internal/InternalMetrics.js';
 import { NOOP_COUNTER } from './metrics/Counter.js';
@@ -106,6 +107,20 @@ export class WardxCore {
     return wrapped;
   }
 
+  retentionActivity(userId) {
+    if (typeof userId !== 'string' || userId.trim().length === 0) {
+      throw new Error('retentionActivity requires a non-empty userId');
+    }
+    const salt = this.settings.privacySalt;
+    if (typeof salt !== 'string' || salt.trim().length === 0) {
+      throw new Error('retentionActivity requires a non-empty privacySalt');
+    }
+    this.event('retention.activity', {
+      subject: subjectHash(salt, userId),
+      salt: subjectHash(salt, 'wardx.retention.identity')
+    });
+  }
+
   identify(subjectId) {
     if (subjectId === undefined || subjectId === null) {
       this._subjectId = null;

package/src/config/hash.js

@@ -1,4 +1,6 @@
-import { createHash } from 'node:crypto';
+import xxhash from 'xxhash-wasm';
+
+const { h64ToString } = await xxhash();
 
 const encoder = new TextEncoder();
 
@@ -25,9 +27,5 @@ export function assignmentHash(experimentId, subjectId, salt) {
 }
 
 export function subjectHash(projectSalt, subjectId) {
-  return createHash('sha256')
-    .update(projectSalt, 'utf8')
-    .update('\0', 'utf8')
-    .update(subjectId, 'utf8')
-    .digest('hex');
+  return h64ToString(`${projectSalt}\0${subjectId}`);
 }

package/src/index.d.ts

@@ -440,6 +440,7 @@ export class WardxCore {
   distinct(name: string, dims?: Dimensions | null): DistinctHandle;
   timer(name: string, dims?: Dimensions | null): StopTimer;
   event(name: string, attrs?: Attrs | null): void;
+  retentionActivity(userId: string): void;
   identify(subjectId: string | null | undefined): void;
   configGet<T>(key: string, fallback: T, context?: SubjectContext): T;
   experimentGoal(name: string, context?: ExperimentGoalContext): void;

package/src/metrics/HyperLogLog.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { subjectHash } from '../config/hash.js';
 
 export const HLL_PRECISION = 9;
 export const HLL_REGISTER_COUNT = 1 << HLL_PRECISION;
@@ -82,11 +82,7 @@ export class HyperLogLog {
     if (typeof identifier !== 'string' || identifier.length === 0) {
       throw new Error('distinct.add requires a non-empty string');
     }
-    const digest = createHash('sha256')
-      .update(this.privacySalt, 'utf8')
-      .update('\0', 'utf8')
-      .update(identifier, 'utf8')
-      .digest();
+    const digest = Buffer.from(subjectHash(this.privacySalt, identifier), 'hex');
     const index = (digest[0] << 1) | (digest[1] >> 7);
     const rank = rankAfterIndex(digest);
     if (rank > this.registers[index]) this.registers[index] = rank;