@lssm/lib.personalization 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217072406

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

@@ -1,81 +1,18 @@
-import{a as e}from"../contracts/dist/docs/registry.js";import"../contracts/dist/docs/index.js";const t=[{id:`docs.personalization.overlay-engine`,title:`Overlay Engine`,summary:"`@lssm/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",kind:`reference`,visibility:`public`,route:`/docs/personalization/overlay-engine`,tags:[`personalization`,`overlay-engine`],body:`# Overlay Engine
-
-\`@lssm/lib.overlay-engine\` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.
-
-## Key APIs
-
-- \`defineOverlay(spec)\` – helper to keep specs typed.
-- \`OverlayRegistry\` – register signed overlays and retrieve them per context.
-- \`OverlayEngine\` – apply overlays to renderable targets, emit audit events, and merge modifications deterministically.
-- \`signOverlay(spec, privateKey)\` – Ed25519/RSA-PSS signer.
-- \`verifyOverlaySignature(overlay)\` – verify public key signatures.
-- \`useOverlay(engine, params)\` – client hook that returns \`{ target, overlaysApplied }\`.
-
-## Scope Precedence
-
-Registrations are sorted by specificity:
-
-1. Tenant overlays
-2. Role overlays
-3. User overlays
-4. Device overlays
-
-Less specific overlays run first; more specific overlays override later.
-
-## Example
-
-\`\`\`ts
-const registry = new OverlayRegistry();
-const engine = new OverlayEngine({
-  registry,
-  audit: (event) => auditLogService.record(event),
-});
-
-const overlay = defineOverlay({
-  overlayId: 'acme-order-form',
-  version: '1.0.0',
-  appliesTo: {
-    capability: 'billing.createOrder',
-    tenantId: 'acme',
-  },
-  modifications: [
-    { type: 'hideField', field: 'internalNotes' },
-    { type: 'renameLabel', field: 'customerReference', newLabel: 'PO Number' },
-  ],
-});
-
-const signedOverlay = await signOverlay(overlay, privateKeyPem);
-registry.register(signedOverlay);
-
-const result = engine.apply({
-  target: { fields: baseFields },
-  capability: 'billing.createOrder',
-  tenantId: 'acme',
-  userId: 'manager-7',
-});
-\`\`\`
-
-\`result.target.fields\` now carries the hidden and renamed outputs ready for rendering.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];e(t);export{t as personalization_overlay_engine_DocBlocks};
+import { registerDocBlocks } from "../contracts/dist/docs/registry.js";
+import "../contracts/dist/docs/index.js";
+
+//#region src/docs/overlay-engine.docblock.ts
+const personalization_overlay_engine_DocBlocks = [{
+	id: "docs.personalization.overlay-engine",
+	title: "Overlay Engine",
+	summary: "`@lssm/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/personalization/overlay-engine",
+	tags: ["personalization", "overlay-engine"],
+	body: "# Overlay Engine\n\n`@lssm/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)` – helper to keep specs typed.\n- `OverlayRegistry` – register signed overlays and retrieve them per context.\n- `OverlayEngine` – apply overlays to renderable targets, emit audit events, and merge modifications deterministically.\n- `signOverlay(spec, privateKey)` – Ed25519/RSA-PSS signer.\n- `verifyOverlaySignature(overlay)` – verify public key signatures.\n- `useOverlay(engine, params)` – 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"
+}];
+registerDocBlocks(personalization_overlay_engine_DocBlocks);
+
+//#endregion
+export { personalization_overlay_engine_DocBlocks };

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

@@ -1,66 +1,18 @@
-import{a as e}from"../contracts/dist/docs/registry.js";import"../contracts/dist/docs/index.js";const t=[{id:`docs.personalization.workflow-composition`,title:`Workflow Composition`,summary:"`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",kind:`reference`,visibility:`public`,route:`/docs/personalization/workflow-composition`,tags:[`personalization`,`workflow-composition`],body:`# Workflow Composition
-
-\`@lssm/lib.workflow-composer\` composes base WorkflowSpecs with tenant/role/device-specific extensions.
-
-## Extensions
-
-\`\`\`ts
-import { WorkflowComposer } from '@lssm/lib.workflow-composer';
-import { approvalStepTemplate } from '@lssm/lib.workflow-composer/templates';
-
-const composer = new WorkflowComposer();
-
-composer.register({
-  workflow: 'billing.invoiceApproval',
-  tenantId: 'acme',
-  priority: 10,
-  customSteps: [
-    {
-      after: 'validate-invoice',
-      inject: approvalStepTemplate({
-        id: 'acme-legal-review',
-        label: 'Legal Review (ACME)',
-        description: 'Tenant-specific compliance step.',
-      }),
-      transitionTo: 'final-approval',
-    },
-  ],
-  hiddenSteps: ['internal-audit'],
-});
-\`\`\`
-
-## Compose
-
-\`\`\`ts
-const runtimeSpec = composer.compose({
-  base: BaseInvoiceWorkflow,
-  tenantId: 'acme',
-});
-
-workflowRunner.execute(runtimeSpec, ctx);
-\`\`\`
-
-The composer uses anchor references (\`after\`/\`before\`) to place injected steps and cleans up transitions when steps are hidden.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];e(t);export{t as personalization_workflow_composition_DocBlocks};
+import { registerDocBlocks } from "../contracts/dist/docs/registry.js";
+import "../contracts/dist/docs/index.js";
+
+//#region src/docs/workflow-composition.docblock.ts
+const personalization_workflow_composition_DocBlocks = [{
+	id: "docs.personalization.workflow-composition",
+	title: "Workflow Composition",
+	summary: "`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/personalization/workflow-composition",
+	tags: ["personalization", "workflow-composition"],
+	body: "# Workflow Composition\n\n`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.\n\n## Extensions\n\n```ts\nimport { WorkflowComposer } from '@lssm/lib.workflow-composer';\nimport { approvalStepTemplate } from '@lssm/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"
+}];
+registerDocBlocks(personalization_workflow_composition_DocBlocks);
+
+//#endregion
+export { personalization_workflow_composition_DocBlocks };

