@contractspec/lib.personalization 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './store';
 export * from './tracker';
 export * from './analyzer';
 export * from './adapter';
+export * from './preference-dimensions';
 import './docs';

package/dist/preference-dimensions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Preference dimensions and bundle preference adapter.
+ * Aligns with specs/contractspec_modules_bundle_spec_2026-03-08 (05_personalization_model.md)
+ * and references/current_specs/01_preference_dimensions.md.
+ *
+ * Surface-runtime and other bundles may consume these types for 7-dimension personalization.
+ */
+/** 7-dimension preference model. Each dimension is independent. */
+export interface PreferenceDimensions {
+    guidance: 'none' | 'hints' | 'tooltips' | 'walkthrough' | 'wizard';
+    density: 'minimal' | 'compact' | 'standard' | 'detailed' | 'dense';
+    dataDepth: 'summary' | 'standard' | 'detailed' | 'exhaustive';
+    control: 'restricted' | 'standard' | 'advanced' | 'full';
+    media: 'text' | 'visual' | 'voice' | 'hybrid';
+    pace: 'deliberate' | 'balanced' | 'rapid';
+    narrative: 'top-down' | 'bottom-up' | 'adaptive';
+}
+/** Scope from which a preference value was resolved. Order: user → workspace-user → bundle → surface → entity → session. */
+export type PreferenceScope = 'user' | 'workspace-user' | 'bundle' | 'surface' | 'entity' | 'session';
+/** Resolved preference profile with source attribution and constraint notes per dimension. */
+export interface ResolvedPreferenceProfile {
+    /** Canonical values after scope merge and constraint resolution. */
+    canonical: PreferenceDimensions;
+    /** Source scope per dimension (which layer provided the value). */
+    sourceByDimension: Partial<Record<keyof PreferenceDimensions, PreferenceScope>>;
+    /** Dimensions that were constrained (requested value not applied); value = reason. */
+    constrained: Partial<Record<keyof PreferenceDimensions, string>>;
+    /** Human-readable notes (e.g. constraint reasons, fallbacks). */
+    notes: string[];
+}
+/** Minimal context for preference resolution. Bundle runtimes pass a broader context (e.g. BundleContext). */
+export interface PreferenceResolutionContext {
+    tenantId: string;
+    workspaceId?: string;
+    actorId?: string;
+    preferences: PreferenceDimensions;
+    capabilities: string[];
+}
+/** Adapter for resolving and persisting preferences in bundle runtimes. */
+export interface BundlePreferenceAdapter {
+    resolve(ctx: PreferenceResolutionContext): Promise<ResolvedPreferenceProfile>;
+    savePreferencePatch(args: {
+        actorId: string;
+        workspaceId?: string;
+        patch: Partial<PreferenceDimensions>;
+        scope: 'user' | 'workspace-user' | 'surface';
+    }): Promise<void>;
+}

package/dist/preference-dimensions.js

@@ -0,0 +1 @@
+// @bun

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.personalization",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
   "keywords": [
     "contractspec",
@@ -32,20 +32,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.bus": "3.3.0",
-    "@contractspec/lib.schema": "3.3.0",
-    "@contractspec/lib.contracts-spec": "3.3.0",
-    "@contractspec/lib.knowledge": "3.3.0",
-    "@contractspec/lib.overlay-engine": "3.3.0",
+    "@contractspec/lib.bus": "3.4.0",
+    "@contractspec/lib.schema": "3.4.0",
+    "@contractspec/lib.contracts-spec": "3.4.0",
+    "@contractspec/lib.knowledge": "3.4.0",
+    "@contractspec/lib.overlay-engine": "3.4.0",
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.3.0",
+    "@contractspec/tool.typescript": "3.4.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.3.0"
+    "@contractspec/tool.bun": "3.4.0"
   },
   "exports": {
     ".": {
@@ -104,6 +104,13 @@
       "browser": "./dist/browser/docs/workflow-composition.docblock.js",
       "default": "./dist/docs/workflow-composition.docblock.js"
     },
+    "./preference-dimensions": {
+      "types": "./dist/preference-dimensions.d.ts",
+      "bun": "./dist/preference-dimensions.js",
+      "node": "./dist/node/preference-dimensions.js",
+      "browser": "./dist/browser/preference-dimensions.js",
+      "default": "./dist/preference-dimensions.js"
+    },
     "./store": {
       "types": "./dist/store.d.ts",
       "bun": "./dist/store.js",
@@ -185,6 +192,13 @@
         "browser": "./dist/browser/docs/workflow-composition.docblock.js",
         "default": "./dist/docs/workflow-composition.docblock.js"
       },
+      "./preference-dimensions": {
+        "types": "./dist/preference-dimensions.d.ts",
+        "bun": "./dist/preference-dimensions.js",
+        "node": "./dist/node/preference-dimensions.js",
+        "browser": "./dist/browser/preference-dimensions.js",
+        "default": "./dist/preference-dimensions.js"
+      },
       "./store": {
         "types": "./dist/store.d.ts",
         "bun": "./dist/store.js",