@contractspec/lib.personalization 1.57.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.personalization",
-  "version": "1.57.0",
+  "version": "1.58.0",
   "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
   "keywords": [
     "contractspec",
@@ -19,60 +19,127 @@
   "scripts": {
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
     "publish:pkg:canary": "bun publish:pkg --tag canary",
-    "build": "bun build:types && bun build:bundle",
-    "build:bundle": "tsdown",
-    "build:types": "tsc --noEmit",
-    "dev": "bun build:bundle --watch",
+    "build": "bun run prebuild && bun run build:bundle && bun run build:types",
+    "build:bundle": "contractspec-bun-build transpile",
+    "build:types": "contractspec-bun-build types",
+    "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
     "lint:fix": "eslint src --fix",
     "lint:check": "eslint src",
-    "test": "bun test"
+    "test": "bun test",
+    "prebuild": "contractspec-bun-build prebuild",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.bus": "1.57.0",
-    "@contractspec/lib.schema": "1.57.0",
-    "@contractspec/lib.contracts": "1.57.0",
-    "@contractspec/lib.knowledge": "1.57.0",
-    "@contractspec/lib.overlay-engine": "1.57.0",
+    "@contractspec/lib.bus": "1.58.0",
+    "@contractspec/lib.schema": "1.58.0",
+    "@contractspec/lib.contracts": "1.58.0",
+    "@contractspec/lib.knowledge": "1.58.0",
+    "@contractspec/lib.overlay-engine": "1.58.0",
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.57.0",
-    "@contractspec/tool.typescript": "1.57.0",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3"
+    "@contractspec/tool.typescript": "1.58.0",
+    "typescript": "^5.9.3",
+    "@contractspec/tool.bun": "1.57.0"
   },
   "exports": {
-    ".": "./dist/index.js",
-    "./adapter": "./dist/adapter.js",
-    "./analyzer": "./dist/analyzer.js",
-    "./docs": "./dist/docs/index.js",
-    "./docs/behavior-tracking.docblock": "./dist/docs/behavior-tracking.docblock.js",
-    "./docs/overlay-engine.docblock": "./dist/docs/overlay-engine.docblock.js",
-    "./docs/workflow-composition.docblock": "./dist/docs/workflow-composition.docblock.js",
-    "./store": "./dist/store.js",
-    "./tracker": "./dist/tracker.js",
-    "./types": "./dist/types.js",
-    "./*": "./*"
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
+    "./analyzer": "./src/analyzer.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/behavior-tracking.docblock": "./src/docs/behavior-tracking.docblock.ts",
+    "./docs/index": "./src/docs/index.ts",
+    "./docs/overlay-engine.docblock": "./src/docs/overlay-engine.docblock.ts",
+    "./docs/workflow-composition.docblock": "./src/docs/workflow-composition.docblock.ts",
+    "./store": "./src/store.ts",
+    "./tracker": "./src/tracker.ts",
+    "./types": "./src/types.ts"
   },
   "publishConfig": {
     "access": "public",
     "exports": {
-      ".": "./dist/index.js",
-      "./adapter": "./dist/adapter.js",
-      "./analyzer": "./dist/analyzer.js",
-      "./docs": "./dist/docs/index.js",
-      "./docs/behavior-tracking.docblock": "./dist/docs/behavior-tracking.docblock.js",
-      "./docs/overlay-engine.docblock": "./dist/docs/overlay-engine.docblock.js",
-      "./docs/workflow-composition.docblock": "./dist/docs/workflow-composition.docblock.js",
-      "./store": "./dist/store.js",
-      "./tracker": "./dist/tracker.js",
-      "./types": "./dist/types.js",
-      "./*": "./*"
+      ".": {
+        "types": "./dist/index.d.ts",
+        "bun": "./dist/index.js",
+        "node": "./dist/node/index.mjs",
+        "browser": "./dist/browser/index.js",
+        "default": "./dist/index.js"
+      },
+      "./adapter": {
+        "types": "./dist/adapter.d.ts",
+        "bun": "./dist/adapter.js",
+        "node": "./dist/node/adapter.mjs",
+        "browser": "./dist/browser/adapter.js",
+        "default": "./dist/adapter.js"
+      },
+      "./analyzer": {
+        "types": "./dist/analyzer.d.ts",
+        "bun": "./dist/analyzer.js",
+        "node": "./dist/node/analyzer.mjs",
+        "browser": "./dist/browser/analyzer.js",
+        "default": "./dist/analyzer.js"
+      },
+      "./docs": {
+        "types": "./dist/docs/index.d.ts",
+        "bun": "./dist/docs/index.js",
+        "node": "./dist/node/docs/index.mjs",
+        "browser": "./dist/browser/docs/index.js",
+        "default": "./dist/docs/index.js"
+      },
+      "./docs/behavior-tracking.docblock": {
+        "types": "./dist/docs/behavior-tracking.docblock.d.ts",
+        "bun": "./dist/docs/behavior-tracking.docblock.js",
+        "node": "./dist/node/docs/behavior-tracking.docblock.mjs",
+        "browser": "./dist/browser/docs/behavior-tracking.docblock.js",
+        "default": "./dist/docs/behavior-tracking.docblock.js"
+      },
+      "./docs/index": {
+        "types": "./dist/docs/index.d.ts",
+        "bun": "./dist/docs/index.js",
+        "node": "./dist/node/docs/index.mjs",
+        "browser": "./dist/browser/docs/index.js",
+        "default": "./dist/docs/index.js"
+      },
+      "./docs/overlay-engine.docblock": {
+        "types": "./dist/docs/overlay-engine.docblock.d.ts",
+        "bun": "./dist/docs/overlay-engine.docblock.js",
+        "node": "./dist/node/docs/overlay-engine.docblock.mjs",
+        "browser": "./dist/browser/docs/overlay-engine.docblock.js",
+        "default": "./dist/docs/overlay-engine.docblock.js"
+      },
+      "./docs/workflow-composition.docblock": {
+        "types": "./dist/docs/workflow-composition.docblock.d.ts",
+        "bun": "./dist/docs/workflow-composition.docblock.js",
+        "node": "./dist/node/docs/workflow-composition.docblock.mjs",
+        "browser": "./dist/browser/docs/workflow-composition.docblock.js",
+        "default": "./dist/docs/workflow-composition.docblock.js"
+      },
+      "./store": {
+        "types": "./dist/store.d.ts",
+        "bun": "./dist/store.js",
+        "node": "./dist/node/store.mjs",
+        "browser": "./dist/browser/store.js",
+        "default": "./dist/store.js"
+      },
+      "./tracker": {
+        "types": "./dist/tracker.d.ts",
+        "bun": "./dist/tracker.js",
+        "node": "./dist/node/tracker.mjs",
+        "browser": "./dist/browser/tracker.js",
+        "default": "./dist/tracker.js"
+      },
+      "./types": {
+        "types": "./dist/types.d.ts",
+        "bun": "./dist/types.js",
+        "node": "./dist/node/types.mjs",
+        "browser": "./dist/browser/types.js",
+        "default": "./dist/types.js"
+      }
     },
     "registry": "https://registry.npmjs.org/"
   },

package/dist/adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.js","names":[],"sources":["../src/adapter.ts"],"sourcesContent":["import type {\n  OverlayModification,\n  OverlaySpec,\n} from '@contractspec/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,4BACd,UACA,SACoB;CACpB,MAAM,gBAAuC,EAAE;AAE/C,UAAS,sBAAsB,SAAS,UAAU;AAChD,gBAAc,KAAK;GACjB,MAAM;GACN;GACA,QAAQ;GACT,CAAC;GACF;AAEF,KAAI,SAAS,qBAAqB,OAChC,eAAc,KAAK;EACjB,MAAM;EACN,QAAQ,SAAS;EAClB,CAAC;AAGJ,KAAI,CAAC,cAAc,OACjB,QAAO;AAGT,QAAO;EACL,WAAW,QAAQ;EACnB,SAAS,QAAQ,WAAW;EAC5B,WAAW;GACT,UAAU,QAAQ;GAClB,YAAY,QAAQ;GACpB,QAAQ,QAAQ;GAChB,MAAM,QAAQ;GACf;EACD;EACA,UAAU;GACR,8BAAa,IAAI,MAAM,EAAC,aAAa;GACrC,WAAW;GACZ;EACF;;AAGH,SAAgB,8BACd,UACsB;AACtB,QAAO,SAAS,oBAAoB,KAAK,gBAAgB;EACvD,UAAU,WAAW;EACrB,MAAM,WAAW;EACjB,MAAM,mBAAmB,KAAK,MAAM,WAAW,WAAW,IAAI,CAAC;EAChE,EAAE"}

package/dist/analyzer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyzer.js","names":[],"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":";AAeA,MAAM,oBAAoB;AAE1B,IAAa,mBAAb,MAA8B;CAC5B,YACE,AAAiB,OACjB,AAAiB,UAAmC,EAAE,EACtD;EAFiB;EACA;;CAGnB,MAAM,QAAQ,QAAkD;EAC9D,MAAM,QAAuB;GAC3B,UAAU,OAAO;GACjB,QAAQ,OAAO;GACf,MAAM,OAAO;GACd;AAED,MAAI,OAAO,SACT,OAAM,QAAQ,KAAK,KAAK,GAAG,OAAO;AAIpC,SAAO,cADS,MAAM,KAAK,MAAM,UAAU,MAAM,EACnB,KAAK,QAAQ;;;AAI/C,SAAS,cACP,SACA,SACkB;CAClB,MAAM,YAAY,QAAQ,4BAA4B;CACtD,MAAM,aAAa,QAAQ,cAAc;CAEzC,MAAM,gBAA0B,EAAE;CAClC,MAAM,uBAAiC,EAAE;AAEzC,MAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,QAAQ,YAAY,EAAE;AAChE,MAAI,SAAS,UACX,eAAc,KAAK,MAAM;AAE3B,MAAI,SAAS,YAAY,EACvB,sBAAqB,KAAK,MAAM;;CAIpC,MAAM,sBAAsB,OAAO,QACjC,QAAQ,mBACT,CAAC,SAAS,CAAC,UAAU,WAAW;EAC/B,MAAM,QAAQ,OAAO,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,MAAM,OAAO,EAAE;AACzE,MAAI,CAAC,SAAS,QAAQ,WACpB,QAAO,EAAE;AAEX,SAAO,OAAO,QAAQ,MAAM,CACzB,QAAQ,GAAG,WAAW,QAAQ,QAAQ,GAAI,CAC1C,KAAK,CAAC,MAAM,YAAY;GACvB;GACA;GACA,UAAU,IAAI,QAAQ;GACvB,EAAE;GACL;CAEF,MAAM,mBAAmB,aAAa,QAAQ;AAE9C,QAAO;EACL,cAAc;EACd,uBAAuB,cAAc,MAAM,GAAG,EAAE;EAChD,sBAAsB,qBAAqB,MAAM,GAAG,GAAG;EACvD;EACA;EACD;;AAGH,SAAS,aACP,SACsC;CACtC,MAAM,aAAa,OAAO,KAAK,QAAQ,YAAY,CAAC;AACpD,KAAI,CAAC,WACH;AAGF,KAAI,cAAc,GAChB,QAAO;AAET,KAAI,cAAc,EAChB,QAAO;AAET,QAAO"}

package/dist/docs/behavior-tracking.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"behavior-tracking.docblock.js","names":[],"sources":["../../src/docs/behavior-tracking.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@contractspec/lib.contracts/docs';\nimport { registerDocBlocks } from '@contractspec/lib.contracts/docs';\n\nexport const personalization_behavior_tracking_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.personalization.behavior-tracking',\n    title: 'Behavior Tracking',\n    summary:\n      '`@contractspec/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/personalization/behavior-tracking',\n    tags: ['personalization', 'behavior-tracking'],\n    body: \"# Behavior Tracking\\n\\n`@contractspec/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.\\n\\n## Tracker\\n\\n```ts\\nimport { createBehaviorTracker } from '@contractspec/lib.personalization';\\nimport { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';\\n\\nconst tracker = createBehaviorTracker({\\n  store: new InMemoryBehaviorStore(),\\n  context: { tenantId: ctx.tenant.id, userId: ctx.identity.userId },\\n  autoFlushIntervalMs: 5000,\\n});\\n\\ntracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'internalNotes' });\\ntracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });\\ntracker.trackWorkflowStep({ workflow: 'invoice-approval', step: 'review', status: 'entered' });\\n```\\n\\nAll events are buffered and flushed either when the buffer hits 25 entries or when `autoFlushIntervalMs` elapses. Tracked metrics flow to OpenTelemetry via the meter/counter built into the tracker.\\n\\n## Analyzer\\n\\n```ts\\nimport { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';\\n\\nconst analyzer = new BehaviorAnalyzer(store, { fieldInactivityThreshold: 2 });\\nconst insights = await analyzer.analyze({ tenantId: 'acme', userId: 'manager-42', windowMs: 7 * 24 * 60 * 60 * 1000 });\\n\\n/*\\n{\\n  unusedFields: ['internalNotes'],\\n  suggestedHiddenFields: ['internalNotes'],\\n  frequentlyUsedFields: ['customerReference', 'items'],\\n  workflowBottlenecks: [{ workflow: 'invoice-approval', step: 'finance-review', dropRate: 0.6 }],\\n  layoutPreference: 'table'\\n}\\n*/\\n```\\n\\nUse the analyzer output with the overlay adapter to generate suggestions automatically.\\n\\n## Adapter\\n\\n```ts\\nimport { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';\\n\\nconst overlay = insightsToOverlaySuggestion(insights, {\\n  overlayId: 'acme-order-form',\\n  tenantId: 'acme',\\n  capability: 'billing.createOrder',\\n});\\n```\\n\\nWhen the adapter returns an overlay spec, pass it to the overlay engine to register or sign it.\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\",\n  },\n];\nregisterDocBlocks(personalization_behavior_tracking_DocBlocks);\n"],"mappings":";;;AAGA,MAAa,8CAA0D,CACrE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,mBAAmB,oBAAoB;CAC9C,MAAM;CACP,CACF;AACD,kBAAkB,4CAA4C"}

