@mongrov/analytics 0.1.0-alpha.7 → 0.1.0-alpha.8

package/dist/rules/hooks/useRuleViolations.js

@@ -0,0 +1,32 @@
+/**
+ * `useRuleViolations(engine, options?)` — session-scoped violation feed.
+ *
+ * Subscribes to `engine.on('violation', ...)` for the lifetime of the
+ * component and buffers the most-recent `limit` violations in state. On
+ * unmount the subscription tears down.
+ *
+ * React is an optional peer of `@mongrov/analytics`; this file is only
+ * imported when the app pulls the `/rules` subpath.
+ */
+import { useEffect, useState, useCallback } from 'react';
+const DEFAULT_LIMIT = 50;
+export function useRuleViolations(engine, options) {
+    const limit = options?.limit ?? DEFAULT_LIMIT;
+    const [violations, setViolations] = useState([]);
+    useEffect(() => {
+        const unsub = engine.on('violation', (v) => {
+            setViolations((prev) => {
+                const next = [v, ...prev];
+                if (next.length > limit)
+                    next.length = limit;
+                return next;
+            });
+        });
+        return unsub;
+    }, [engine, limit]);
+    const clear = useCallback(() => {
+        setViolations([]);
+    }, []);
+    return { violations, clear };
+}
+//# sourceMappingURL=useRuleViolations.js.map

package/dist/rules/hooks/useRuleViolations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRuleViolations.js","sourceRoot":"","sources":["../../../src/rules/hooks/useRuleViolations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGxD,MAAM,aAAa,GAAG,EAAE,CAAA;AAYxB,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,OAAkC;IAElC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,aAAa,CAAA;IAC7C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAkB,EAAE,CAAC,CAAA;IAEjE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;YACzC,aAAa,CAAC,CAAC,IAAI,EAAE,EAAE;gBACrB,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAA;gBACzB,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK;oBAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;gBAC5C,OAAO,IAAI,CAAA;YACb,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QACF,OAAO,KAAK,CAAA;IACd,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;IAEnB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,aAAa,CAAC,EAAE,CAAC,CAAA;IACnB,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAA;AAC9B,CAAC"}

package/dist/rules/index.d.ts

@@ -1,2 +1,31 @@
-export {};
+/**
+ * @mongrov/analytics/rules — structured threshold rule engine.
+ *
+ * See `README.md` for authoring rules, sampling minimums, brand default
+ * catalogs, and hooks. Consumers typically:
+ *
+ * ```ts
+ * import {
+ *   createRulesEngine,
+ *   defaults,
+ * } from '@mongrov/analytics/rules';
+ *
+ * const engine = createRulesEngine({ analytics, storage, brand: 'ziva', ... });
+ * await engine.register(defaults.zivaDefaults);
+ * engine.on('violation', (v) => notify(v));
+ * ```
+ */
+export { RuleSchema, RuleValidationError, TargetSchema, ThrottleSchema, AGGREGATIONS, COMPARES, SEVERITIES, WINDOWS, } from './schema';
+export type { Aggregation, Compare, Rule, Severity, Target, Throttle, Window, } from './schema';
+export type { Clock, CompiledRule, FlushSummary, RuleSeverity, RuleViolation, RulesEngine, RulesEngineConfig, RulesLogger, Unsubscribe, } from './types';
+export { allowedWindowsFor, validateRule } from './validator';
+export { compileRule, sanitizeIdent } from './compiler';
+export { createCompilerCache, type CompilerCache } from './compiler-cache';
+export { createRulesRegistry, type CreateRegistryConfig, type RulesRegistry, } from './registry';
+export { createThrottleStore, type CreateThrottleConfig, type ThrottleStore, } from './throttle';
+export { createEmitter, type CreateEmitterConfig, type RulesEmitter, } from './emitter';
+export { createRulesEngine } from './factory';
+export * as defaults from './defaults';
+export { useRuleViolations, type UseRuleViolationsOptions, type UseRuleViolationsResult, } from './hooks/useRuleViolations';
+export { useRuleRegistry, type UseRuleRegistryResult, } from './hooks/useRuleRegistry';
 //# sourceMappingURL=index.d.ts.map

