@lssm/lib.personalization 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @lssm/lib.personalization
+
+Composable behavior tracking and personalization primitives for ContractSpec applications. The library provides trackers that capture feature usage, analyzers that transform raw events into adaptation hints, and adapters that feed personalized overlays or workflow tweaks.
+
+## Modules
+
+- `tracker` – lightweight tracker helpers that record field/feature/workflow usage.
+- `store` – store abstractions plus an in-memory implementation.
+- `analyzer` – stateless analyzers that convert usage data into insights.
+- `adapter` – bridges insights into OverlaySpecs or WorkflowComposer extensions.
+
+See `docs/tech/personalization/behavior-tracking.md` for full usage notes.
+
+
+
+
+

package/dist/adapter.d.ts

@@ -0,0 +1,22 @@
+import { BehaviorInsights } from "./types.js";
+import { OverlaySpec } from "@lssm/lib.overlay-engine";
+
+//#region src/adapter.d.ts
+interface OverlaySuggestionOptions {
+  overlayId: string;
+  tenantId: string;
+  capability: string;
+  userId?: string;
+  role?: string;
+  version?: string;
+}
+interface WorkflowAdaptation {
+  workflow: string;
+  step: string;
+  note: string;
+}
+declare function insightsToOverlaySuggestion(insights: BehaviorInsights, options: OverlaySuggestionOptions): OverlaySpec | null;
+declare function insightsToWorkflowAdaptations(insights: BehaviorInsights): WorkflowAdaptation[];
+//#endregion
+export { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../src/adapter.ts"],"sourcesContent":[],"mappings":";;;;UAMiB,wBAAA;;EAAA,QAAA,EAAA,MAAA;EASA,UAAA,EAAA,MAAA;EAMD,MAAA,CAAA,EAAA,MAAA;EACJ,IAAA,CAAA,EAAA,MAAA;EACD,OAAA,CAAA,EAAA,MAAA;;AACG,UATG,kBAAA,CASH;EAuCE,QAAA,EAAA,MAAA;;;;iBA1CA,2BAAA,WACJ,2BACD,2BACR;iBAuCa,6BAAA,WACJ,mBACT"}

package/dist/adapter.js

@@ -0,0 +1,2 @@
+function e(e,t){let n=[];return e.suggestedHiddenFields.forEach(e=>{n.push({type:`hideField`,field:e,reason:`Automatically hidden because usage is near zero`})}),e.frequentlyUsedFields.length&&n.push({type:`reorderFields`,fields:e.frequentlyUsedFields}),n.length?{overlayId:t.overlayId,version:t.version??`1.0.0`,appliesTo:{tenantId:t.tenantId,capability:t.capability,userId:t.userId,role:t.role},modifications:n,metadata:{generatedAt:new Date().toISOString(),automated:!0}}:null}function t(e){return e.workflowBottlenecks.map(e=>({workflow:e.workflow,step:e.step,note:`High drop rate (${Math.round(e.dropRate*100)}%) detected`}))}export{e as insightsToOverlaySuggestion,t as insightsToWorkflowAdaptations};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["modifications: OverlayModification[]"],"sources":["../src/adapter.ts"],"sourcesContent":["import type {\n  OverlayModification,\n  OverlaySpec,\n} from '@lssm/lib.overlay-engine';\nimport type { BehaviorInsights } from './types';\n\nexport interface OverlaySuggestionOptions {\n  overlayId: string;\n  tenantId: string;\n  capability: string;\n  userId?: string;\n  role?: string;\n  version?: string;\n}\n\nexport interface WorkflowAdaptation {\n  workflow: string;\n  step: string;\n  note: string;\n}\n\nexport function insightsToOverlaySuggestion(\n  insights: BehaviorInsights,\n  options: OverlaySuggestionOptions\n): OverlaySpec | null {\n  const modifications: OverlayModification[] = [];\n\n  insights.suggestedHiddenFields.forEach((field) => {\n    modifications.push({\n      type: 'hideField',\n      field,\n      reason: 'Automatically hidden because usage is near zero',\n    });\n  });\n\n  if (insights.frequentlyUsedFields.length) {\n    modifications.push({\n      type: 'reorderFields',\n      fields: insights.frequentlyUsedFields,\n    });\n  }\n\n  if (!modifications.length) {\n    return null;\n  }\n\n  return {\n    overlayId: options.overlayId,\n    version: options.version ?? '1.0.0',\n    appliesTo: {\n      tenantId: options.tenantId,\n      capability: options.capability,\n      userId: options.userId,\n      role: options.role,\n    },\n    modifications,\n    metadata: {\n      generatedAt: new Date().toISOString(),\n      automated: true,\n    },\n  };\n}\n\nexport function insightsToWorkflowAdaptations(\n  insights: BehaviorInsights\n): WorkflowAdaptation[] {\n  return insights.workflowBottlenecks.map((bottleneck) => ({\n    workflow: bottleneck.workflow,\n    step: bottleneck.step,\n    note: `High drop rate (${Math.round(bottleneck.dropRate * 100)}%) detected`,\n  }));\n}\n"],"mappings":"AAqBA,SAAgB,EACd,EACA,EACoB,CACpB,IAAMA,EAAuC,EAAE,CAqB/C,OAnBA,EAAS,sBAAsB,QAAS,GAAU,CAChD,EAAc,KAAK,CACjB,KAAM,YACN,QACA,OAAQ,kDACT,CAAC,EACF,CAEE,EAAS,qBAAqB,QAChC,EAAc,KAAK,CACjB,KAAM,gBACN,OAAQ,EAAS,qBAClB,CAAC,CAGC,EAAc,OAIZ,CACL,UAAW,EAAQ,UACnB,QAAS,EAAQ,SAAW,QAC5B,UAAW,CACT,SAAU,EAAQ,SAClB,WAAY,EAAQ,WACpB,OAAQ,EAAQ,OAChB,KAAM,EAAQ,KACf,CACD,gBACA,SAAU,CACR,YAAa,IAAI,MAAM,CAAC,aAAa,CACrC,UAAW,GACZ,CACF,CAjBQ,KAoBX,SAAgB,EACd,EACsB,CACtB,OAAO,EAAS,oBAAoB,IAAK,IAAgB,CACvD,SAAU,EAAW,SACrB,KAAM,EAAW,KACjB,KAAM,mBAAmB,KAAK,MAAM,EAAW,SAAW,IAAI,CAAC,aAChE,EAAE"}