package/dist/docs/overlay-engine.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"overlay-engine.docblock.js","names":[],"sources":["../../src/docs/overlay-engine.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@contractspec/lib.contracts/docs';\nimport { registerDocBlocks } from '@contractspec/lib.contracts/docs';\n\nexport const personalization_overlay_engine_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.personalization.overlay-engine',\n    title: 'Overlay Engine',\n    summary:\n      '`@contractspec/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/personalization/overlay-engine',\n    tags: ['personalization', 'overlay-engine'],\n    body: \"# Overlay Engine\\n\\n`@contractspec/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.\\n\\n## Key APIs\\n\\n- `defineOverlay(spec)` \\u2013 helper to keep specs typed.\\n- `OverlayRegistry` \\u2013 register signed overlays and retrieve them per context.\\n- `OverlayEngine` \\u2013 apply overlays to renderable targets, emit audit events, and merge modifications deterministically.\\n- `signOverlay(spec, privateKey)` \\u2013 Ed25519/RSA-PSS signer.\\n- `verifyOverlaySignature(overlay)` \\u2013 verify public key signatures.\\n- `useOverlay(engine, params)` \\u2013 client hook that returns `{ target, overlaysApplied }`.\\n\\n## Scope Precedence\\n\\nRegistrations are sorted by specificity:\\n\\n1. Tenant overlays\\n2. Role overlays\\n3. User overlays\\n4. Device overlays\\n\\nLess specific overlays run first; more specific overlays override later.\\n\\n## Example\\n\\n```ts\\nconst registry = new OverlayRegistry();\\nconst engine = new OverlayEngine({\\n  registry,\\n  audit: (event) => auditLogService.record(event),\\n});\\n\\nconst overlay = defineOverlay({\\n  overlayId: 'acme-order-form',\\n  version: '1.0.0',\\n  appliesTo: {\\n    capability: 'billing.createOrder',\\n    tenantId: 'acme',\\n  },\\n  modifications: [\\n    { type: 'hideField', field: 'internalNotes' },\\n    { type: 'renameLabel', field: 'customerReference', newLabel: 'PO Number' },\\n  ],\\n});\\n\\nconst signedOverlay = await signOverlay(overlay, privateKeyPem);\\nregistry.register(signedOverlay);\\n\\nconst result = engine.apply({\\n  target: { fields: baseFields },\\n  capability: 'billing.createOrder',\\n  tenantId: 'acme',\\n  userId: 'manager-7',\\n});\\n```\\n\\n`result.target.fields` now carries the hidden and renamed outputs ready for rendering.\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\",\n  },\n];\nregisterDocBlocks(personalization_overlay_engine_DocBlocks);\n"],"mappings":";;;AAGA,MAAa,2CAAuD,CAClE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,mBAAmB,iBAAiB;CAC3C,MAAM;CACP,CACF;AACD,kBAAkB,yCAAyC"}

