@contractspec/lib.personalization 6.0.26 → 6.1.1

package/dist/browser/index.js

@@ -1,212 +0,0 @@
-function O(e,t){let r=[];if(e.suggestedHiddenFields.forEach((o)=>{r.push({type:"hideField",field:o,reason:"Automatically hidden because usage is near zero"})}),e.frequentlyUsedFields.length)r.push({type:"reorderFields",fields:e.frequentlyUsedFields});if(!r.length)return null;return{overlayId:t.overlayId,version:t.version??"1.0.0",appliesTo:{tenantId:t.tenantId,capability:t.capability,userId:t.userId,role:t.role},modifications:r,metadata:{generatedAt:new Date().toISOString(),automated:!0}}}function A(e){return e.workflowBottlenecks.map((t)=>({workflow:t.workflow,step:t.step,note:`High drop rate (${Math.round(t.dropRate*100)}%) detected`}))}class h{store;options;constructor(e,t={}){this.store=e;this.options=t}async analyze(e){let t={tenantId:e.tenantId,userId:e.userId,role:e.role};if(e.windowMs)t.since=Date.now()-e.windowMs;let r=await this.store.summarize(t);return v(r,this.options)}}function v(e,t){let r=t.fieldInactivityThreshold??3,o=t.minSamples??10,i=[],l=[];for(let[n,s]of Object.entries(e.fieldCounts)){if(s<=r)i.push(n);if(s>=r*4)l.push(n)}let c=Object.entries(e.workflowStepCounts).flatMap(([n,s])=>{let u=Object.values(s).reduce((a,d)=>a+d,0);if(!u||u<o)return[];return Object.entries(s).filter(([,a])=>a/u<0.4).map(([a,d])=>({workflow:n,step:a,dropRate:1-d/u}))}),p=m(e);return{unusedFields:i,suggestedHiddenFields:i.slice(0,5),frequentlyUsedFields:l.slice(0,10),workflowBottlenecks:c,layoutPreference:p}}function m(e){let t=Object.keys(e.fieldCounts).length;if(!t)return;if(t>=15)return"table";if(t>=8)return"grid";return"form"}import{registerDocBlocks as g}from"@contractspec/lib.contracts-spec/docs";var y=[{id:"docs.personalization.behavior-tracking",title:"Behavior Tracking",summary:"`@contractspec/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.",kind:"reference",visibility:"public",route:"/docs/personalization/behavior-tracking",tags:["personalization","behavior-tracking"],body:`# Behavior Tracking
-
-\`@contractspec/lib.personalization\` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.
-
-## Tracker
-
-\`\`\`ts
-import { createBehaviorTracker } from '@contractspec/lib.personalization';
-import { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';
-
-const tracker = createBehaviorTracker({
-  store: new InMemoryBehaviorStore(),
-  context: { tenantId: ctx.tenant.id, userId: ctx.identity.userId },
-  autoFlushIntervalMs: 5000,
-});
-
-tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'internalNotes' });
-tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
-tracker.trackWorkflowStep({ workflow: 'invoice-approval', step: 'review', status: 'entered' });
-\`\`\`
-
-All 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.
-
-## Analyzer
-
-\`\`\`ts
-import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
-
-const analyzer = new BehaviorAnalyzer(store, { fieldInactivityThreshold: 2 });
-const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'manager-42', windowMs: 7 * 24 * 60 * 60 * 1000 });
-
-/*
-{
-  unusedFields: ['internalNotes'],
-  suggestedHiddenFields: ['internalNotes'],
-  frequentlyUsedFields: ['customerReference', 'items'],
-  workflowBottlenecks: [{ workflow: 'invoice-approval', step: 'finance-review', dropRate: 0.6 }],
-  layoutPreference: 'table'
-}
-*/
-\`\`\`
-
-Use the analyzer output with the overlay adapter to generate suggestions automatically.
-
-## Adapter
-
-\`\`\`ts
-import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
-
-const overlay = insightsToOverlaySuggestion(insights, {
-  overlayId: 'acme-order-form',
-  tenantId: 'acme',
-  capability: 'billing.createOrder',
-});
-\`\`\`
-
-When the adapter returns an overlay spec, pass it to the overlay engine to register or sign it.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];g(y);import{registerDocBlocks as w}from"@contractspec/lib.contracts-spec/docs";var B=[{id:"docs.personalization.overlay-engine",title:"Overlay Engine",summary:"`@contractspec/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
-
-\`@contractspec/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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`}];w(B);import{registerDocBlocks as k}from"@contractspec/lib.contracts-spec/docs";var I=[{id:"docs.personalization.workflow-composition",title:"Workflow Composition",summary:"`@contractspec/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions, strict validation, deterministic merge ordering, metadata/annotation overlays, and orphan-graph protection for hidden-step rewrites.",kind:"reference",visibility:"public",route:"/docs/personalization/workflow-composition",tags:["personalization","workflow-composition"],body:`# Workflow Composition
-
-\`@contractspec/lib.workflow-composer\` composes base WorkflowSpecs with tenant/role/device-specific extensions.
-
-## Extensions
-
-\`\`\`ts
-import { WorkflowComposer } from '@contractspec/lib.workflow-composer';
-import { approvalStepTemplate } from '@contractspec/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.',
-      }),
-      transitionFrom: 'validate-invoice',
-      transitionTo: 'final-approval',
-    },
-  ],
-  hiddenSteps: ['internal-audit'],
-  metadata: { rollout: 'tenant-acme' },
-});
-\`\`\`
-
-## Compose
-
-\`\`\`ts
-const runtimeSpec = composer.compose({
-  base: BaseInvoiceWorkflow,
-  tenantId: 'acme',
-});
-
-workflowRunner.execute(runtimeSpec, ctx);
-\`\`\`
-
-## Guarantees
-
-- Extensions are normalized in deterministic priority order before composition.
-- Duplicate injected step ids, invalid anchors, and invalid transition endpoints are rejected early.
-- Hidden-step rewrites are validated so remaining steps stay reachable from the workflow entry step.
-- \`metadata\` and \`annotations\` overlays are merged into the composed runtime workflow for downstream observability and rollout tracing.
-
-This keeps tenant overlays additive, auditable, and replay-safe.
-`}];k(I);class x{events=[];async record(e){this.events.push(e)}async bulkRecord(e){this.events.push(...e)}async query(e){return b(this.events,e)}async summarize(e){let t=await this.query(e),r={fieldCounts:{},featureCounts:{},workflowStepCounts:{},totalEvents:t.length};return t.forEach((o)=>{switch(o.type){case"field_access":r.fieldCounts[o.field]=(r.fieldCounts[o.field]??0)+1;break;case"feature_usage":r.featureCounts[o.feature]=(r.featureCounts[o.feature]??0)+1;break;case"workflow_step":{let i=r.workflowStepCounts[o.workflow]??={};i[o.step]=(i[o.step]??0)+1;break}default:break}}),r}async clear(){this.events=[]}}function b(e,t){return e.filter((r)=>{if(t.tenantId&&r.tenantId!==t.tenantId)return!1;if(t.userId&&r.userId!==t.userId)return!1;if(t.role&&r.role!==t.role)return!1;if(t.since&&r.timestamp<t.since)return!1;if(t.until&&r.timestamp>t.until)return!1;if(t.operation&&r.type==="field_access"&&r.operation!==t.operation)return!1;if(t.feature&&r.type==="feature_usage"&&r.feature!==t.feature)return!1;if(t.workflow&&r.type==="workflow_step"&&r.workflow!==t.workflow)return!1;return!0})}import{metrics as S,trace as E}from"@opentelemetry/api";var F=25;class f{store;context;tracer=E.getTracer("lssm.personalization","1.0.0");counter=S.getMeter("lssm.personalization","1.0.0").createCounter("lssm.personalization.events",{description:"Behavior events tracked for personalization"});buffer=[];bufferSize;flushTimer;constructor(e){if(this.store=e.store,this.context=e.context,this.bufferSize=e.bufferSize??F,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(){if(this.flushTimer)clearInterval(this.flushTimer);await this.flush()}enqueue(e){if(this.buffer.push(e),this.counter.add(1,{tenantId:this.context.tenantId,type:e.type}),this.tracer.startActiveSpan(`personalization.${e.type}`,(t)=>{if(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()}}var $=(e)=>new f(e);import{defineFeature as T}from"@contractspec/lib.contracts-spec/features";var q=T({meta:{key:"libs.personalization",version:"1.0.0",title:"Personalization",description:"Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",domain:"personalization",owners:["@contractspec-core"],tags:["package","libs","personalization"],stability:"experimental"}});export{A as insightsToWorkflowAdaptations,O as insightsToOverlaySuggestion,$ as createBehaviorTracker,q as PersonalizationFeature,x as InMemoryBehaviorStore,f as BehaviorTracker,h as BehaviorAnalyzer};

package/dist/browser/personalization.feature.js

@@ -1 +0,0 @@
-import{defineFeature as g}from"@contractspec/lib.contracts-spec/features";var j=g({meta:{key:"libs.personalization",version:"1.0.0",title:"Personalization",description:"Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",domain:"personalization",owners:["@contractspec-core"],tags:["package","libs","personalization"],stability:"experimental"}});export{j as PersonalizationFeature};

package/dist/browser/store.js

@@ -1 +0,0 @@
-class i{events=[];async record(o){this.events.push(o)}async bulkRecord(o){this.events.push(...o)}async query(o){return s(this.events,o)}async summarize(o){let e=await this.query(o),r={fieldCounts:{},featureCounts:{},workflowStepCounts:{},totalEvents:e.length};return e.forEach((t)=>{switch(t.type){case"field_access":r.fieldCounts[t.field]=(r.fieldCounts[t.field]??0)+1;break;case"feature_usage":r.featureCounts[t.feature]=(r.featureCounts[t.feature]??0)+1;break;case"workflow_step":{let a=r.workflowStepCounts[t.workflow]??={};a[t.step]=(a[t.step]??0)+1;break}default:break}}),r}async clear(){this.events=[]}}function s(o,e){return o.filter((r)=>{if(e.tenantId&&r.tenantId!==e.tenantId)return!1;if(e.userId&&r.userId!==e.userId)return!1;if(e.role&&r.role!==e.role)return!1;if(e.since&&r.timestamp<e.since)return!1;if(e.until&&r.timestamp>e.until)return!1;if(e.operation&&r.type==="field_access"&&r.operation!==e.operation)return!1;if(e.feature&&r.type==="feature_usage"&&r.feature!==e.feature)return!1;if(e.workflow&&r.type==="workflow_step"&&r.workflow!==e.workflow)return!1;return!0})}export{i as InMemoryBehaviorStore};

package/dist/browser/tracker.js

@@ -1 +0,0 @@
-import{metrics as a,trace as s}from"@opentelemetry/api";var i=25;class r{store;context;tracer=s.getTracer("lssm.personalization","1.0.0");counter=a.getMeter("lssm.personalization","1.0.0").createCounter("lssm.personalization.events",{description:"Behavior events tracked for personalization"});buffer=[];bufferSize;flushTimer;constructor(e){if(this.store=e.store,this.context=e.context,this.bufferSize=e.bufferSize??i,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(){if(this.flushTimer)clearInterval(this.flushTimer);await this.flush()}enqueue(e){if(this.buffer.push(e),this.counter.add(1,{tenantId:this.context.tenantId,type:e.type}),this.tracer.startActiveSpan(`personalization.${e.type}`,(t)=>{if(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()}}var n=(e)=>new r(e);export{n as createBehaviorTracker,r as BehaviorTracker};