@wardx/core 0.1.2 → 0.1.4

package/README.md

@@ -27,6 +27,7 @@ import { WardxCore, assignVariant, loadSdkDefaults } from '@wardx/core';
 - A measure call does not wait for a Promise.
 - If a buffer is full, the engine discards data. The engine does not block the application.
 - Counters in a frame are window deltas. Counters are not lifetime totals.
+- `identify(subjectId)` sets the default subject for this instance. A per-call `{ subjectId }` overrides it.
 
 ## Settings
 
@@ -125,7 +126,7 @@ A dimension value must be a string, a number, or a boolean.
 ```js
 core.event('purchase', { product: 'premium' });
 core.log.info('match_started', { mode: 'ranked', players: 4 });
-core.log.error('payment_failed', { code: 'timeout' });
+core.log.error('payment_failed', { code: 'timeout', stack: 'PaymentError: timeout' });
 ```
 
 Log levels: `debug`, `info`, `warn`, `error`.
@@ -138,7 +139,7 @@ Log levels: `debug`, `info`, `warn`, `error`.
 
 Dropped items increment `wardx.internal.events_dropped` or `wardx.internal.logs_dropped`.
 
-Use counters and histograms for rates and latency. Use events for rare product facts: a purchase, an experiment exposure or goal, a named screen. Use logs for failures. Do not put user ids on metric dimensions.
+Use counters and histograms for rates and latency. Use events for rare product facts: a purchase, an experiment exposure or goal, a named screen. Use logs for failures. Put a clipped `stack` or a provider `code` on the log attrs so MCP `get_recent_logs` can show an agent where to look. The engine does not edit source. Do not put user ids on metric dimensions.
 
 A volume funnel is one event name and one counter per step. The engine does not join events by subject. See `docs/ARCHITECTURE.md`.
 
@@ -148,6 +149,8 @@ A volume funnel is one event name and one counter per step. The engine does not
 
 **Objective:** Get a config value. If an experiment applies, get the variant value.
 
+There is a default subject after `identify(subjectId)`. Pass `{ subjectId }` on a call to override it, or when one process serves many users. Use a stable account id, not `sessionId`. With no subject, `configGet` returns the Remote Config value and that call is not in the A/B test.
+
 ```js
 core.applyConfig(13, {
   values: {
@@ -170,23 +173,26 @@ core.applyConfig(13, {
 });
 
 const fallback = 1000;
-const delay = core.configGet('message.delayMs', fallback, { subjectId: 'user-1' });
-core.experimentGoal('message.sent', { subjectId: 'user-1', value: 1 });
+const shared = core.configGet('message.delayMs', fallback);
+core.identify('user-1');
+const delay = core.configGet('message.delayMs', fallback);
+core.experimentGoal('message.sent', { value: 1 });
+const other = core.configGet('message.delayMs', fallback, { subjectId: 'user-2' });
 ```
 
+`shared` is always the snapshot value (`1000`). `delay` is `1000` or `400` for `user-1`. `other` is the variant for `user-2`. The same `subjectId`, experiment `id`, and `salt` always map to the same variant. You do not persist the group. Changing `salt` redistributes the population. `identify(null)` clears the default.
+
 ### Resolution order
 
 1. If the key is not in the snapshot, return `fallback`.
-2. If `subjectId` is missing, return the Remote Config value.
+2. If there is no subject (`identify` unset and no `{ subjectId }`), return the Remote Config value.
 3. If no enabled experiment contains the key, return the Remote Config value.
 4. If the subject is not in the allocation, return the Remote Config value.
 5. If the subject is in the allocation, return the variant value.
 
-The assignment is deterministic. The same `experimentId`, `subjectId`, and `salt` always give the same variant.
-
 The first resolve for a subject in a session emits event `experiment.exposure`. The payload contains a hashed subject. The payload does not contain the raw `subjectId`.
 