package/dist/analyzer.d.ts

@@ -0,0 +1,23 @@
+import { BehaviorInsights } from "./types.js";
+import { BehaviorStore } from "./store.js";
+
+//#region src/analyzer.d.ts
+interface BehaviorAnalyzerOptions {
+  fieldInactivityThreshold?: number;
+  minSamples?: number;
+}
+interface AnalyzeParams {
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  windowMs?: number;
+}
+declare class BehaviorAnalyzer {
+  private readonly store;
+  private readonly options;
+  constructor(store: BehaviorStore, options?: BehaviorAnalyzerOptions);
+  analyze(params: AnalyzeParams): Promise<BehaviorInsights>;
+}
+//#endregion
+export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions };
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","names":[],"sources":["../src/analyzer.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,uBAAA;;EAAA,UAAA,CAAA,EAAA,MAAA;AAKjB;AASa,UATI,aAAA,CASY;EAED,QAAA,EAAA,MAAA;EACE,MAAA,CAAA,EAAA,MAAA;EAGN,IAAA,CAAA,EAAA,MAAA;EAAwB,QAAA,CAAA,EAAA,MAAA;;AAAD,cANlC,gBAAA,CAMkC;;;qBAJnB,yBACE;kBAGN,gBAAgB,QAAQ"}

package/dist/analyzer.js

@@ -0,0 +1,2 @@
+var e=class{constructor(e,t={}){this.store=e,this.options=t}async analyze(e){let n={tenantId:e.tenantId,userId:e.userId,role:e.role};return e.windowMs&&(n.since=Date.now()-e.windowMs),t(await this.store.summarize(n),this.options)}};function t(e,t){let r=t.fieldInactivityThreshold??3,i=t.minSamples??10,a=[],o=[];for(let[t,n]of Object.entries(e.fieldCounts))n<=r&&a.push(t),n>=r*4&&o.push(t);let s=Object.entries(e.workflowStepCounts).flatMap(([e,t])=>{let n=Object.values(t).reduce((e,t)=>e+t,0);return!n||n<i?[]:Object.entries(t).filter(([,e])=>e/n<.4).map(([t,r])=>({workflow:e,step:t,dropRate:1-r/n}))}),c=n(e);return{unusedFields:a,suggestedHiddenFields:a.slice(0,5),frequentlyUsedFields:o.slice(0,10),workflowBottlenecks:s,layoutPreference:c}}function n(e){let t=Object.keys(e.fieldCounts).length;if(t)return t>=15?`table`:t>=8?`grid`:`form`}export{e as BehaviorAnalyzer};
+//# sourceMappingURL=analyzer.js.map