package/dist/docs/workflow-composition.docblock.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"workflow-composition.docblock.js","names":[],"sources":["../../src/docs/workflow-composition.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@contractspec/lib.contracts/docs';\nimport { registerDocBlocks } from '@contractspec/lib.contracts/docs';\n\nexport const personalization_workflow_composition_DocBlocks: DocBlock[] = [\n  {\n    id: 'docs.personalization.workflow-composition',\n    title: 'Workflow Composition',\n    summary:\n      '`@contractspec/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/personalization/workflow-composition',\n    tags: ['personalization', 'workflow-composition'],\n    body: \"# Workflow Composition\\n\\n`@contractspec/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.\\n\\n## Extensions\\n\\n```ts\\nimport { WorkflowComposer } from '@contractspec/lib.workflow-composer';\\nimport { approvalStepTemplate } from '@contractspec/lib.workflow-composer/templates';\\n\\nconst composer = new WorkflowComposer();\\n\\ncomposer.register({\\n  workflow: 'billing.invoiceApproval',\\n  tenantId: 'acme',\\n  priority: 10,\\n  customSteps: [\\n    {\\n      after: 'validate-invoice',\\n      inject: approvalStepTemplate({\\n        id: 'acme-legal-review',\\n        label: 'Legal Review (ACME)',\\n        description: 'Tenant-specific compliance step.',\\n      }),\\n      transitionTo: 'final-approval',\\n    },\\n  ],\\n  hiddenSteps: ['internal-audit'],\\n});\\n```\\n\\n## Compose\\n\\n```ts\\nconst runtimeSpec = composer.compose({\\n  base: BaseInvoiceWorkflow,\\n  tenantId: 'acme',\\n});\\n\\nworkflowRunner.execute(runtimeSpec, ctx);\\n```\\n\\nThe composer uses anchor references (`after`/`before`) to place injected steps and cleans up transitions when steps are hidden.\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\\n\",\n  },\n];\nregisterDocBlocks(personalization_workflow_composition_DocBlocks);\n"],"mappings":";;;AAGA,MAAa,iDAA6D,CACxE;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM,CAAC,mBAAmB,uBAAuB;CACjD,MAAM;CACP,CACF;AACD,kBAAkB,+CAA+C"}