-`experimentGoal` emits event `experiment.goal`. You must supply `subjectId`. You can supply `value`.
+`experimentGoal` emits event `experiment.goal`. The subject comes from `identify()` or from `{ subjectId }` on that call. You can supply `value`. Use milliseconds for a session-duration goal. The server stores that number as `goalSum` and `goalMean` per variant. Without a subject, the call throws. One experiment should have one quantitative goal name.
 
 ## Use case 4: Assign a variant without WardxCore
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardx/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Runtime-agnostic Wardx engine for metrics, events, logs, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -27,8 +27,13 @@
     "node": ">=20"
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
   },
+  "types": "./src/index.d.ts",
   "files": [
     "src",
     "defaults.json"
@@ -36,4 +41,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/WardxCore.js

@@ -40,6 +40,7 @@ export class WardxCore {
     this.seq = 0;
     this.pendingFrames = [];
     this.windowStart = Date.now();
+    this._subjectId = null;
     this.log = {
       debug: (message, attrs) => this._log('debug', message, attrs),
       info: (message, attrs) => this._log('info', message, attrs),
@@ -96,30 +97,48 @@ export class WardxCore {
     return wrapped;
   }
 
+  identify(subjectId) {
+    if (subjectId === undefined || subjectId === null) {
+      this._subjectId = null;
+      return;
+    }
+    if (typeof subjectId !== 'string' || subjectId.length === 0) {
+      throw new Error('identify requires a non-empty subjectId');
+    }
+    this._subjectId = subjectId;
+  }
+
+  _subjectIdFrom(context) {
+    if (context && context.subjectId !== undefined && context.subjectId !== null) {
+      return context.subjectId;
+    }
+    return this._subjectId;
+  }
+
   configGet(key, fallback, context) {
     if (!this.configStore.has(key)) return fallback;
     const remote = this.configStore.getRaw(key);
-    if (!context || context.subjectId === undefined || context.subjectId === null) {
-      return remote;
-    }
+    const subjectId = this._subjectIdFrom(context);
+    if (subjectId === undefined || subjectId === null) return remote;
     return this.experiments.resolve(
       key,
       remote,
-      context.subjectId,
+      subjectId,
       this.configStore.experimentsByKey
     );
   }
 
   experimentGoal(name, context) {
-    if (!context || context.subjectId === undefined || context.subjectId === null) {
+    const subjectId = this._subjectIdFrom(context);
+    if (subjectId === undefined || subjectId === null) {
       throw new Error('experiment.goal requires subjectId');
     }
     if (typeof name !== 'string' || name.length === 0) {
       throw new Error('experiment.goal requires a metric name');
     }
-    const subject = this.experiments.hashSubject(context.subjectId);
+    const subject = this.experiments.hashSubject(subjectId);
     const experiments = this.experiments.relevantExperiments(
-      context.subjectId,
+      subjectId,
       this.configStore.experiments
     );
     const payload = {
@@ -127,7 +146,7 @@ export class WardxCore {
       subject,
       experiments
     };
-    if (context.value !== undefined) payload.value = context.value;
+    if (context && context.value !== undefined) payload.value = context.value;
     this.event('experiment.goal', payload);
   }
 

package/src/index.d.ts

@@ -0,0 +1,410 @@
+export const PROTOCOL_VERSION: 1;
+export const SDK_NAME: 'wardx-node';
+export const PLATFORM: 'node';
+
+export const INTERNAL: {
+  readonly eventsBuffered: 'wardx.internal.events_buffered';
+  readonly logsBuffered: 'wardx.internal.logs_buffered';
+  readonly eventsDropped: 'wardx.internal.events_dropped';
+  readonly logsDropped: 'wardx.internal.logs_dropped';
+  readonly cardinalityDropped: 'wardx.internal.cardinality_dropped';
+  readonly framesSent: 'wardx.internal.frames_sent';
+  readonly framesFailed: 'wardx.internal.frames_failed';
+  readonly bytesUncompressed: 'wardx.internal.bytes_uncompressed';
+  readonly bytesCompressed: 'wardx.internal.bytes_compressed';
+  readonly lastSyncMs: 'wardx.internal.last_sync_ms';
+  readonly configVersion: 'wardx.internal.config_version';
+  readonly processRssBytes: 'wardx.internal.process_rss_bytes';
+};
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type DimensionValue = string | number | boolean;
+export interface Dimensions {
+  [name: string]: DimensionValue;
+}
+export type Attrs = Record<string, unknown>;
+export type ConfigValue = string | number | boolean;
+
+export interface HistogramOptions {
+  buckets?: number[];
+  [dimension: string]: DimensionValue | number[] | undefined;
+}
+
+export interface CounterHandle {
+  inc(): void;
+  add(n: number): void;
+}
+
+export interface GaugeHandle {
+  set(value: number): void;
+}
+
+export interface HistogramHandle {
+  observe(value: number, attrs?: Dimensions | null): void;
+}
+
+export type StopTimer = (dims?: Dimensions | null) => void;
+
+export interface SdkDefaults {
+  aggregateIntervalMs: number;
+  syncIntervalMs: number;
+  syncJitterMin: number;
+  syncJitterMax: number;
+  maxBufferedEvents: number;
+  maxBufferedLogs: number;
+  maxFrameBytes: number;
+  maxSeriesPerMetric: number;
+  maxDimensionKeys: number;
+  maxDimensionValueLength: number;
+  httpTimeoutMs: number;
+  histogramBuckets: number[];
+}
+
+export interface CreateWardxOptions extends Partial<SdkDefaults> {
+  endpoint: string;
+  projectKey: string;
+  project: string;
+  role: string;
+  appVersion: string;
+  environment: string;
+  privacySalt?: string;
+  tracer?: Tracer | null;
+}
+
+export interface CoreSettings extends SdkDefaults {
+  privacySalt: string;
+  endpoint?: string;
+  projectKey?: string;
+  project?: string;
+  role?: string;
+  appVersion?: string;
+  environment?: string;
+  tracer?: Tracer | null;
+}
+
+export interface ResolvedSettings extends SdkDefaults {
+  endpoint: string;
+  projectKey: string;
+  project: string;
+  role: string;
+  appVersion: string;
+  environment: string;
+  privacySalt: string;
+  tracer?: Tracer | null;
+}
+
+export interface SubjectContext {
+  subjectId?: string | null;
+}
+
+export interface ExperimentGoalContext extends SubjectContext {
+  value?: number;
+}
+
+export interface ExperimentVariant {
+  key: string;
+  weight: number;
+  values: Record<string, ConfigValue>;
+}
+
+export interface Experiment {
+  id: string;
+  enabled: boolean;
+  allocation: number;
+  salt: string;
+  primaryMetric?: string;
+  variants: ExperimentVariant[];
+}
+
+export interface ConfigSnapshot {
+  values?: Record<string, ConfigValue>;
+  experiments?: Experiment[];
+}
+
+export interface Assignment {
+  experiment: string;
+  variant: string;
+}
+
+export interface ExposurePayload {
+  experiment: string;
+  variant: string;
+  subject: string;
+}
+
+export type EventRow = [timestamp: number, name: string, attrs: Attrs | null];
+export type LogRow = [timestamp: number, level: LogLevel, message: string, attrs: Attrs | null];
+export type CounterRow = [name: string, dims: Dimensions | null, value: number];
+export type GaugeRow = [name: string, dims: Dimensions | null, value: number, timestamp: number];
+export type HistogramRow = [name: string, dims: Dimensions | null, snapshot: HistogramSnapshot];
+
+export interface HistogramExemplar {
+  value: number;
+  attrs: Dimensions;
+}
+
+export interface HistogramSnapshot {
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  buckets: Array<[bound: number, count: number]>;
+  exemplar?: HistogramExemplar;
+}
+
+export interface MetricsSnapshot {
+  counters: CounterRow[];
+  gauges: GaugeRow[];
+  histograms: HistogramRow[];
+}
+
+export interface Frame {
+  seq: number;
+  from: number;
+  to: number;
+  metrics: MetricsSnapshot;
+  events: EventRow[];
+  logs: LogRow[];
+}
+
+export interface FittedFrame {
+  frame: Frame;
+  json: string;
+  droppedLogs: number;
+  droppedEvents: number;
+}
+
+export interface InternalSnapshot {
+  eventsDropped: number;
+  logsDropped: number;
+  cardinalityDropped: number;
+  framesSent: number;
+  framesFailed: number;
+  bytesUncompressed: number;
+  bytesCompressed: number;
+  eventsBuffered: number;
+  logsBuffered: number;
+  lastSyncMs: number;
+  configVersion: number;
+  processRssBytes: number;
+}
+
+export interface MeasureTraceRecord {
+  type: 'counter' | 'gauge' | 'histogram';
+  name: string;
+  dims: Dimensions | null;
+  op: 'inc' | 'add' | 'set' | 'observe';
+  value: number;
+  attrs?: Dimensions | null;
+  noop: boolean;
+}
+
+export interface EventTraceRecord {
+  name: string;
+  attrs: Attrs | null;
+  dropped: boolean;
+}
+
+export interface LogTraceRecord {
+  level: LogLevel;
+  message: string;
+  attrs: Attrs | null;
+  dropped: boolean;
+}
+
+export interface FrameTraceRecord {
+  seq: number;
+  from: number;
+  to: number;
+  counters: number;
+  gauges: number;
+  histograms: number;
+  events: number;
+  logs: number;
+  droppedLogs: number;
+  droppedEvents: number;
+}
+
+export interface SyncTraceRecord {
+  phase: 'bootstrap' | 'flush' | 'tick';
+  frames: number;
+  bytesUncompressed: number;
+  bytesCompressed: number;
+  ms: number;
+  ok: boolean;
+  status?: number;
+  configVersion?: number;
+  appliedConfig?: boolean;
+}
+
+export interface Tracer {
+  measure?(record: MeasureTraceRecord): void;
+  event?(record: EventTraceRecord): void;
+  log?(record: LogTraceRecord): void;
+  frame?(record: FrameTraceRecord): void;
+  sync?(record: SyncTraceRecord): void;
+}
+
+export interface LogApi {
+  debug(message: string, attrs?: Attrs | null): void;
+  info(message: string, attrs?: Attrs | null): void;
+  warn(message: string, attrs?: Attrs | null): void;
+  error(message: string, attrs?: Attrs | null): void;
+}
+
+export interface InternalMetricsState extends InternalSnapshot {
+  hasCounterActivity(): boolean;
+  snapshotAndReset(): InternalSnapshot;
+}
+
+export class Counter implements CounterHandle {
+  name: string;
+  dims: Dimensions | null;
+  value: number;
+  constructor(name: string, dims?: Dimensions | null);
+  inc(): void;
+  add(n: number): void;
+}
+
+export class Gauge implements GaugeHandle {
+  name: string;
+  dims: Dimensions | null;
+  value: number;
+  timestamp: number;
+  dirty: boolean;
+  constructor(name: string, dims?: Dimensions | null);
+  set(value: number): void;
+}
+
+export class Histogram implements HistogramHandle {
+  name: string;
+  dims: Dimensions | null;
+  bounds: number[];
+  maxDimensionKeys: number | null;
+  maxDimensionValueLength: number | null;
+  counts: number[];
+  count: number;
+  sum: number;
+  min: number;
+  max: number;
+  exemplar: HistogramExemplar | null;
+  constructor(
+    name: string,
+    dims: Dimensions | null,
+    bounds: number[],
+    limits?: { maxDimensionKeys: number; maxDimensionValueLength: number } | null
+  );
+  observe(value: number, attrs?: Dimensions | null): void;
+  snapshot(): HistogramSnapshot;
+  reset(): void;
+}
+
+export interface MetricsRegistryOptions {
+  maxSeriesPerMetric: number;
+  maxDimensionKeys: number;
+  maxDimensionValueLength: number;
+  defaultHistogramBuckets: number[];
+  onCardinalityDropped: () => void;
+}
+
+export class MetricsRegistry {
+  constructor(options: MetricsRegistryOptions);
+  counter(name: string, dims?: Dimensions | null): CounterHandle;
+  gauge(name: string, dims?: Dimensions | null): GaugeHandle;
+  histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;
+  timer(name: string, dims?: Dimensions | null): StopTimer;
+  snapshotAndReset(): MetricsSnapshot;
+  isDirty(): boolean;
+}
+
+export class EventBuffer {
+  max: number;
+  constructor(maxBufferedEvents: number);
+  get length(): number;
+  push(name: string, attrs?: Attrs | null): boolean;
+  swap(): EventRow[];
+}
+
+export class LogBuffer {
+  max: number;
+  constructor(maxBufferedLogs: number);
+  get length(): number;
+  push(level: LogLevel, message: string, attrs?: Attrs | null): boolean;
+  swap(): LogRow[];
+}
+
+export class ConfigStore {
+  version: number;
+  values: Record<string, ConfigValue>;
+  experiments: Experiment[];
+  experimentsByKey: Map<string, Experiment[]>;
+  applySnapshot(snapshot: { version: number } & ConfigSnapshot): void;
+  has(key: string): boolean;
+  getRaw(key: string): ConfigValue | undefined;
+}
+
+export class ExperimentResolver {
+  constructor(options: { privacySalt: string; onExposure: (payload: ExposurePayload) => void });
+  hashSubject(subjectId: string): string;
+  recordAssignment(subjectId: string, experiment: Experiment, variant: ExperimentVariant): void;
+  assignmentsFor(subjectId: string): Assignment[];
+  resolve(
+    key: string,
+    remoteValue: ConfigValue,
+    subjectId: string | null | undefined,
+    experimentsByKey: Map<string, Experiment[]>
+  ): ConfigValue;
+  relevantExperiments(subjectId: string, experiments: Experiment[]): Assignment[];
+}
+
+export class FrameBuilder {
+  static build(input: {
+    seq: number;
+    from: number;
+    to: number;
+    metrics: MetricsSnapshot;
+    events: EventRow[];
+    logs: LogRow[];
+    internal: InternalSnapshot;
+  }): Frame;
+  static mergeInternal(counters: CounterRow[], gauges: GaugeRow[], internal: InternalSnapshot): void;
+  static fitToMaxBytes(frame: Frame, maxFrameBytes: number): FittedFrame;
+}
+
+export class WardxCore {
+  settings: CoreSettings;
+  stopped: boolean;
+  internal: InternalMetricsState;
+  metrics: MetricsRegistry;
+  events: EventBuffer;
+  logs: LogBuffer;
+  configStore: ConfigStore;
+  experiments: ExperimentResolver;
+  seq: number;
+  pendingFrames: Frame[];
+  windowStart: number;
+  log: LogApi;
+  constructor(settings: CoreSettings);
+  counter(name: string, dims?: Dimensions | null): CounterHandle;
+  gauge(name: string, dims?: Dimensions | null): GaugeHandle;
+  histogram(name: string, a?: HistogramOptions | null, b?: HistogramOptions | null): HistogramHandle;
+  timer(name: string, dims?: Dimensions | null): StopTimer;
+  event(name: string, attrs?: Attrs | null): void;
+  identify(subjectId: string | null | undefined): void;
+  configGet<T>(key: string, fallback: T, context?: SubjectContext): T;
+  experimentGoal(name: string, context?: ExperimentGoalContext): void;
+  applyConfig(version: number, config: ConfigSnapshot): void;
+  snapshotIfDirty(): FittedFrame | null;
+  snapshotFrame(): FittedFrame;
+  takePendingFrames(): Frame[];
+}
+
+export function fnv1a32(input: string | Uint8Array): number;
+export function assignmentHash(experimentId: string, subjectId: string, salt: string): number;
+export function hashToUnitInterval(hash: number): number;
+export function subjectHash(projectSalt: string, subjectId: string): string;
+export function assignVariant(experiment: Experiment, subjectId: string): ExperimentVariant | null;
+export function resolveSettings(options: CreateWardxOptions): ResolvedSettings;
+export function loadSdkDefaults(): SdkDefaults;
+export function nextSyncDelayMs(settings: Pick<ResolvedSettings, 'syncIntervalMs' | 'syncJitterMin' | 'syncJitterMax'>): number;
+export function ulid(now?: number): string;