package/dist/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","names":["store: BehaviorStore","options: BehaviorAnalyzerOptions","query: BehaviorQuery","ignoredFields: string[]","frequentlyUsedFields: string[]"],"sources":["../src/analyzer.ts"],"sourcesContent":["import type { BehaviorStore } from './store';\nimport type { BehaviorInsights, BehaviorQuery, BehaviorSummary } from './types';\n\nexport interface BehaviorAnalyzerOptions {\n  fieldInactivityThreshold?: number;\n  minSamples?: number;\n}\n\nexport interface AnalyzeParams {\n  tenantId: string;\n  userId?: string;\n  role?: string;\n  windowMs?: number;\n}\n\nconst DEFAULT_THRESHOLD = 3;\n\nexport class BehaviorAnalyzer {\n  constructor(\n    private readonly store: BehaviorStore,\n    private readonly options: BehaviorAnalyzerOptions = {}\n  ) {}\n\n  async analyze(params: AnalyzeParams): Promise<BehaviorInsights> {\n    const query: BehaviorQuery = {\n      tenantId: params.tenantId,\n      userId: params.userId,\n      role: params.role,\n    };\n\n    if (params.windowMs) {\n      query.since = Date.now() - params.windowMs;\n    }\n\n    const summary = await this.store.summarize(query);\n    return buildInsights(summary, this.options);\n  }\n}\n\nfunction buildInsights(\n  summary: BehaviorSummary,\n  options: BehaviorAnalyzerOptions\n): BehaviorInsights {\n  const threshold = options.fieldInactivityThreshold ?? DEFAULT_THRESHOLD;\n  const minSamples = options.minSamples ?? 10;\n\n  const ignoredFields: string[] = [];\n  const frequentlyUsedFields: string[] = [];\n\n  for (const [field, count] of Object.entries(summary.fieldCounts)) {\n    if (count <= threshold) {\n      ignoredFields.push(field);\n    }\n    if (count >= threshold * 4) {\n      frequentlyUsedFields.push(field);\n    }\n  }\n\n  const workflowBottlenecks = Object.entries(\n    summary.workflowStepCounts\n  ).flatMap(([workflow, steps]) => {\n    const total = Object.values(steps).reduce((acc, value) => acc + value, 0);\n    if (!total || total < minSamples) {\n      return [];\n    }\n    return Object.entries(steps)\n      .filter(([, count]) => count / total < 0.4)\n      .map(([step, count]) => ({\n        workflow,\n        step,\n        dropRate: 1 - count / total,\n      }));\n  });\n\n  const layoutPreference = detectLayout(summary);\n\n  return {\n    unusedFields: ignoredFields,\n    suggestedHiddenFields: ignoredFields.slice(0, 5),\n    frequentlyUsedFields: frequentlyUsedFields.slice(0, 10),\n    workflowBottlenecks,\n    layoutPreference,\n  };\n}\n\nfunction detectLayout(\n  summary: BehaviorSummary\n): BehaviorInsights['layoutPreference'] {\n  const fieldCount = Object.keys(summary.fieldCounts).length;\n  if (!fieldCount) {\n    return undefined;\n  }\n\n  if (fieldCount >= 15) {\n    return 'table';\n  }\n  if (fieldCount >= 8) {\n    return 'grid';\n  }\n  return 'form';\n}\n"],"mappings":"AAiBA,IAAa,EAAb,KAA8B,CAC5B,YACE,EACA,EAAoD,EAAE,CACtD,CAFiB,KAAA,MAAA,EACA,KAAA,QAAA,EAGnB,MAAM,QAAQ,EAAkD,CAC9D,IAAME,EAAuB,CAC3B,SAAU,EAAO,SACjB,OAAQ,EAAO,OACf,KAAM,EAAO,KACd,CAOD,OALI,EAAO,WACT,EAAM,MAAQ,KAAK,KAAK,CAAG,EAAO,UAI7B,EADS,MAAM,KAAK,MAAM,UAAU,EAAM,CACnB,KAAK,QAAQ,GAI/C,SAAS,EACP,EACA,EACkB,CAClB,IAAM,EAAY,EAAQ,0BAA4B,EAChD,EAAa,EAAQ,YAAc,GAEnCC,EAA0B,EAAE,CAC5BC,EAAiC,EAAE,CAEzC,IAAK,GAAM,CAAC,EAAO,KAAU,OAAO,QAAQ,EAAQ,YAAY,CAC1D,GAAS,GACX,EAAc,KAAK,EAAM,CAEvB,GAAS,EAAY,GACvB,EAAqB,KAAK,EAAM,CAIpC,IAAM,EAAsB,OAAO,QACjC,EAAQ,mBACT,CAAC,SAAS,CAAC,EAAU,KAAW,CAC/B,IAAM,EAAQ,OAAO,OAAO,EAAM,CAAC,QAAQ,EAAK,IAAU,EAAM,EAAO,EAAE,CAIzE,MAHI,CAAC,GAAS,EAAQ,EACb,EAAE,CAEJ,OAAO,QAAQ,EAAM,CACzB,QAAQ,EAAG,KAAW,EAAQ,EAAQ,GAAI,CAC1C,KAAK,CAAC,EAAM,MAAY,CACvB,WACA,OACA,SAAU,EAAI,EAAQ,EACvB,EAAE,EACL,CAEI,EAAmB,EAAa,EAAQ,CAE9C,MAAO,CACL,aAAc,EACd,sBAAuB,EAAc,MAAM,EAAG,EAAE,CAChD,qBAAsB,EAAqB,MAAM,EAAG,GAAG,CACvD,sBACA,mBACD,CAGH,SAAS,EACP,EACsC,CACtC,IAAM,EAAa,OAAO,KAAK,EAAQ,YAAY,CAAC,OAC/C,KAUL,OANI,GAAc,GACT,QAEL,GAAc,EACT,OAEF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorSummary, FeatureUsageEvent, FieldAccessEvent, WorkflowStepEvent } from "./types.js";
+import { BehaviorStore, InMemoryBehaviorStore } from "./store.js";
+import { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker } from "./tracker.js";
+import { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions } from "./analyzer.js";
+import { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations } from "./adapter.js";
+export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions, BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorStore, BehaviorSummary, BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, FeatureUsageEvent, FieldAccessEvent, InMemoryBehaviorStore, OverlaySuggestionOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, WorkflowAdaptation, WorkflowStepEvent, createBehaviorTracker, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };

package/dist/index.js

@@ -0,0 +1 @@
+import{InMemoryBehaviorStore as e}from"./store.js";import{BehaviorTracker as t,createBehaviorTracker as n}from"./tracker.js";import{BehaviorAnalyzer as r}from"./analyzer.js";import{insightsToOverlaySuggestion as i,insightsToWorkflowAdaptations as a}from"./adapter.js";export{r as BehaviorAnalyzer,t as BehaviorTracker,e as InMemoryBehaviorStore,n as createBehaviorTracker,i as insightsToOverlaySuggestion,a as insightsToWorkflowAdaptations};

package/dist/store.d.ts

@@ -0,0 +1,21 @@
+import { BehaviorEvent, BehaviorQuery, BehaviorSummary } from "./types.js";
+
+//#region src/store.d.ts
+interface BehaviorStore {
+  record(event: BehaviorEvent): Promise<void> | void;
+  bulkRecord(events: BehaviorEvent[]): Promise<void> | void;
+  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
+  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
+  clear?(): Promise<void> | void;
+}
+declare class InMemoryBehaviorStore implements BehaviorStore {
+  private events;
+  record(event: BehaviorEvent): Promise<void>;
+  bulkRecord(events: BehaviorEvent[]): Promise<void>;
+  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
+  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
+  clear(): Promise<void>;
+}
+//#endregion
+export { BehaviorStore, InMemoryBehaviorStore };
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","names":[],"sources":["../src/store.ts"],"sourcesContent":[],"mappings":";;;UAEiB,aAAA;gBACD,gBAAgB;EADf,UAAA,CAAA,MAAa,EAET,aAFS,EAAA,CAAA,EAES,OAFT,CAAA,IAAA,CAAA,GAAA,IAAA;EACd,KAAA,CAAA,KAAA,EAED,aAFC,CAAA,EAEe,OAFf,CAEuB,aAFvB,EAAA,CAAA;EAAgB,SAAA,CAAA,KAAA,EAGb,aAHa,CAAA,EAGG,OAHH,CAGW,eAHX,CAAA;EACX,KAAA,GAAA,EAGT,OAHS,CAAA,IAAA,CAAA,GAAA,IAAA;;AACN,cAKF,qBAAA,YAAiC,aAL/B,CAAA;EAAwB,QAAA,MAAA;EAAR,MAAA,CAAA,KAAA,EAQT,aARS,CAAA,EAQO,OARP,CAAA,IAAA,CAAA;EACZ,UAAA,CAAA,MAAA,EAWQ,aAXR,EAAA,CAAA,EAW0B,OAX1B,CAAA,IAAA,CAAA;EAAwB,KAAA,CAAA,KAAA,EAetB,aAfsB,CAAA,EAeN,OAfM,CAeE,aAfF,EAAA,CAAA;EAAR,SAAA,CAAA,KAAA,EAmBV,aAnBU,CAAA,EAmBM,OAnBN,CAmBc,eAnBd,CAAA;EACvB,KAAA,CAAA,CAAA,EAkDK,OAlDL,CAAA,IAAA,CAAA"}

package/dist/store.js