package/dist/rules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,OAAO,GACR,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,WAAW,EACX,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,MAAM,GACP,MAAM,UAAU,CAAA;AAEjB,YAAY,EACV,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,WAAW,GACZ,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG7D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAI1E,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,YAAY,GAClB,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAG7C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA;AAGtC,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,GAC3B,MAAM,yBAAyB,CAAA"}

package/dist/rules/index.js

@@ -1,2 +1,37 @@
-export {};
+/**
+ * @mongrov/analytics/rules — structured threshold rule engine.
+ *
+ * See `README.md` for authoring rules, sampling minimums, brand default
+ * catalogs, and hooks. Consumers typically:
+ *
+ * ```ts
+ * import {
+ *   createRulesEngine,
+ *   defaults,
+ * } from '@mongrov/analytics/rules';
+ *
+ * const engine = createRulesEngine({ analytics, storage, brand: 'ziva', ... });
+ * await engine.register(defaults.zivaDefaults);
+ * engine.on('violation', (v) => notify(v));
+ * ```
+ */
+// R1 — schema + types
+export { RuleSchema, RuleValidationError, TargetSchema, ThrottleSchema, AGGREGATIONS, COMPARES, SEVERITIES, WINDOWS, } from './schema';
+// R2 — validator
+export { allowedWindowsFor, validateRule } from './validator';
+// R3 — compiler + cache
+export { compileRule, sanitizeIdent } from './compiler';
+export { createCompilerCache } from './compiler-cache';
+// R4-R6 — registry / throttle / emitter (exposed for advanced composition
+// or test doubles; typical apps go through `createRulesEngine`).
+export { createRulesRegistry, } from './registry';
+export { createThrottleStore, } from './throttle';
+export { createEmitter, } from './emitter';
+// R9 — factory
+export { createRulesEngine } from './factory';
+// R8 — brand defaults
+export * as defaults from './defaults';
+// R10 — hooks
+export { useRuleViolations, } from './hooks/useRuleViolations';
+export { useRuleRegistry, } from './hooks/useRuleRegistry';
 //# sourceMappingURL=index.js.map

package/dist/rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sBAAsB;AACtB,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,OAAO,GACR,MAAM,UAAU,CAAA;AAuBjB,iBAAiB;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE7D,wBAAwB;AACxB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAsB,MAAM,kBAAkB,CAAA;AAE1E,0EAA0E;AAC1E,iEAAiE;AACjE,OAAO,EACL,mBAAmB,GAGpB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,mBAAmB,GAGpB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,aAAa,GAGd,MAAM,WAAW,CAAA;AAElB,eAAe;AACf,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAE7C,sBAAsB;AACtB,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAA;AAEtC,cAAc;AACd,OAAO,EACL,iBAAiB,GAGlB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,eAAe,GAEhB,MAAM,yBAAyB,CAAA"}

package/dist/rules/registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-memory rule registry with KV-persisted `enabled` state.
+ *
+ * Every register/enable/disable bumps `rev` — the compiler cache keys on
+ * `(ruleId, rev)`, so mutations transparently invalidate compiled SQL.
+ *
+ * The `subscribe(listener)` surface backs the `useRuleRegistry` hook via
+ * `useSyncExternalStore`.
+ */
+import type { KVStore, Unsubscribe } from '../core/types';
+import type { MetricId } from '../core/metric_metadata';
+import { type Rule } from './schema';
+import type { RulesLogger } from './types';
+export interface RulesRegistry {
+    register(rules: Rule[]): Promise<void>;
+    enable(ruleId: string): Promise<void>;
+    disable(ruleId: string): Promise<void>;
+    list(): Rule[];
+    getActive(): Rule[];
+    getByMetric(metric: MetricId): Rule[];
+    getByBrand(brand: string): Rule[];
+    subscribe(listener: () => void): Unsubscribe;
+    readonly rev: number;
+}
+export interface CreateRegistryConfig {
+    storage: KVStore;
+    logger?: RulesLogger;
+    /** Brand assigned to rules with no explicit `brand` field. Default `ziva`. */
+    defaultBrand?: string;
+}
+export declare function createRulesRegistry({ storage, logger, defaultBrand, }: CreateRegistryConfig): RulesRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/rules/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/rules/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAmC,KAAK,IAAI,EAAE,MAAM,UAAU,CAAA;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAQ1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,IAAI,IAAI,EAAE,CAAA;IACd,SAAS,IAAI,IAAI,EAAE,CAAA;IACnB,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,CAAA;IACrC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAAA;IACjC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,WAAW,CAAA;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAM,EACN,YAAqB,GACtB,EAAE,oBAAoB,GAAG,aAAa,CA2FtC"}