package/dist/store.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"store.js","names":[],"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,wBAAb,MAA4D;CAC1D,AAAQ,SAA0B,EAAE;CAEpC,MAAM,OAAO,OAAqC;AAChD,OAAK,OAAO,KAAK,MAAM;;CAGzB,MAAM,WAAW,QAAwC;AACvD,OAAK,OAAO,KAAK,GAAG,OAAO;;CAG7B,MAAM,MAAM,OAAgD;AAC1D,SAAO,aAAa,KAAK,QAAQ,MAAM;;CAGzC,MAAM,UAAU,OAAgD;EAC9D,MAAM,SAAS,MAAM,KAAK,MAAM,MAAM;EACtC,MAAM,UAA2B;GAC/B,aAAa,EAAE;GACf,eAAe,EAAE;GACjB,oBAAoB,EAAE;GACtB,aAAa,OAAO;GACrB;AAED,SAAO,SAAS,UAAU;AACxB,WAAQ,MAAM,MAAd;IACE,KAAK;AACH,aAAQ,YAAY,MAAM,UACvB,QAAQ,YAAY,MAAM,UAAU,KAAK;AAC5C;IACF,KAAK;AACH,aAAQ,cAAc,MAAM,YACzB,QAAQ,cAAc,MAAM,YAAY,KAAK;AAChD;IACF,KAAK,iBAAiB;KACpB,MAAM,WAAY,QAAQ,mBAAmB,MAAM,cAAc,EAAE;AACnE,cAAS,MAAM,SAAS,SAAS,MAAM,SAAS,KAAK;AACrD;;IAEF,QACE;;IAEJ;AAEF,SAAO;;CAGT,MAAM,QAAuB;AAC3B,OAAK,SAAS,EAAE;;;AAIpB,SAAS,aACP,QACA,OACiB;AACjB,QAAO,OAAO,QAAQ,UAAU;AAC9B,MAAI,MAAM,YAAY,MAAM,aAAa,MAAM,SAC7C,QAAO;AAET,MAAI,MAAM,UAAU,MAAM,WAAW,MAAM,OACzC,QAAO;AAET,MAAI,MAAM,QAAQ,MAAM,SAAS,MAAM,KACrC,QAAO;AAET,MAAI,MAAM,SAAS,MAAM,YAAY,MAAM,MACzC,QAAO;AAET,MAAI,MAAM,SAAS,MAAM,YAAY,MAAM,MACzC,QAAO;AAGT,MACE,MAAM,aACN,MAAM,SAAS,kBACf,MAAM,cAAc,MAAM,UAE1B,QAAO;AAET,MACE,MAAM,WACN,MAAM,SAAS,mBACf,MAAM,YAAY,MAAM,QAExB,QAAO;AAET,MACE,MAAM,YACN,MAAM,SAAS,mBACf,MAAM,aAAa,MAAM,SAEzB,QAAO;AAET,SAAO;GACP"}