@@ -0,0 +1,2 @@
+var e=class{events=[];async record(e){this.events.push(e)}async bulkRecord(e){this.events.push(...e)}async query(e){return t(this.events,e)}async summarize(e){let t=await this.query(e),n={fieldCounts:{},featureCounts:{},workflowStepCounts:{},totalEvents:t.length};return t.forEach(e=>{switch(e.type){case`field_access`:n.fieldCounts[e.field]=(n.fieldCounts[e.field]??0)+1;break;case`feature_usage`:n.featureCounts[e.feature]=(n.featureCounts[e.feature]??0)+1;break;case`workflow_step`:{let t=n.workflowStepCounts[e.workflow]??={};t[e.step]=(t[e.step]??0)+1;break}default:break}}),n}async clear(){this.events=[]}};function t(e,t){return e.filter(e=>!(t.tenantId&&e.tenantId!==t.tenantId||t.userId&&e.userId!==t.userId||t.role&&e.role!==t.role||t.since&&e.timestamp<t.since||t.until&&e.timestamp>t.until||t.operation&&e.type===`field_access`&&e.operation!==t.operation||t.feature&&e.type===`feature_usage`&&e.feature!==t.feature||t.workflow&&e.type===`workflow_step`&&e.workflow!==t.workflow))}export{e as InMemoryBehaviorStore};
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":["summary: BehaviorSummary"],"sources":["../src/store.ts"],"sourcesContent":["import type { BehaviorEvent, BehaviorQuery, BehaviorSummary } from './types';\n\nexport interface BehaviorStore {\n  record(event: BehaviorEvent): Promise<void> | void;\n  bulkRecord(events: BehaviorEvent[]): Promise<void> | void;\n  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;\n  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;\n  clear?(): Promise<void> | void;\n}\n\nexport class InMemoryBehaviorStore implements BehaviorStore {\n  private events: BehaviorEvent[] = [];\n\n  async record(event: BehaviorEvent): Promise<void> {\n    this.events.push(event);\n  }\n\n  async bulkRecord(events: BehaviorEvent[]): Promise<void> {\n    this.events.push(...events);\n  }\n\n  async query(query: BehaviorQuery): Promise<BehaviorEvent[]> {\n    return filterEvents(this.events, query);\n  }\n\n  async summarize(query: BehaviorQuery): Promise<BehaviorSummary> {\n    const events = await this.query(query);\n    const summary: BehaviorSummary = {\n      fieldCounts: {},\n      featureCounts: {},\n      workflowStepCounts: {},\n      totalEvents: events.length,\n    };\n\n    events.forEach((event) => {\n      switch (event.type) {\n        case 'field_access':\n          summary.fieldCounts[event.field] =\n            (summary.fieldCounts[event.field] ?? 0) + 1;\n          break;\n        case 'feature_usage':\n          summary.featureCounts[event.feature] =\n            (summary.featureCounts[event.feature] ?? 0) + 1;\n          break;\n        case 'workflow_step': {\n          const workflow = (summary.workflowStepCounts[event.workflow] ??= {});\n          workflow[event.step] = (workflow[event.step] ?? 0) + 1;\n          break;\n        }\n        default:\n          break;\n      }\n    });\n\n    return summary;\n  }\n\n  async clear(): Promise<void> {\n    this.events = [];\n  }\n}\n\nfunction filterEvents(\n  events: BehaviorEvent[],\n  query: BehaviorQuery\n): BehaviorEvent[] {\n  return events.filter((event) => {\n    if (query.tenantId && event.tenantId !== query.tenantId) {\n      return false;\n    }\n    if (query.userId && event.userId !== query.userId) {\n      return false;\n    }\n    if (query.role && event.role !== query.role) {\n      return false;\n    }\n    if (query.since && event.timestamp < query.since) {\n      return false;\n    }\n    if (query.until && event.timestamp > query.until) {\n      return false;\n    }\n\n    if (\n      query.operation &&\n      event.type === 'field_access' &&\n      event.operation !== query.operation\n    ) {\n      return false;\n    }\n    if (\n      query.feature &&\n      event.type === 'feature_usage' &&\n      event.feature !== query.feature\n    ) {\n      return false;\n    }\n    if (\n      query.workflow &&\n      event.type === 'workflow_step' &&\n      event.workflow !== query.workflow\n    ) {\n      return false;\n    }\n    return true;\n  });\n}\n"],"mappings":"AAUA,IAAa,EAAb,KAA4D,CAC1D,OAAkC,EAAE,CAEpC,MAAM,OAAO,EAAqC,CAChD,KAAK,OAAO,KAAK,EAAM,CAGzB,MAAM,WAAW,EAAwC,CACvD,KAAK,OAAO,KAAK,GAAG,EAAO,CAG7B,MAAM,MAAM,EAAgD,CAC1D,OAAO,EAAa,KAAK,OAAQ,EAAM,CAGzC,MAAM,UAAU,EAAgD,CAC9D,IAAM,EAAS,MAAM,KAAK,MAAM,EAAM,CAChCA,EAA2B,CAC/B,YAAa,EAAE,CACf,cAAe,EAAE,CACjB,mBAAoB,EAAE,CACtB,YAAa,EAAO,OACrB,CAsBD,OApBA,EAAO,QAAS,GAAU,CACxB,OAAQ,EAAM,KAAd,CACE,IAAK,eACH,EAAQ,YAAY,EAAM,QACvB,EAAQ,YAAY,EAAM,QAAU,GAAK,EAC5C,MACF,IAAK,gBACH,EAAQ,cAAc,EAAM,UACzB,EAAQ,cAAc,EAAM,UAAY,GAAK,EAChD,MACF,IAAK,gBAAiB,CACpB,IAAM,EAAY,EAAQ,mBAAmB,EAAM,YAAc,EAAE,CACnE,EAAS,EAAM,OAAS,EAAS,EAAM,OAAS,GAAK,EACrD,MAEF,QACE,QAEJ,CAEK,EAGT,MAAM,OAAuB,CAC3B,KAAK,OAAS,EAAE,GAIpB,SAAS,EACP,EACA,EACiB,CACjB,OAAO,EAAO,OAAQ,GA+BpB,EA9BI,EAAM,UAAY,EAAM,WAAa,EAAM,UAG3C,EAAM,QAAU,EAAM,SAAW,EAAM,QAGvC,EAAM,MAAQ,EAAM,OAAS,EAAM,MAGnC,EAAM,OAAS,EAAM,UAAY,EAAM,OAGvC,EAAM,OAAS,EAAM,UAAY,EAAM,OAKzC,EAAM,WACN,EAAM,OAAS,gBACf,EAAM,YAAc,EAAM,WAK1B,EAAM,SACN,EAAM,OAAS,iBACf,EAAM,UAAY,EAAM,SAKxB,EAAM,UACN,EAAM,OAAS,iBACf,EAAM,WAAa,EAAM,UAK3B"}

package/dist/tracker.d.ts