package/dist/index.js

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

package/dist/store.js

@@ -1 +1,58 @@
-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};
+//#region src/store.ts
+var InMemoryBehaviorStore = class {
+	events = [];
+	async record(event) {
+		this.events.push(event);
+	}
+	async bulkRecord(events) {
+		this.events.push(...events);
+	}
+	async query(query) {
+		return filterEvents(this.events, query);
+	}
+	async summarize(query) {
+		const events = await this.query(query);
+		const summary = {
+			fieldCounts: {},
+			featureCounts: {},
+			workflowStepCounts: {},
+			totalEvents: events.length
+		};
+		events.forEach((event) => {
+			switch (event.type) {
+				case "field_access":
+					summary.fieldCounts[event.field] = (summary.fieldCounts[event.field] ?? 0) + 1;
+					break;
+				case "feature_usage":
+					summary.featureCounts[event.feature] = (summary.featureCounts[event.feature] ?? 0) + 1;
+					break;
+				case "workflow_step": {
+					const workflow = summary.workflowStepCounts[event.workflow] ??= {};
+					workflow[event.step] = (workflow[event.step] ?? 0) + 1;
+					break;
+				}
+				default: break;
+			}
+		});
+		return summary;
+	}
+	async clear() {
+		this.events = [];
+	}
+};
+function filterEvents(events, query) {
+	return events.filter((event) => {
+		if (query.tenantId && event.tenantId !== query.tenantId) return false;
+		if (query.userId && event.userId !== query.userId) return false;
+		if (query.role && event.role !== query.role) return false;
+		if (query.since && event.timestamp < query.since) return false;
+		if (query.until && event.timestamp > query.until) return false;
+		if (query.operation && event.type === "field_access" && event.operation !== query.operation) return false;
+		if (query.feature && event.type === "feature_usage" && event.feature !== query.feature) return false;
+		if (query.workflow && event.type === "workflow_step" && event.workflow !== query.workflow) return false;
+		return true;
+	});
+}
+
+//#endregion
+export { InMemoryBehaviorStore };

package/dist/tracker.js

@@ -1 +1,92 @@
-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};
+import { metrics, trace } from "@opentelemetry/api";
+
+//#region src/tracker.ts
+const DEFAULT_BUFFER_SIZE = 25;
+var BehaviorTracker = class {
+	store;
+	context;
+	tracer = trace.getTracer("lssm.personalization", "1.0.0");
+	counter = metrics.getMeter("lssm.personalization", "1.0.0").createCounter("lssm.personalization.events", { description: "Behavior events tracked for personalization" });
+	buffer = [];
+	bufferSize;
+	flushTimer;
+	constructor(options) {
+		this.store = options.store;
+		this.context = options.context;
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		if (options.autoFlushIntervalMs) this.flushTimer = setInterval(() => {
+			this.flush();
+		}, options.autoFlushIntervalMs);
+	}
+	trackFieldAccess(input) {
+		const event = {
+			type: "field_access",
+			operation: input.operation,
+			field: input.field,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	trackFeatureUsage(input) {
+		const event = {
+			type: "feature_usage",
+			feature: input.feature,
+			action: input.action,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	trackWorkflowStep(input) {
+		const event = {
+			type: "workflow_step",
+			workflow: input.workflow,
+			step: input.step,
+			status: input.status,
+			timestamp: Date.now(),
+			...this.context,
+			metadata: {
+				...this.context.metadata,
+				...input.metadata
+			}
+		};
+		this.enqueue(event);
+	}
+	async flush() {
+		if (!this.buffer.length) return;
+		const events = this.buffer;
+		this.buffer = [];
+		await this.store.bulkRecord(events);
+	}
+	async dispose() {
+		if (this.flushTimer) clearInterval(this.flushTimer);
+		await this.flush();
+	}
+	enqueue(event) {
+		this.buffer.push(event);
+		this.counter.add(1, {
+			tenantId: this.context.tenantId,
+			type: event.type
+		});
+		this.tracer.startActiveSpan(`personalization.${event.type}`, (span) => {
+			span.setAttribute("tenant.id", this.context.tenantId);
+			if (this.context.userId) span.setAttribute("user.id", this.context.userId);
+			span.setAttribute("personalization.event_type", event.type);
+			span.end();
+		});
+		if (this.buffer.length >= this.bufferSize) this.flush();
+	}
+};
+const createBehaviorTracker = (options) => new BehaviorTracker(options);
+
+//#endregion
+export { BehaviorTracker, createBehaviorTracker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.personalization",
-  "version": "0.0.0-canary-20251217063201",
+  "version": "0.0.0-canary-20251217072406",
   "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,16 +24,17 @@
     "test": "bun run"
   },
   "dependencies": {
-    "@lssm/lib.bus": "0.0.0-canary-20251217063201",
-    "@lssm/lib.overlay-engine": "0.0.0-canary-20251217063201",
+    "@lssm/lib.bus": "0.0.0-canary-20251217072406",
+    "@lssm/lib.knowledge": "0.0.0-canary-20251217072406",
+    "@lssm/lib.overlay-engine": "0.0.0-canary-20251217072406",
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217063201",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217063201",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217072406",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217072406",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },