wardx 0.1.7 → 0.4.0

package/README.md

@@ -32,8 +32,10 @@ To receive frames, run an ingest server. Install `@wardx/server` and start it wi
 - A measure call does not send network data.
 - A measure call does not wait for a Promise.
 - Delivery is at-most-once. If a sync fails, the SDK discards the batch.
+- Physical frames are serialized, split to `maxFrameBytes`, and assigned consecutive sequence numbers. An individually oversized row is counted in `wardx.internal.frame_rows_dropped`.
 - The application has priority over telemetry.
 - Remote Config is always read from local memory.
+- Remote Config must not contain secrets. The project key authenticates the project; client-selected `role` is routing metadata, not authorization.
 - The SDK sends names only. Descriptions live in the server catalog: ship them in the config file, or fill them during MCP onboarding.
 - `identify(subjectId)` sets the default subject for this instance. A per-call `{ subjectId }` overrides it. A process that serves many users must pass `subjectId` on each call and must not `identify()`.
 
@@ -48,11 +50,12 @@ To receive frames, run an ingest server. Install `@wardx/server` and start it wi
 | `endpoint` | Base URL of the ingest server, for example `http://127.0.0.1:8787`. |
 | `projectKey` | Value of header `X-Wardx-Key`. |
 | `project` | Project name. The name must match the server mapping. |
-| `role` | Name of this instance inside the project, for example `client`, `unity`, `game-server`, `desktop`. Not `*`. |
+| `role` | Routing name of this instance inside the project, for example `client`, `unity`, `game-server`, `desktop`. Not `*`; not an authorization boundary. |
 | `appVersion` | Application version. |
 | `environment` | Environment name. |
+| `privacySalt` | Required stable, project-specific salt for one-way subject hashes. |
 
-Optional keys include `privacySalt`, `tracer`, and the keys in `@wardx/core` `defaults.json`. If `privacySalt` is empty, the SDK uses `projectKey`. `tracer` is a local diagnostic hook. It does not go over the wire.
+Optional keys include `tracer` and overrides for centralized values in `@wardx/core` `defaults.json`. `maxFrameBytes` is at least `1024`; `experimentStateMaxSubjects` defaults to `100000` and bounds assignment/exposure state in this SDK instance. Missing or empty `privacySalt` is rejected; it is never derived from the project credential. `tracer` is a local diagnostic hook. It does not go over the wire.
 
 The SDK starts a bootstrap sync immediately. The SDK then syncs on `syncIntervalMs` with jitter.
 
@@ -71,7 +74,8 @@ const wardx = createWardx({
   project: 'demo',
   role: 'client',
   appVersion: '2.4.1',
-  environment: 'production'
+  environment: 'production',
+  privacySalt: 'demo-subject-hash-v1'
 });
 
 wardx.log.info('match_started', { mode: 'ranked', players: 4 });
@@ -79,6 +83,7 @@ wardx.event('match.started', { mode: 'ranked', country: 'AR' });
 wardx.counter('match.completed', { mode: 'ranked' }).inc();
 wardx.gauge('players.online').set(12);
 wardx.histogram('request.duration', { buckets: [10, 25, 50, 100, 250] }).observe(42);
+wardx.distinct('shot.traffic.hids', { result: 'violating' }).add(hid);
 
 const end = wardx.timer('matchmaking.duration');
 end({ result: 'success' });
@@ -273,7 +278,7 @@ If the event buffer is full, the SDK discards the new event and increments `ward
 
 **Objective:** Emit one named event and one counter per step. Compare those counts. Do not reconstruct a per-user path.
 
-Wardx does not store a user journey. Delivery is at-most-once. Production discards envelopes after ingest (`sink: "null"`). The aggregator counts events by name and role. Event attrs do not split that count. `sessionId` identifies the envelope. It is not a join key. There are no unique users, no ordered sequences, and no time between steps.
+Wardx does not store a user journey. Delivery is at-most-once. Production discards envelopes after ingest (`sink: "null"`). The aggregator counts events by name and role. Event attrs do not split that count. `sessionId` identifies the envelope. It is not a join key. `distinct` can estimate unique identifiers per named aggregate, but it does not provide ordered sequences or time between steps.
 
 Give each step its own name. Do not reuse `screen.view` with a `surface` attr as the funnel. Use `surface` only as a counter dimension when you also need a breakdown of one step.
 
@@ -305,7 +310,10 @@ function onOnboardingDone(wardx, userId) {
 
 On a backend that serves many users, increment the counters in process. Do not `event()` once per user action.
 
-Do not put `userId` on a counter dimension. Do not expect Mixpanel-style unique-user funnels from Wardx.
+Do not put `userId` on a counter dimension. For an approximate unique count at
+one step, use `distinct(stepName, dims).add(userId)`. It hashes with the required
+local `privacySalt` and sends only a 512-register HLL sketch (`p=9`, about 4.6%
+standard error). This still does not create a Mixpanel-style per-user funnel.
 
 ## Use case 8: Detect abnormal point accumulation
 
@@ -388,7 +396,7 @@ The SDK updates the snapshot when a sync response contains a newer `configVersio
 
 The ingest server config can define experiment `message-delay-v1` on key `message.delayMs`. See `@wardx/server`. Variants live on the server. The app still reads the same key.
 
-On a client with one user, call `identify` once after login. Later `config.get` and `experiment.goal` use that subject. On a server that handles many users, pass `{ subjectId }` on every call. Do not `identify()` there: it is process-wide and would mix users.
+On a client with one user, call `identify` once after login. Later `config.get` and `experiment.goal` use that subject. On a server that handles many users, pass `{ subjectId }` on every call. Do not use one SDK instance's default there; it would mix users.
 
 ```js
 wardx.identify(userId);
@@ -419,7 +427,7 @@ The first `config.get` that has a subject in a session can emit event `experimen
 
 The payload does not contain the raw `subjectId`.
 
-`experiment.goal` needs a subject: from `identify()` or from `{ subjectId }` on that call. The event includes the known assignments for that subject. Without a subject, the call throws.
+`experiment.goal` needs a subject: from `identify()` or from `{ subjectId }` on that call. It emits nothing until that subject has an exposure whose `goalMetric` matches the goal name; a valid event contains exactly that one assignment. Without a subject, the call throws.
 
 ## Use case 11: Continue when the ingest server is down
 
@@ -434,7 +442,8 @@ const wardx = createWardx({
   project: 'demo',
   role: 'client',
   appVersion: '0.1.0',
-  environment: 'development'
+  environment: 'development',
+  privacySalt: 'demo-subject-hash-v1'
 });
 
 wardx.counter('jobs.completed').inc();
