@contractspec/lib.personalization 6.0.16 → 6.0.18

package/README.md

@@ -1,79 +1,177 @@
 # @contractspec/lib.personalization
 
-Website: https://contractspec.io
-
-**Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.**
+`@contractspec/lib.personalization` tracks behavior events, summarizes them into actionable insights, and converts those insights into personalization outputs such as overlay suggestions. It also defines the shared preference-dimensions model consumed by runtime layers.
 
-## What It Provides
-
-- **Layer**: lib.
-- **Consumers**: bundles, example apps.
-- `src/docs/` contains docblocks and documentation-facing exports.
-- Related ContractSpec packages include `@contractspec/lib.bus`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.knowledge`, `@contractspec/lib.overlay-engine`, `@contractspec/lib.schema`, `@contractspec/lib.surface-runtime`, ...
-- `src/docs/` contains docblocks and documentation-facing exports.
+Website: https://contractspec.io
 
 ## Installation
 
-`npm install @contractspec/lib.personalization`
+`bun add @contractspec/lib.personalization`
 
 or
 
-`bun add @contractspec/lib.personalization`
+`npm install @contractspec/lib.personalization`
 
-## Usage
-
-Import the root entrypoint from `@contractspec/lib.personalization`, or choose a documented subpath when you only need one part of the package surface.
-
-## Architecture
-
-- `src/adapter.ts` is part of the package's public or composition surface.
-- `src/analyzer.ts` is part of the package's public or composition surface.
-- `src/docs/` contains docblocks and documentation-facing exports.
-- `src/index.ts` is the root public barrel and package entrypoint.
-- `src/preference-dimensions.ts` is part of the package's public or composition surface.
-- `src/store.ts` is part of the package's public or composition surface.
-- `src/tracker.ts` is part of the package's public or composition surface.
-- `src/types.ts` is shared public type definitions.
-
-## Public Entry Points
-
-- Export `.` resolves through `./src/index.ts`.
-- Export `./adapter` resolves through `./src/adapter.ts`.
-- Export `./analyzer` resolves through `./src/analyzer.ts`.
-- Export `./docs` resolves through `./src/docs/index.ts`.
-- Export `./docs/behavior-tracking.docblock` resolves through `./src/docs/behavior-tracking.docblock.ts`.
-- Export `./docs/overlay-engine.docblock` resolves through `./src/docs/overlay-engine.docblock.ts`.
-- Export `./docs/workflow-composition.docblock` resolves through `./src/docs/workflow-composition.docblock.ts`.
-- Export `./preference-dimensions` resolves through `./src/preference-dimensions.ts`.
-- Export `./store` resolves through `./src/store.ts`.
-- Export `./tracker` resolves through `./src/tracker.ts`.
-- The package publishes 11 total export subpaths; keep docs aligned with `package.json`.
-
-## Local Commands
-
-- `bun run dev` — contractspec-bun-build dev
-- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
-- `bun run test` — bun test --pass-with-no-tests
-- `bun run lint` — bun lint:fix
-- `bun run lint:check` — biome check .
-- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
-- `bun run typecheck` — tsc --noEmit
-- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
-- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
-- `bun run clean` — rimraf dist .turbo
-- `bun run build:bundle` — contractspec-bun-build transpile
-- `bun run build:types` — contractspec-bun-build types
-- `bun run prebuild` — contractspec-bun-build prebuild
-
-## Recent Updates
-
-- Replace eslint+prettier by biomejs to optimize speed.
-- Vercel AI SDK parity + surface-runtime i18n and bundle alignment.
-- Bundle spec alignment, i18n support, PM workbench pilot.
-- Upgrade dependencies.
-
-## Notes
-
-- Tracker interface is the adapter boundary — implementation details must not leak.
-- Behavior data schema must stay backward-compatible; older events must remain parseable.
-- Depends on bus, overlay-engine, and knowledge — coordinate cross-lib changes.
+## What belongs here
+
+This package currently has two jobs:
+
+- Behavior telemetry and analysis: `tracker`, `store`, `analyzer`, `adapter`, and `types` handle event capture, storage, summarization, and conversion into adaptation hints.
+- Shared preference contracts: `preference-dimensions` defines the 7-dimension personalization model and the adapter types used by runtime consumers.
+
+Use this package when you need a thin personalization layer inside ContractSpec. Do not use it as a general analytics platform or as the full overlay runtime.
+
+## Core workflow
+
+```ts
+import {
+  BehaviorAnalyzer,
+  createBehaviorTracker,
+  insightsToOverlaySuggestion,
+  InMemoryBehaviorStore,
+} from "@contractspec/lib.personalization";
+
+const store = new InMemoryBehaviorStore();
+
+const tracker = createBehaviorTracker({
+  store,
+  context: {
+    tenantId: "acme",
+    userId: "user-123",
+    role: "manager",
+  },
+  autoFlushIntervalMs: 5000,
+});
+
+tracker.trackFieldAccess({
+  operation: "billing.createOrder",
+  field: "internalNotes",
+});
+tracker.trackFieldAccess({
+  operation: "billing.createOrder",
+  field: "customerReference",
+});
+tracker.trackFeatureUsage({
+  feature: "workflow-editor",
+  action: "opened",
+});
+tracker.trackWorkflowStep({
+  workflow: "invoice-approval",
+  step: "review",
+  status: "entered",
+});
+
+await tracker.flush();
+await tracker.dispose();
+
+const analyzer = new BehaviorAnalyzer(store, {
+  fieldInactivityThreshold: 2,
+});
+
+const insights = await analyzer.analyze({
+  tenantId: "acme",
+  userId: "user-123",
+  windowMs: 7 * 24 * 60 * 60 * 1000,
+});
+
+const overlay = insightsToOverlaySuggestion(insights, {
+  overlayId: "acme-order-form",
+  tenantId: "acme",
+  capability: "billing.createOrder",
+});
+```
+
+Typical flow:
+
+1. Record behavior events through `BehaviorTracker`.
+2. Persist and summarize those events through a `BehaviorStore`.
+3. Analyze the summary with `BehaviorAnalyzer`.
+4. Convert insights into an `OverlaySpec` suggestion or workflow adaptation hints.
+
+## API map
+
+### Main runtime APIs
+
+- `BehaviorStore`: persistence boundary for recording, querying, and summarizing `BehaviorEvent` data.
+- `InMemoryBehaviorStore`: simple in-memory implementation for tests, demos, and local composition.
+- `BehaviorTracker` and `createBehaviorTracker`: buffered event capture with tenant/user context and OpenTelemetry instrumentation.
+- `BehaviorAnalyzer`: converts `BehaviorSummary` data into `BehaviorInsights`.
+- `insightsToOverlaySuggestion`: turns analysis output into an overlay-engine `OverlaySpec`.
+- `insightsToWorkflowAdaptations`: turns workflow bottlenecks into lightweight adaptation notes.
+
+### Core data contracts
+
+- `BehaviorEvent`: discriminated union with three event kinds: `field_access`, `feature_usage`, and `workflow_step`.
+- `BehaviorQuery`: filter shape used by `BehaviorStore.query()` and `BehaviorStore.summarize()`.
+- `BehaviorSummary`: aggregated counts returned by store summarization.
+- `BehaviorInsights`: analyzer output including hidden-field candidates, bottlenecks, and layout preference hints.
+- `BehaviorAnalyzerOptions`: tuning knobs for inactivity threshold and minimum workflow sample size.
+- `OverlaySuggestionOptions`: metadata required to build an overlay suggestion.
+- `WorkflowAdaptation`: workflow, step, and note triple derived from bottlenecks.
+
+### Preference model contracts
+
+- `PreferenceDimensions`: the shared 7-dimension personalization model.
+- `PreferenceScope`: source scope used when a preference value is resolved.
+- `ResolvedPreferenceProfile`: canonical resolved preferences plus source attribution and constraint notes.
+- `PreferenceResolutionContext`: minimal runtime context required to resolve a preference profile.
+- `BundlePreferenceAdapter`: contract for resolving and persisting preference patches in runtime consumers.
+
+## Public entrypoints
+
+The root barrel at `src/index.ts` re-exports public symbols from:
+
+- `adapter`
+- `analyzer`
+- `preference-dimensions`
+- `store`
+- `tracker`
+- `types`
+
+Published subpaths from `package.json`:
+
+- `.`
+- `./adapter`
+- `./analyzer`
+- `./docs`
+- `./docs/behavior-tracking.docblock`
+- `./docs/overlay-engine.docblock`
+- `./docs/workflow-composition.docblock`
+- `./preference-dimensions`
+- `./store`
+- `./tracker`
+- `./types`
+
+For application code, prefer `.` or the focused subpaths above. The `./docs*` subpaths exist for docblock registration and documentation surfaces.
+
+## Operational semantics and gotchas
+
+- `BehaviorTracker` buffers events in memory and flushes when the buffer reaches the configured size or when `autoFlushIntervalMs` is enabled.
+- `flush()` persists the current buffer with `BehaviorStore.bulkRecord()`.
+- `dispose()` clears the interval timer, then flushes any remaining buffered events.
+- Each enqueue also emits OpenTelemetry metrics and tracing through `@opentelemetry/api`.
+- `BehaviorAnalyzer` uses deterministic threshold heuristics. It does not do ranking, learning, or probabilistic inference.
+- `insightsToOverlaySuggestion()` currently emits only `hideField` and `reorderFields` modifications.
+- `layoutPreference` is inferred from field-count thresholds, not from UI render telemetry.
+- `PreferenceDimensions` and related types are contracts. Durable persistence and runtime resolution live elsewhere.
+
+## When not to use this package
+
+- Do not use it as a full analytics warehouse or reporting system.
+- Do not use it as the durable preference persistence layer.
+- Do not use it as the overlay runtime or overlay registry implementation.
+- Do not use it when you need workflow composition itself; this package only emits adaptation hints.
+
+## Related packages
+
+- `@contractspec/lib.overlay-engine`: runtime for registering, validating, and applying overlays.
+- `@contractspec/lib.surface-runtime`: runtime consumer of preference resolution and adaptive surface behavior.
+- `@contractspec/lib.workflow-composer`: workflow extension and composition runtime.
+- `@contractspec/lib.contracts-spec`: shared spec and docblock contracts used across ContractSpec.
+
+## Local commands
+
+- `bun run lint:check`
+- `bun run typecheck`
+- `bun run test`
+- `bun run build`

package/dist/adapter.js

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

package/dist/analyzer.js

@@ -1,73 +1,2 @@
 // @bun
-// src/analyzer.ts
-var DEFAULT_THRESHOLD = 3;
-
-class BehaviorAnalyzer {
-  store;
-  options;
-  constructor(store, options = {}) {
-    this.store = store;
-    this.options = options;
-  }
-  async analyze(params) {
-    const query = {
-      tenantId: params.tenantId,
-      userId: params.userId,
-      role: params.role
-    };
-    if (params.windowMs) {
-      query.since = Date.now() - params.windowMs;
-    }
-    const summary = await this.store.summarize(query);
-    return buildInsights(summary, this.options);
-  }
-}
-function buildInsights(summary, options) {
-  const threshold = options.fieldInactivityThreshold ?? DEFAULT_THRESHOLD;
-  const minSamples = options.minSamples ?? 10;
-  const ignoredFields = [];
-  const frequentlyUsedFields = [];
-  for (const [field, count] of Object.entries(summary.fieldCounts)) {
-    if (count <= threshold) {
-      ignoredFields.push(field);
-    }
-    if (count >= threshold * 4) {
-      frequentlyUsedFields.push(field);
-    }
-  }
-  const workflowBottlenecks = Object.entries(summary.workflowStepCounts).flatMap(([workflow, steps]) => {
-    const total = Object.values(steps).reduce((acc, value) => acc + value, 0);
-    if (!total || total < minSamples) {
-      return [];
-    }
-    return Object.entries(steps).filter(([, count]) => count / total < 0.4).map(([step, count]) => ({
-      workflow,
-      step,
-      dropRate: 1 - count / total
-    }));
-  });
-  const layoutPreference = detectLayout(summary);
-  return {
-    unusedFields: ignoredFields,
-    suggestedHiddenFields: ignoredFields.slice(0, 5),
-    frequentlyUsedFields: frequentlyUsedFields.slice(0, 10),
-    workflowBottlenecks,
-    layoutPreference
-  };
-}
-function detectLayout(summary) {
-  const fieldCount = Object.keys(summary.fieldCounts).length;
-  if (!fieldCount) {
-    return;
-  }
-  if (fieldCount >= 15) {
-    return "table";
-  }
-  if (fieldCount >= 8) {
-    return "grid";
-  }
-  return "form";
-}
-export {
-  BehaviorAnalyzer
-};
+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 i=await this.store.summarize(t);return y(i,this.options)}}function y(e,t){let i=t.fieldInactivityThreshold??3,d=t.minSamples??10,a=[],u=[];for(let[o,r]of Object.entries(e.fieldCounts)){if(r<=i)a.push(o);if(r>=i*4)u.push(o)}let c=Object.entries(e.workflowStepCounts).flatMap(([o,r])=>{let s=Object.values(r).reduce((n,l)=>n+l,0);if(!s||s<d)return[];return Object.entries(r).filter(([,n])=>n/s<0.4).map(([n,l])=>({workflow:o,step:n,dropRate:1-l/s}))}),f=m(e);return{unusedFields:a,suggestedHiddenFields:a.slice(0,5),frequentlyUsedFields:u.slice(0,10),workflowBottlenecks:c,layoutPreference:f}}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"}export{h as BehaviorAnalyzer};

package/dist/browser/adapter.js

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

package/dist/browser/analyzer.js

@@ -1,72 +1 @@
-// src/analyzer.ts
-var DEFAULT_THRESHOLD = 3;
-
-class BehaviorAnalyzer {
-  store;
-  options;
-  constructor(store, options = {}) {
-    this.store = store;
-    this.options = options;
-  }
-  async analyze(params) {
-    const query = {
-      tenantId: params.tenantId,
-      userId: params.userId,
-      role: params.role
-    };
-    if (params.windowMs) {
-      query.since = Date.now() - params.windowMs;
-    }
-    const summary = await this.store.summarize(query);
-    return buildInsights(summary, this.options);
-  }
-}
-function buildInsights(summary, options) {
-  const threshold = options.fieldInactivityThreshold ?? DEFAULT_THRESHOLD;
-  const minSamples = options.minSamples ?? 10;
-  const ignoredFields = [];
-  const frequentlyUsedFields = [];
-  for (const [field, count] of Object.entries(summary.fieldCounts)) {
-    if (count <= threshold) {
-      ignoredFields.push(field);
-    }
-    if (count >= threshold * 4) {
-      frequentlyUsedFields.push(field);
-    }
-  }
-  const workflowBottlenecks = Object.entries(summary.workflowStepCounts).flatMap(([workflow, steps]) => {
-    const total = Object.values(steps).reduce((acc, value) => acc + value, 0);
-    if (!total || total < minSamples) {
-      return [];
-    }
-    return Object.entries(steps).filter(([, count]) => count / total < 0.4).map(([step, count]) => ({
-      workflow,
-      step,
-      dropRate: 1 - count / total
-    }));
-  });
-  const layoutPreference = detectLayout(summary);
-  return {
-    unusedFields: ignoredFields,
-    suggestedHiddenFields: ignoredFields.slice(0, 5),
-    frequentlyUsedFields: frequentlyUsedFields.slice(0, 10),
-    workflowBottlenecks,
-    layoutPreference
-  };
-}
-function detectLayout(summary) {
-  const fieldCount = Object.keys(summary.fieldCounts).length;
-  if (!fieldCount) {
-    return;
-  }
-  if (fieldCount >= 15) {
-    return "table";
-  }
-  if (fieldCount >= 8) {
-    return "grid";
-  }
-  return "form";
-}
-export {
-  BehaviorAnalyzer
-};
+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 i=await this.store.summarize(t);return y(i,this.options)}}function y(e,t){let i=t.fieldInactivityThreshold??3,d=t.minSamples??10,a=[],u=[];for(let[o,r]of Object.entries(e.fieldCounts)){if(r<=i)a.push(o);if(r>=i*4)u.push(o)}let c=Object.entries(e.workflowStepCounts).flatMap(([o,r])=>{let s=Object.values(r).reduce((n,l)=>n+l,0);if(!s||s<d)return[];return Object.entries(r).filter(([,n])=>n/s<0.4).map(([n,l])=>({workflow:o,step:n,dropRate:1-l/s}))}),f=m(e);return{unusedFields:a,suggestedHiddenFields:a.slice(0,5),frequentlyUsedFields:u.slice(0,10),workflowBottlenecks:c,layoutPreference:f}}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"}export{h as BehaviorAnalyzer};

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

@@ -1,15 +1,4 @@
-// src/docs/behavior-tracking.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
-var personalization_behavior_tracking_DocBlocks = [
-  {
-    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
+import{registerDocBlocks as d}from"@contractspec/lib.contracts-spec/docs";var f=[{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.
 
@@ -88,10 +77,4 @@ When the adapter returns an overlay spec, pass it to the overlay engine to regis
 
 
 
-`
-  }
-];
-registerDocBlocks(personalization_behavior_tracking_DocBlocks);
-export {
-  personalization_behavior_tracking_DocBlocks
-};
+`}];d(f);export{f as personalization_behavior_tracking_DocBlocks};

package/dist/browser/docs/index.js

@@ -1,15 +1,4 @@
-// src/docs/behavior-tracking.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
-var personalization_behavior_tracking_DocBlocks = [
-  {
-    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
+import{registerDocBlocks as m}from"@contractspec/lib.contracts-spec/docs";var d=[{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.
 
@@ -88,23 +77,7 @@ When the adapter returns an overlay spec, pass it to the overlay engine to regis
 
 
 
-`
-  }
-];
-registerDocBlocks(personalization_behavior_tracking_DocBlocks);
-
-// src/docs/overlay-engine.docblock.ts
-import { registerDocBlocks as registerDocBlocks2 } from "@contractspec/lib.contracts-spec/docs";
-var personalization_overlay_engine_DocBlocks = [
-  {
-    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
+`}];m(d);import{registerDocBlocks as j}from"@contractspec/lib.contracts-spec/docs";var q=[{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.
 
@@ -184,23 +157,7 @@ const result = engine.apply({
 
 
 
-`
-  }
-];
-registerDocBlocks2(personalization_overlay_engine_DocBlocks);
-
-// src/docs/workflow-composition.docblock.ts
-import { registerDocBlocks as registerDocBlocks3 } from "@contractspec/lib.contracts-spec/docs";
-var personalization_workflow_composition_DocBlocks = [
-  {
-    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
+`}];j(q);import{registerDocBlocks as u}from"@contractspec/lib.contracts-spec/docs";var x=[{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.
 
@@ -252,7 +209,4 @@ workflowRunner.execute(runtimeSpec, ctx);
 - \`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.
-`
-  }
-];
-registerDocBlocks3(personalization_workflow_composition_DocBlocks);
+`}];u(x);

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

@@ -1,15 +1,4 @@
-// src/docs/overlay-engine.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
-var personalization_overlay_engine_DocBlocks = [
-  {
-    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
+import{registerDocBlocks as b}from"@contractspec/lib.contracts-spec/docs";var d=[{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.
 
@@ -89,10 +78,4 @@ const result = engine.apply({
 
 
 
-`
-  }
-];
-registerDocBlocks(personalization_overlay_engine_DocBlocks);
-export {
-  personalization_overlay_engine_DocBlocks
-};
+`}];b(d);export{d as personalization_overlay_engine_DocBlocks};

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

@@ -1,15 +1,4 @@
-// src/docs/workflow-composition.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
-var personalization_workflow_composition_DocBlocks = [
-  {
-    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
+import{registerDocBlocks as b}from"@contractspec/lib.contracts-spec/docs";var d=[{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.
 
@@ -61,10 +50,4 @@ workflowRunner.execute(runtimeSpec, ctx);
 - \`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.
-`
-  }
-];
-registerDocBlocks(personalization_workflow_composition_DocBlocks);
-export {
-  personalization_workflow_composition_DocBlocks
-};
+`}];b(d);export{d as personalization_workflow_composition_DocBlocks};