package/dist/rules/registry.js

@@ -0,0 +1,98 @@
+/**
+ * In-memory rule registry with KV-persisted `enabled` state.
+ *
+ * Every register/enable/disable bumps `rev` — the compiler cache keys on
+ * `(ruleId, rev)`, so mutations transparently invalidate compiled SQL.
+ *
+ * The `subscribe(listener)` surface backs the `useRuleRegistry` hook via
+ * `useSyncExternalStore`.
+ */
+import { RuleSchema, RuleValidationError } from './schema';
+import { validateRule } from './validator';
+const KV_ENABLED_PREFIX = 'analytics:rules:';
+function enabledKey(ruleId) {
+    return `${KV_ENABLED_PREFIX}${ruleId}:enabled`;
+}
+export function createRulesRegistry({ storage, logger, defaultBrand = 'ziva', }) {
+    const entries = new Map();
+    const listeners = new Set();
+    let rev = 0;
+    function notify() {
+        rev += 1;
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                logger?.error('rules.registry: listener threw', {
+                    err: err.message,
+                });
+            }
+        }
+    }
+    return {
+        async register(rules) {
+            // Validate everything up-front — fail fast on first bad rule.
+            const validated = [];
+            for (const raw of rules) {
+                const parsed = RuleSchema.parse(raw);
+                validateRule(parsed, logger);
+                validated.push(parsed);
+            }
+            for (const rule of validated) {
+                const persisted = await storage.get(enabledKey(rule.id));
+                entries.set(rule.id, {
+                    rule,
+                    enabled: persisted ?? true,
+                });
+            }
+            logger?.info('rules.registry: registered', { count: validated.length });
+            notify();
+        },
+        async enable(ruleId) {
+            const entry = entries.get(ruleId);
+            if (!entry) {
+                throw new RuleValidationError(`Rule ${ruleId} not registered.`);
+            }
+            entry.enabled = true;
+            await storage.set(enabledKey(ruleId), true);
+            notify();
+        },
+        async disable(ruleId) {
+            const entry = entries.get(ruleId);
+            if (!entry) {
+                throw new RuleValidationError(`Rule ${ruleId} not registered.`);
+            }
+            entry.enabled = false;
+            await storage.set(enabledKey(ruleId), false);
+            notify();
+        },
+        list() {
+            return Array.from(entries.values()).map(e => e.rule);
+        },
+        getActive() {
+            const active = [];
+            for (const entry of entries.values()) {
+                if (entry.enabled)
+                    active.push(entry.rule);
+            }
+            return active;
+        },
+        getByMetric(metric) {
+            return this.getActive().filter(r => r.metric === metric);
+        },
+        getByBrand(brand) {
+            return this.getActive().filter(r => (r.brand ?? defaultBrand) === brand);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        get rev() {
+            return rev;
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/rules/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/rules/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAa,MAAM,UAAU,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C,MAAM,iBAAiB,GAAG,kBAAkB,CAAA;AAE5C,SAAS,UAAU,CAAC,MAAc;IAChC,OAAO,GAAG,iBAAiB,GAAG,MAAM,UAAU,CAAA;AAChD,CAAC;AAqBD,MAAM,UAAU,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAM,EACN,YAAY,GAAG,MAAM,GACA;IACrB,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAA;IACnE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,IAAI,GAAG,GAAG,CAAC,CAAA;IAEX,SAAS,MAAM;QACb,GAAG,IAAI,CAAC,CAAA;QACR,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,QAAQ,EAAE,CAAA;YACZ,CAAC;YACD,OAAO,GAAG,EAAE,CAAC;gBACX,MAAM,EAAE,KAAK,CAAC,gCAAgC,EAAE;oBAC9C,GAAG,EAAG,GAAa,CAAC,OAAO;iBAC5B,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,KAAK;YAClB,8DAA8D;YAC9D,MAAM,SAAS,GAAW,EAAE,CAAA;YAC5B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;gBACpC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;gBAC5B,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACxB,CAAC;YAED,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CAAU,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;gBACjE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE;oBACnB,IAAI;oBACJ,OAAO,EAAE,SAAS,IAAI,IAAI;iBAC3B,CAAC,CAAA;YACJ,CAAC;YACD,MAAM,EAAE,IAAI,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAA;YACvE,MAAM,EAAE,CAAA;QACV,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,MAAM;YACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACjC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,mBAAmB,CAAC,QAAQ,MAAM,kBAAkB,CAAC,CAAA;YACjE,CAAC;YACD,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;YACpB,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAA;YAC3C,MAAM,EAAE,CAAA;QACV,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACjC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,mBAAmB,CAAC,QAAQ,MAAM,kBAAkB,CAAC,CAAA;YACjE,CAAC;YACD,KAAK,CAAC,OAAO,GAAG,KAAK,CAAA;YACrB,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAA;YAC5C,MAAM,EAAE,CAAA;QACV,CAAC;QAED,IAAI;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACtD,CAAC;QAED,SAAS;YACP,MAAM,MAAM,GAAW,EAAE,CAAA;YACzB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBACrC,IAAI,KAAK,CAAC,OAAO;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC5C,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;QAED,WAAW,CAAC,MAAM;YAChB,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAA;QAC1D,CAAC;QAED,UAAU,CAAC,KAAK;YACd,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,YAAY,CAAC,KAAK,KAAK,CAAC,CAAA;QAC1E,CAAC;QAED,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC5B,CAAC,CAAA;QACH,CAAC;QAED,IAAI,GAAG;YACL,OAAO,GAAG,CAAA;QACZ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/rules/schema.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Zod schema for structured threshold rules (spec §Rule schema).
+ *
+ * The `metric` enum is generated at module load from the frozen
+ * `METRIC_METADATA` registry — only metrics with `exposure: 'full'` are
+ * accepted. Rules referencing `collected_only` metrics can still ship
+ * via `rawSql` + `exposureOverride: true` (see validator.ts).
+ */
+import { z } from 'zod';
+/** Custom error class for rule-schema / validator failures. */
+export declare class RuleValidationError extends Error {
+    constructor(message: string);
+}
+export declare const WINDOWS: readonly ["1h", "6h", "24h", "3d", "7d", "30d"];
+export type Window = (typeof WINDOWS)[number];
+export declare const AGGREGATIONS: readonly ["avg", "min", "max", "sum", "last", "count"];
+export type Aggregation = (typeof AGGREGATIONS)[number];
+export declare const COMPARES: readonly ["less_than", "greater_than", "equals", "not_equals", "between"];
+export type Compare = (typeof COMPARES)[number];
+export declare const SEVERITIES: readonly ["info", "warn", "critical"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const TargetSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"absolute">;
+    value: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "absolute";
+    value: number;
+}, {
+    type: "absolute";
+    value: number;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"baseline_percent">;
+    windowDays: z.ZodNumber;
+    percent: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "baseline_percent";
+    windowDays: number;
+    percent: number;
+}, {
+    type: "baseline_percent";
+    windowDays: number;
+    percent: number;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"baseline_stddev">;
+    windowDays: z.ZodNumber;
+    stddevs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "baseline_stddev";
+    windowDays: number;
+    stddevs: number;
+}, {
+    type: "baseline_stddev";
+    windowDays: number;
+    stddevs: number;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"range">;
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: "range";
+    min: number;
+    max: number;
+}, {
+    type: "range";
+    min: number;
+    max: number;
+}>]>;
+export type Target = z.infer<typeof TargetSchema>;
+export declare const ThrottleSchema: z.ZodDefault<z.ZodObject<{
+    minGapMinutes: z.ZodDefault<z.ZodNumber>;
+    maxPerDay: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    minGapMinutes: number;
+    maxPerDay: number;
+}, {
+    minGapMinutes?: number | undefined;
+    maxPerDay?: number | undefined;
+}>>;
+export type Throttle = z.infer<typeof ThrottleSchema>;
+export declare const RuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    brand: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    metric: z.ZodEnum<["spo2" | "hrv_ms" | "stress" | "systolic_bp" | "diastolic_bp" | "vascular_aging" | "hr_bpm" | "temp_c" | "activity_steps" | "calories" | "distance_km" | "sleep_total_minutes" | "sleep_score" | "device_battery", ...("spo2" | "hrv_ms" | "stress" | "systolic_bp" | "diastolic_bp" | "vascular_aging" | "hr_bpm" | "temp_c" | "activity_steps" | "calories" | "distance_km" | "sleep_total_minutes" | "sleep_score" | "device_battery")[]]>;
+    window: z.ZodEnum<["1h", "6h", "24h", "3d", "7d", "30d"]>;
+    aggregation: z.ZodDefault<z.ZodEnum<["avg", "min", "max", "sum", "last", "count"]>>;
+    compare: z.ZodEnum<["less_than", "greater_than", "equals", "not_equals", "between"]>;
+    target: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"absolute">;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "absolute";
+        value: number;
+    }, {
+        type: "absolute";
+        value: number;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"baseline_percent">;
+        windowDays: z.ZodNumber;
+        percent: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "baseline_percent";
+        windowDays: number;
+        percent: number;
+    }, {
+        type: "baseline_percent";
+        windowDays: number;
+        percent: number;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"baseline_stddev">;
+        windowDays: z.ZodNumber;
+        stddevs: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "baseline_stddev";
+        windowDays: number;
+        stddevs: number;
+    }, {
+        type: "baseline_stddev";
+        windowDays: number;
+        stddevs: number;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"range">;
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "range";
+        min: number;
+        max: number;
+    }, {
+        type: "range";
+        min: number;
+        max: number;
+    }>]>;
+    severity: z.ZodEnum<["info", "warn", "critical"]>;
+    throttle: z.ZodDefault<z.ZodObject<{
+        minGapMinutes: z.ZodDefault<z.ZodNumber>;
+        maxPerDay: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        minGapMinutes: number;
+        maxPerDay: number;
+    }, {
+        minGapMinutes?: number | undefined;
+        maxPerDay?: number | undefined;
+    }>>;
+    rawSql: z.ZodOptional<z.ZodString>;
+    rawSqlParams: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Required-true when `rawSql` references `collected_only` columns
+     * (BP, vascular aging). Validator enforces.
+     */
+    exposureOverride: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    target: {
+        type: "absolute";
+        value: number;
+    } | {
+        type: "baseline_percent";
+        windowDays: number;
+        percent: number;
+    } | {
+        type: "baseline_stddev";
+        windowDays: number;
+        stddevs: number;
+    } | {
+        type: "range";
+        min: number;
+        max: number;
+    };
+    name: string;
+    metric: "spo2" | "hrv_ms" | "stress" | "systolic_bp" | "diastolic_bp" | "vascular_aging" | "hr_bpm" | "temp_c" | "activity_steps" | "calories" | "distance_km" | "sleep_total_minutes" | "sleep_score" | "device_battery";
+    window: "1h" | "6h" | "24h" | "3d" | "7d" | "30d";
+    aggregation: "avg" | "min" | "max" | "sum" | "last" | "count";
+    compare: "less_than" | "greater_than" | "equals" | "not_equals" | "between";
+    severity: "info" | "warn" | "critical";
+    throttle: {
+        minGapMinutes: number;
+        maxPerDay: number;
+    };
+    description?: string | undefined;
+    brand?: string | undefined;
+    rawSql?: string | undefined;
+    rawSqlParams?: string[] | undefined;
+    exposureOverride?: boolean | undefined;
+}, {
+    id: string;
+    target: {
+        type: "absolute";
+        value: number;
+    } | {
+        type: "baseline_percent";
+        windowDays: number;
+        percent: number;
+    } | {
+        type: "baseline_stddev";
+        windowDays: number;
+        stddevs: number;
+    } | {
+        type: "range";
+        min: number;
+        max: number;
+    };
+    name: string;
+    metric: "spo2" | "hrv_ms" | "stress" | "systolic_bp" | "diastolic_bp" | "vascular_aging" | "hr_bpm" | "temp_c" | "activity_steps" | "calories" | "distance_km" | "sleep_total_minutes" | "sleep_score" | "device_battery";
+    window: "1h" | "6h" | "24h" | "3d" | "7d" | "30d";
+    compare: "less_than" | "greater_than" | "equals" | "not_equals" | "between";
+    severity: "info" | "warn" | "critical";
+    description?: string | undefined;
+    brand?: string | undefined;
+    aggregation?: "avg" | "min" | "max" | "sum" | "last" | "count" | undefined;
+    throttle?: {
+        minGapMinutes?: number | undefined;
+        maxPerDay?: number | undefined;
+    } | undefined;
+    rawSql?: string | undefined;
+    rawSqlParams?: string[] | undefined;
+    exposureOverride?: boolean | undefined;
+}>;
+export type Rule = z.infer<typeof RuleSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/rules/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/rules/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,+DAA+D;AAC/D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAID,eAAO,MAAM,OAAO,iDAAkD,CAAA;AACtE,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7C,eAAO,MAAM,YAAY,wDAAyD,CAAA;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvD,eAAO,MAAM,QAAQ,2EAMX,CAAA;AACV,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/C,eAAO,MAAM,UAAU,uCAAwC,CAAA;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAyBlD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAKvB,CAAA;AACF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEjD,eAAO,MAAM,cAAc;;;;;;;;;GAKb,CAAA;AAEd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAErD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcrB;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAA;AAEF,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA"}