@@ -458,7 +467,8 @@ const wardx = createWardx({
   project: 'demo',
   role: 'client',
   appVersion: '0.1.0',
-  environment: 'production'
+  environment: 'production',
+  privacySalt: 'demo-subject-hash-v1'
 });
 
 async function onStop() {
@@ -470,7 +480,7 @@ process.on('SIGTERM', onStop);
 process.on('SIGINT', onStop);
 ```
 
-`shutdown` is safe to call more than one time. The second call returns immediately.
+`shutdown` is safe to call more than once. Concurrent callers receive the same promise and all await the final flush and single transport close.
 
 `flush` sends the current pending frames and does not stop the timers. Use `shutdown` when the process stops.
 
@@ -490,6 +500,7 @@ const wardx = createWardx({
   role: 'client',
   appVersion: '0.1.0',
   environment: 'development',
+  privacySalt: 'demo-subject-hash-v1',
   tracer: createConsoleTracer()
 });
 ```
@@ -579,7 +590,7 @@ The volume funnel `level.start` → `level.fail` / `level.complete` is the diffi
 
 Call `experiment.goal('session.duration', { value: durationMs })` when the play session ends (use case 14).
 
-From MCP, after onboarding: `upsert_experiment` on the existing keys (`level.3.enemyHp`, …) with a hypothesis such as "Lower HP on level 3 increases session duration", `primaryMetric: 'session.time_ms'`, `goalKind: 'mean'`, `control`, `minExposures`, `confidence`, and variants that only change those keys. Later `analyze_experiment`: follow `decision` and compare `goalMean` for the duration goal. `ship_experiment` when status is `winner`. Compare the funnel counts with `get_aggregates`. See `@wardx/server` use case 7.
+From MCP, after onboarding: `upsert_experiment` on the existing keys (`level.3.enemyHp`, …) with a hypothesis such as "Lower HP on level 3 increases session duration", `primaryMetric: 'session.time_ms'`, `goalMetric: 'session.duration'`, `assignmentUnitKind: 'session'`, `outcomeKind: 'mean'`, and the complete fixed-horizon sample/time/alpha/effect/direction/health policy. Later `analyze_experiment` uses only trusted, server-deduplicated evidence; follow its persisted terminal `decision` and compare `goalMean`. `ship_experiment` additionally requires the current `expectedVersion` and a reason. Compare current funnel counts with `get_aggregates` and completed baselines with `get_aggregate_history`.
 
 ## Use case 16: Surface an error so an agent can open the source
 
@@ -629,13 +640,13 @@ The log ring is recent only (`recentLogsMax`). It is not a history search. See `
 | `timer(name, dims)` | Starts a timer. The returned function records milliseconds. |
 | `event(name, attrs)` | Buffers a product event. |
 | `log.debug\|info\|warn\|error(message, attrs)` | Buffers a structured log. |
-| `identify(subjectId)` | Sets the default subject for this instance. `identify(null)` clears it. Process-wide: do not use on a game-server that serves many users. |
+| `identify(subjectId)` | Sets the default subject for this SDK instance. `identify(null)` clears it. Do not share that default across users on a multi-user server. |
 | `config.get(key, fallback, context)` | Reads Remote Config. Uses `identify()` or `{ subjectId }`. A per-call `{ subjectId }` overrides `identify()`. Omit both for the shared value. |
 | `experiment.goal(name, context)` | Emits `experiment.goal`. Needs a subject from `identify()` or `{ subjectId }`. Optional `value` for a quantitative goal such as session duration. |
 | `flush()` | Sends pending frames now. Returns a Promise. |
 | `shutdown()` | Stops timers, sends pending frames, and closes the HTTP agent. |
 
-The SDK creates one `instanceId` and one `sessionId` per process. The IDs are ULIDs.
+Each `createWardx()` SDK instance creates its own `instanceId` and `sessionId`. The IDs are ULIDs; they are not process-wide singletons or subject/journey keys.
 
 Sync delay is `syncIntervalMs * random(syncJitterMin, syncJitterMax)`. The default interval is 15 seconds. The default jitter is 0.85 to 1.15.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wardx",
-  "version": "0.1.7",
+  "version": "0.4.0",
   "description": "Node.js SDK for Wardx telemetry, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -37,6 +37,6 @@
     "src"
   ],
   "dependencies": {
-    "@wardx/core": "0.1.7"
+    "@wardx/core": "0.4.0"
   }
-}
+}

package/src/WardxNode.js

@@ -23,6 +23,7 @@ export class WardxNode {
     this._core = new WardxCore(settings);
     this._transport = createHttpTransport(settings);
     this._stopped = false;
+    this._shutdownPromise = null;
     this._syncChain = Promise.resolve();
     this._instanceId = ulid();
     this._sessionId = ulid();
@@ -58,6 +59,10 @@ export class WardxNode {
     return this._core.histogram(name, a, b);
   }
 
+  distinct(name, dims) {
+    return this._core.distinct(name, dims);
+  }
+
   timer(name, dims) {
     return this._core.timer(name, dims);
   }
@@ -70,8 +75,12 @@ export class WardxNode {
     return this._enqueueSync({ flush: true });
   }
 
-  async shutdown() {
-    if (this._stopped) return;
+  shutdown() {
+    if (this._shutdownPromise === null) this._shutdownPromise = this._shutdown();
+    return this._shutdownPromise;
+  }
+
+  async _shutdown() {
     this._stopped = true;
     clearInterval(this._aggregateTimer);
     if (this._syncTimer) clearTimeout(this._syncTimer);

package/src/index.d.ts

@@ -7,6 +7,7 @@ import type {
   CreateWardxOptions,
   DimensionValue,
   Dimensions,
+  DistinctHandle,
   EventTraceRecord,
   Experiment,
   ExperimentGoalContext,
@@ -36,6 +37,7 @@ export type {
   CreateWardxOptions,
   DimensionValue,
   Dimensions,
+  DistinctHandle,
   EventTraceRecord,
   Experiment,
   ExperimentGoalContext,
@@ -78,6 +80,7 @@ export class WardxNode {
   counter(name: string, dims?: Dimensions | null): CounterHandle;
   gauge(name: string, dims?: Dimensions | null): GaugeHandle;
   histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;
+  distinct(name: string, dims?: Dimensions | null): DistinctHandle;
   timer(name: string, dims?: Dimensions | null): StopTimer;
   event(name: string, attrs?: Attrs | null): void;
   flush(): Promise<void>;