@@ -0,0 +1,53 @@
+import { BehaviorStore } from "./store.js";
+
+//#region src/tracker.d.ts
+interface BehaviorTrackerContext {
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  device?: string;
+  metadata?: Record<string, unknown>;
+}
+interface BehaviorTrackerOptions {
+  store: BehaviorStore;
+  context: BehaviorTrackerContext;
+  tracerName?: string;
+  autoFlushIntervalMs?: number;
+  bufferSize?: number;
+}
+interface TrackFieldAccessInput {
+  operation: string;
+  field: string;
+  metadata?: Record<string, unknown>;
+}
+interface TrackFeatureUsageInput {
+  feature: string;
+  action: 'opened' | 'completed' | 'dismissed';
+  metadata?: Record<string, unknown>;
+}
+interface TrackWorkflowStepInput {
+  workflow: string;
+  step: string;
+  status: 'entered' | 'completed' | 'skipped' | 'errored';
+  metadata?: Record<string, unknown>;
+}
+declare class BehaviorTracker {
+  private readonly store;
+  private readonly context;
+  private readonly tracer;
+  private readonly counter;
+  private buffer;
+  private readonly bufferSize;
+  private flushTimer?;
+  constructor(options: BehaviorTrackerOptions);
+  trackFieldAccess(input: TrackFieldAccessInput): void;
+  trackFeatureUsage(input: TrackFeatureUsageInput): void;
+  trackWorkflowStep(input: TrackWorkflowStepInput): void;
+  flush(): Promise<void>;
+  dispose(): Promise<void>;
+  private enqueue;
+}
+declare const createBehaviorTracker: (options: BehaviorTrackerOptions) => BehaviorTracker;
+//#endregion
+export { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker };
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","names":[],"sources":["../src/tracker.ts"],"sourcesContent":[],"mappings":";;;UAIiB,sBAAA;;EAAA,MAAA,CAAA,EAAA,MAAA;EAQA,IAAA,CAAA,EAAA,MAAA;EAUA,MAAA,CAAA,EAAA,MAAA;EAMA,QAAA,CAAA,EAnBJ,MAmBI,CAAA,MAAA,EAAsB,OAAA,CAAA;AAMvC;AAOa,UA7BI,sBAAA,CA6BW;EAcL,KAAA,EA1Cd,aA0Cc;EAYG,OAAA,EArDf,sBAqDe;EAYC,UAAA,CAAA,EAAA,MAAA;EAYA,mBAAA,CAAA,EAAA,MAAA;EAaV,UAAA,CAAA,EAAA,MAAA;;AAOS,UAzFT,qBAAA,CAyFS;EA4Bb,SAAA,EAAA,MAAA;;aAlHA;;UAGI,sBAAA;;;aAGJ;;UAGI,sBAAA;;;;aAIJ;;cAGA,eAAA;;;;;;;;uBAcU;0BAYG;2BAYC;2BAYA;WAaV;aAOE;;;cA4BN,iCAAkC,2BAAsB"}

package/dist/tracker.js

@@ -0,0 +1,2 @@
+import{metrics as e,trace as t}from"@opentelemetry/api";var n=class{store;context;tracer=t.getTracer(`lssm.personalization`,`1.0.0`);counter=e.getMeter(`lssm.personalization`,`1.0.0`).createCounter(`lssm.personalization.events`,{description:`Behavior events tracked for personalization`});buffer=[];bufferSize;flushTimer;constructor(e){this.store=e.store,this.context=e.context,this.bufferSize=e.bufferSize??25,e.autoFlushIntervalMs&&(this.flushTimer=setInterval(()=>{this.flush()},e.autoFlushIntervalMs))}trackFieldAccess(e){let t={type:`field_access`,operation:e.operation,field:e.field,timestamp:Date.now(),...this.context,metadata:{...this.context.metadata,...e.metadata}};this.enqueue(t)}trackFeatureUsage(e){let t={type:`feature_usage`,feature:e.feature,action:e.action,timestamp:Date.now(),...this.context,metadata:{...this.context.metadata,...e.metadata}};this.enqueue(t)}trackWorkflowStep(e){let t={type:`workflow_step`,workflow:e.workflow,step:e.step,status:e.status,timestamp:Date.now(),...this.context,metadata:{...this.context.metadata,...e.metadata}};this.enqueue(t)}async flush(){if(!this.buffer.length)return;let e=this.buffer;this.buffer=[],await this.store.bulkRecord(e)}async dispose(){this.flushTimer&&clearInterval(this.flushTimer),await this.flush()}enqueue(e){this.buffer.push(e),this.counter.add(1,{tenantId:this.context.tenantId,type:e.type}),this.tracer.startActiveSpan(`personalization.${e.type}`,t=>{t.setAttribute(`tenant.id`,this.context.tenantId),this.context.userId&&t.setAttribute(`user.id`,this.context.userId),t.setAttribute(`personalization.event_type`,e.type),t.end()}),this.buffer.length>=this.bufferSize&&this.flush()}};const r=e=>new n(e);export{n as BehaviorTracker,r as createBehaviorTracker};
+//# sourceMappingURL=tracker.js.map