package/dist/tracker.js.map

@@ -1 +0,0 @@
-{"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":";;;AAoBA,MAAM,sBAAsB;AAqB5B,IAAa,kBAAb,MAA6B;CAC3B,AAAiB;CACjB,AAAiB;CACjB,AAAiB,SAAS,MAAM,UAAU,wBAAwB,QAAQ;CAC1E,AAAiB,UAAU,QACxB,SAAS,wBAAwB,QAAQ,CACzC,cAAc,+BAA+B,EAC5C,aAAa,+CACd,CAAC;CAEJ,AAAQ,SAA0B,EAAE;CACpC,AAAiB;CACjB,AAAQ;CAER,YAAY,SAAiC;AAC3C,OAAK,QAAQ,QAAQ;AACrB,OAAK,UAAU,QAAQ;AACvB,OAAK,aAAa,QAAQ,cAAc;AAExC,MAAI,QAAQ,oBACV,MAAK,aAAa,kBAAkB;AAClC,GAAK,KAAK,OAAO;KAChB,QAAQ,oBAAoB;;CAInC,iBAAiB,OAA8B;EAC7C,MAAM,QAAQ;GACZ,MAAM;GACN,WAAW,MAAM;GACjB,OAAO,MAAM;GACb,WAAW,KAAK,KAAK;GACrB,GAAG,KAAK;GACR,UAAU;IAAE,GAAG,KAAK,QAAQ;IAAU,GAAG,MAAM;IAAU;GAC1D;AACD,OAAK,QAAQ,MAAM;;CAGrB,kBAAkB,OAA+B;EAC/C,MAAM,QAAQ;GACZ,MAAM;GACN,SAAS,MAAM;GACf,QAAQ,MAAM;GACd,WAAW,KAAK,KAAK;GACrB,GAAG,KAAK;GACR,UAAU;IAAE,GAAG,KAAK,QAAQ;IAAU,GAAG,MAAM;IAAU;GAC1D;AACD,OAAK,QAAQ,MAAM;;CAGrB,kBAAkB,OAA+B;EAC/C,MAAM,QAAQ;GACZ,MAAM;GACN,UAAU,MAAM;GAChB,MAAM,MAAM;GACZ,QAAQ,MAAM;GACd,WAAW,KAAK,KAAK;GACrB,GAAG,KAAK;GACR,UAAU;IAAE,GAAG,KAAK,QAAQ;IAAU,GAAG,MAAM;IAAU;GAC1D;AACD,OAAK,QAAQ,MAAM;;CAGrB,MAAM,QAAuB;AAC3B,MAAI,CAAC,KAAK,OAAO,OAAQ;EACzB,MAAM,SAAS,KAAK;AACpB,OAAK,SAAS,EAAE;AAChB,QAAM,KAAK,MAAM,WAAW,OAAO;;CAGrC,MAAM,UAAyB;AAC7B,MAAI,KAAK,WACP,eAAc,KAAK,WAAW;AAEhC,QAAM,KAAK,OAAO;;CAGpB,AAAQ,QAAQ,OAAsB;AACpC,OAAK,OAAO,KAAK,MAAM;AACvB,OAAK,QAAQ,IAAI,GAAG;GAClB,UAAU,KAAK,QAAQ;GACvB,MAAM,MAAM;GACb,CAAC;AAEF,OAAK,OAAO,gBAAgB,mBAAmB,MAAM,SAAS,SAAS;AACrE,QAAK,aAAa,aAAa,KAAK,QAAQ,SAAS;AACrD,OAAI,KAAK,QAAQ,OACf,MAAK,aAAa,WAAW,KAAK,QAAQ,OAAO;AACnD,QAAK,aAAa,8BAA8B,MAAM,KAAK;AAC3D,QAAK,KAAK;IACV;AAEF,MAAI,KAAK,OAAO,UAAU,KAAK,WAC7B,CAAK,KAAK,OAAO;;;AAKvB,MAAa,yBAAyB,YACpC,IAAI,gBAAgB,QAAQ"}