package/dist/rules/schema.js

@@ -0,0 +1,80 @@
+/**
+ * Zod schema for structured threshold rules (spec §Rule schema).
+ *
+ * The `metric` enum is generated at module load from the frozen
+ * `METRIC_METADATA` registry — only metrics with `exposure: 'full'` are
+ * accepted. Rules referencing `collected_only` metrics can still ship
+ * via `rawSql` + `exposureOverride: true` (see validator.ts).
+ */
+import { z } from 'zod';
+import { getExposedMetricIds } from '../core/metric_metadata';
+/** Custom error class for rule-schema / validator failures. */
+export class RuleValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RuleValidationError';
+    }
+}
+const exposedMetricIds = getExposedMetricIds();
+export const WINDOWS = ['1h', '6h', '24h', '3d', '7d', '30d'];
+export const AGGREGATIONS = ['avg', 'min', 'max', 'sum', 'last', 'count'];
+export const COMPARES = [
+    'less_than',
+    'greater_than',
+    'equals',
+    'not_equals',
+    'between',
+];
+export const SEVERITIES = ['info', 'warn', 'critical'];
+const TargetAbsolute = z.object({
+    type: z.literal('absolute'),
+    value: z.number(),
+});
+const TargetBaselinePercent = z.object({
+    type: z.literal('baseline_percent'),
+    windowDays: z.number().int().positive(),
+    percent: z.number().positive(),
+});
+const TargetBaselineStddev = z.object({
+    type: z.literal('baseline_stddev'),
+    windowDays: z.number().int().positive(),
+    stddevs: z.number(),
+});
+const TargetRange = z.object({
+    type: z.literal('range'),
+    min: z.number(),
+    max: z.number(),
+});
+export const TargetSchema = z.discriminatedUnion('type', [
+    TargetAbsolute,
+    TargetBaselinePercent,
+    TargetBaselineStddev,
+    TargetRange,
+]);
+export const ThrottleSchema = z
+    .object({
+    minGapMinutes: z.number().nonnegative().default(60),
+    maxPerDay: z.number().int().positive().default(3),
+})
+    .default({});
+export const RuleSchema = z.object({
+    id: z.string().min(1),
+    brand: z.string().optional(),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    metric: z.enum(exposedMetricIds),
+    window: z.enum(WINDOWS),
+    aggregation: z.enum(AGGREGATIONS).default('avg'),
+    compare: z.enum(COMPARES),
+    target: TargetSchema,
+    severity: z.enum(SEVERITIES),
+    throttle: ThrottleSchema,
+    rawSql: z.string().optional(),
+    rawSqlParams: z.array(z.string()).optional(),
+    /**
+     * Required-true when `rawSql` references `collected_only` columns
+     * (BP, vascular aging). Validator enforces.
+     */
+    exposureOverride: z.boolean().optional(),
+});
+//# sourceMappingURL=schema.js.map