package/dist/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","names":[],"sources":["../src/tracker.ts"],"sourcesContent":["import { trace, metrics } from '@opentelemetry/api';\nimport type { BehaviorEvent } from './types';\nimport type { BehaviorStore } from './store';\n\nexport interface BehaviorTrackerContext {\n  tenantId: string;\n  userId?: string;\n  role?: string;\n  device?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface BehaviorTrackerOptions {\n  store: BehaviorStore;\n  context: BehaviorTrackerContext;\n  tracerName?: string;\n  autoFlushIntervalMs?: number;\n  bufferSize?: number;\n}\n\nconst DEFAULT_BUFFER_SIZE = 25;\n\nexport interface TrackFieldAccessInput {\n  operation: string;\n  field: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface TrackFeatureUsageInput {\n  feature: string;\n  action: 'opened' | 'completed' | 'dismissed';\n  metadata?: Record<string, unknown>;\n}\n\nexport interface TrackWorkflowStepInput {\n  workflow: string;\n  step: string;\n  status: 'entered' | 'completed' | 'skipped' | 'errored';\n  metadata?: Record<string, unknown>;\n}\n\nexport class BehaviorTracker {\n  private readonly store: BehaviorStore;\n  private readonly context: BehaviorTrackerContext;\n  private readonly tracer = trace.getTracer('lssm.personalization', '1.0.0');\n  private readonly counter = metrics\n    .getMeter('lssm.personalization', '1.0.0')\n    .createCounter('lssm.personalization.events', {\n      description: 'Behavior events tracked for personalization',\n    });\n\n  private buffer: BehaviorEvent[] = [];\n  private readonly bufferSize: number;\n  private flushTimer?: ReturnType<typeof setInterval>;\n\n  constructor(options: BehaviorTrackerOptions) {\n    this.store = options.store;\n    this.context = options.context;\n    this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;\n\n    if (options.autoFlushIntervalMs) {\n      this.flushTimer = setInterval(() => {\n        void this.flush();\n      }, options.autoFlushIntervalMs);\n    }\n  }\n\n  trackFieldAccess(input: TrackFieldAccessInput) {\n    const event = {\n      type: 'field_access',\n      operation: input.operation,\n      field: input.field,\n      timestamp: Date.now(),\n      ...this.context,\n      metadata: { ...this.context.metadata, ...input.metadata },\n    } as BehaviorEvent;\n    this.enqueue(event);\n  }\n\n  trackFeatureUsage(input: TrackFeatureUsageInput) {\n    const event = {\n      type: 'feature_usage',\n      feature: input.feature,\n      action: input.action,\n      timestamp: Date.now(),\n      ...this.context,\n      metadata: { ...this.context.metadata, ...input.metadata },\n    } as BehaviorEvent;\n    this.enqueue(event);\n  }\n\n  trackWorkflowStep(input: TrackWorkflowStepInput) {\n    const event = {\n      type: 'workflow_step',\n      workflow: input.workflow,\n      step: input.step,\n      status: input.status,\n      timestamp: Date.now(),\n      ...this.context,\n      metadata: { ...this.context.metadata, ...input.metadata },\n    } as BehaviorEvent;\n    this.enqueue(event);\n  }\n\n  async flush(): Promise<void> {\n    if (!this.buffer.length) return;\n    const events = this.buffer;\n    this.buffer = [];\n    await this.store.bulkRecord(events);\n  }\n\n  async dispose(): Promise<void> {\n    if (this.flushTimer) {\n      clearInterval(this.flushTimer);\n    }\n    await this.flush();\n  }\n\n  private enqueue(event: BehaviorEvent) {\n    this.buffer.push(event);\n    this.counter.add(1, {\n      tenantId: this.context.tenantId,\n      type: event.type,\n    });\n\n    this.tracer.startActiveSpan(`personalization.${event.type}`, (span) => {\n      span.setAttribute('tenant.id', this.context.tenantId);\n      if (this.context.userId)\n        span.setAttribute('user.id', this.context.userId);\n      span.setAttribute('personalization.event_type', event.type);\n      span.end();\n    });\n\n    if (this.buffer.length >= this.bufferSize) {\n      void this.flush();\n    }\n  }\n}\n\nexport const createBehaviorTracker = (options: BehaviorTrackerOptions) =>\n  new BehaviorTracker(options);\n"],"mappings":"wDAyCA,IAAa,EAAb,KAA6B,CAC3B,MACA,QACA,OAA0B,EAAM,UAAU,uBAAwB,QAAQ,CAC1E,QAA2B,EACxB,SAAS,uBAAwB,QAAQ,CACzC,cAAc,8BAA+B,CAC5C,YAAa,8CACd,CAAC,CAEJ,OAAkC,EAAE,CACpC,WACA,WAEA,YAAY,EAAiC,CAC3C,KAAK,MAAQ,EAAQ,MACrB,KAAK,QAAU,EAAQ,QACvB,KAAK,WAAa,EAAQ,YAAc,GAEpC,EAAQ,sBACV,KAAK,WAAa,gBAAkB,CAC7B,KAAK,OAAO,EAChB,EAAQ,oBAAoB,EAInC,iBAAiB,EAA8B,CAC7C,IAAM,EAAQ,CACZ,KAAM,eACN,UAAW,EAAM,UACjB,MAAO,EAAM,MACb,UAAW,KAAK,KAAK,CACrB,GAAG,KAAK,QACR,SAAU,CAAE,GAAG,KAAK,QAAQ,SAAU,GAAG,EAAM,SAAU,CAC1D,CACD,KAAK,QAAQ,EAAM,CAGrB,kBAAkB,EAA+B,CAC/C,IAAM,EAAQ,CACZ,KAAM,gBACN,QAAS,EAAM,QACf,OAAQ,EAAM,OACd,UAAW,KAAK,KAAK,CACrB,GAAG,KAAK,QACR,SAAU,CAAE,GAAG,KAAK,QAAQ,SAAU,GAAG,EAAM,SAAU,CAC1D,CACD,KAAK,QAAQ,EAAM,CAGrB,kBAAkB,EAA+B,CAC/C,IAAM,EAAQ,CACZ,KAAM,gBACN,SAAU,EAAM,SAChB,KAAM,EAAM,KACZ,OAAQ,EAAM,OACd,UAAW,KAAK,KAAK,CACrB,GAAG,KAAK,QACR,SAAU,CAAE,GAAG,KAAK,QAAQ,SAAU,GAAG,EAAM,SAAU,CAC1D,CACD,KAAK,QAAQ,EAAM,CAGrB,MAAM,OAAuB,CAC3B,GAAI,CAAC,KAAK,OAAO,OAAQ,OACzB,IAAM,EAAS,KAAK,OACpB,KAAK,OAAS,EAAE,CAChB,MAAM,KAAK,MAAM,WAAW,EAAO,CAGrC,MAAM,SAAyB,CACzB,KAAK,YACP,cAAc,KAAK,WAAW,CAEhC,MAAM,KAAK,OAAO,CAGpB,QAAgB,EAAsB,CACpC,KAAK,OAAO,KAAK,EAAM,CACvB,KAAK,QAAQ,IAAI,EAAG,CAClB,SAAU,KAAK,QAAQ,SACvB,KAAM,EAAM,KACb,CAAC,CAEF,KAAK,OAAO,gBAAgB,mBAAmB,EAAM,OAAS,GAAS,CACrE,EAAK,aAAa,YAAa,KAAK,QAAQ,SAAS,CACjD,KAAK,QAAQ,QACf,EAAK,aAAa,UAAW,KAAK,QAAQ,OAAO,CACnD,EAAK,aAAa,6BAA8B,EAAM,KAAK,CAC3D,EAAK,KAAK,EACV,CAEE,KAAK,OAAO,QAAU,KAAK,YACxB,KAAK,OAAO,GAKvB,MAAa,EAAyB,GACpC,IAAI,EAAgB,EAAQ"}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+//#region src/types.d.ts
+type BehaviorEventType = 'field_access' | 'feature_usage' | 'workflow_step';
+interface BehaviorEventBase {
+  id?: string;
+  tenantId: string;
+  userId?: string;
+  role?: string;
+  device?: string;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+interface FieldAccessEvent extends BehaviorEventBase {
+  type: 'field_access';
+  operation: string;
+  field: string;
+}
+interface FeatureUsageEvent extends BehaviorEventBase {
+  type: 'feature_usage';
+  feature: string;
+  action: 'opened' | 'completed' | 'dismissed';
+}
+interface WorkflowStepEvent extends BehaviorEventBase {
+  type: 'workflow_step';
+  workflow: string;
+  step: string;
+  status: 'entered' | 'completed' | 'skipped' | 'errored';
+}
+type BehaviorEvent = FieldAccessEvent | FeatureUsageEvent | WorkflowStepEvent;
+interface BehaviorQuery {
+  tenantId?: string;
+  userId?: string;
+  role?: string;
+  feature?: string;
+  operation?: string;
+  workflow?: string;
+  since?: number;
+  until?: number;
+  limit?: number;
+}
+interface BehaviorSummary {
+  fieldCounts: Record<string, number>;
+  featureCounts: Record<string, number>;
+  workflowStepCounts: Record<string, Record<string, number>>;
+  totalEvents: number;
+}
+interface BehaviorInsights {
+  unusedFields: string[];
+  frequentlyUsedFields: string[];
+  suggestedHiddenFields: string[];
+  workflowBottlenecks: {
+    workflow: string;
+    step: string;
+    dropRate: number;
+  }[];
+  layoutPreference?: 'form' | 'grid' | 'list' | 'table';
+}
+//#endregion
+export { BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorSummary, FeatureUsageEvent, FieldAccessEvent, WorkflowStepEvent };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";KAAY,iBAAA;AAAA,UAKK,iBAAA,CALY;EAKZ,EAAA,CAAA,EAAA,MAAA;EAUA,QAAA,EAAA,MAAA;EAMA,MAAA,CAAA,EAAA,MAAA;EAMA,IAAA,CAAA,EAAA,MAAA;EAOL,MAAA,CAAA,EAAA,MAAA;EACR,SAAA,EAAA,MAAA;EACA,QAAA,CAAA,EAxBS,MAwBT,CAAA,MAAA,EAAA,OAAA,CAAA;;AACiB,UAtBJ,gBAAA,SAAyB,iBAsBrB,CAAA;EAEJ,IAAA,EAAA,cAAa;EAYb,SAAA,EAAA,MAAA;EACF,KAAA,EAAA,MAAA;;AAEsB,UAjCpB,iBAAA,SAA0B,iBAiCN,CAAA;EAAf,IAAA,EAAA,eAAA;EAAM,OAAA,EAAA,MAAA;EAIX,MAAA,EAAA,QAAA,GAAgB,WAAA,GAAA,WAAA;;UA/BhB,iBAAA,SAA0B;;;;;;KAO/B,aAAA,GACR,mBACA,oBACA;UAEa,aAAA;;;;;;;;;;;UAYA,eAAA;eACF;iBACE;sBACK,eAAe;;;UAIpB,gBAAA"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@lssm/lib.personalization",
+  "version": "0.1.0",
+  "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@lssm/lib.bus": "workspace:*",
+    "@lssm/lib.overlay-engine": "workspace:*",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.16.6",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.0"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  }
+}