package/dist/rules/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/rules/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAiB,MAAM,yBAAyB,CAAA;AAE5E,+DAA+D;AAC/D,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,mBAAmB,EAA+B,CAAA;AAE3E,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAU,CAAA;AAGtE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAU,CAAA;AAGlF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,WAAW;IACX,cAAc;IACd,QAAQ;IACR,YAAY;IACZ,SAAS;CACD,CAAA;AAGV,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAA;AAG/D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAA;AAEF,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAA;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;CAChB,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACvD,cAAc;IACd,qBAAqB;IACrB,oBAAoB;IACpB,WAAW;CACZ,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACnD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CAClD,CAAC;KACD,OAAO,CAAC,EAAE,CAAC,CAAA;AAId,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IACvB,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IACzB,MAAM,EAAE,YAAY;IACpB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IAC5B,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC5C;;;OAGG;IACH,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAA"}

package/dist/rules/throttle.d.ts

@@ -0,0 +1,27 @@
+/**
+ * KV-backed throttle store for rule fires.
+ *
+ * Two keys per (rule, user):
+ *   - `analytics:rules:throttle:{ruleId}:{userId}:last` → ISO date string
+ *   - `analytics:rules:throttle:{ruleId}:{userId}:count:{yyyy-mm-dd}` → number
+ *
+ * Order of checks: min-gap first, then daily cap. Stale daily-count
+ * entries (from earlier days) are best-effort deleted on next-day reads.
+ *
+ * All time reads go through an injected `clock: () => Date` so tests can
+ * pin the wall clock. Production defaults to `() => new Date()`.
+ */
+import type { KVStore } from '../core/types';
+import type { Clock, RulesLogger } from './types';
+import type { Throttle } from './schema';
+export interface ThrottleStore {
+    isThrottled(ruleId: string, userId: string, throttle: Throttle): Promise<boolean>;
+    recordFire(ruleId: string, userId: string): Promise<void>;
+}
+export interface CreateThrottleConfig {
+    storage: KVStore;
+    clock?: Clock;
+    logger?: RulesLogger;
+}
+export declare function createThrottleStore({ storage, clock, logger, }: CreateThrottleConfig): ThrottleStore;
+//# sourceMappingURL=throttle.d.ts.map

package/dist/rules/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/rules/throttle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAoBxC,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACjF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,KAAwB,EACxB,MAAM,GACP,EAAE,oBAAoB,GAAG,aAAa,CAmDtC"}