@contractspec/lib.personalization 6.1.0 → 6.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @contractspec/lib.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.
+`@contractspec/lib.personalization` tracks behavior events, summarizes them into actionable insights, and converts those insights into transparent personalization outputs such as overlay suggestions, preference recommendations, and runtime adaptive-experience decisions. It also defines the shared preference-dimensions model consumed by runtime layers.
 
 Website: https://contractspec.io
 
@@ -14,10 +14,11 @@ or
 
 ## What belongs here
 
-This package currently has two jobs:
+This package currently has three 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.
+- Shared adaptive contracts: `preference-dimensions`, behavior support, behavior signals, and runtime resolution define the generic adaptive-experience model consumed by runtime layers.
+- Practical adoption: curated presets, onboarding recommendation, and safe evolution suggestions help applications offer a better starting point without creating rigid personas.
 
 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.
 
@@ -186,19 +187,354 @@ Add DataView personalization for <screen>.
 ### Preference model contracts
 
 - `PreferenceDimensions`: the shared 7-dimension personalization model.
+- `BehaviorSupportDimensions`: the support-strategy model for helping users act, recover, and review progress.
+- `BehaviorSignalModel`: scoped behavior evidence used to explain adaptation suggestions without profiling users.
+- `ResolvedAdaptiveExperience`: runtime-only result describing what the application should do now.
+- Preset helpers: `PREFERENCE_DIMENSION_PRESETS`, `PREFERENCE_PRESET_DEFINITIONS`, `getPreferencePresetDimensions`, and `createPreferencePresetCatalog`.
+- Behavior support preset helpers: `BEHAVIOR_SUPPORT_PRESETS`, `BEHAVIOR_SUPPORT_PRESET_DEFINITIONS`, and `getBehaviorSupportPresetDimensions`.
+- Onboarding helpers: `recommendPreferencePreset`, `recommendBehaviorSupportPreset`, `recommendAdaptiveExperience`, and related recommendation types.
+- Evolution helpers: `suggestPreferenceEvolution`, `suggestAdaptiveExperienceEvolution`, and related suggestion types.
 - `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.
 
+## Adaptive experience toolkit
+
+Use ContractSpec personalization to give builders a transparent adaptation layer. The package separates how software presents itself from how the system supports user action:
+
+- `PreferenceDimensions` decide how the software adapts as a tool.
+- `BehaviorSupportDimensions` decide how the system supports human action.
+- `BehaviorSignalModel` records what evidence is strong enough to suggest a change.
+- `ResolvedAdaptiveExperience` describes what should happen now, at runtime.
+
+This is not a profiling engine, user-personality classifier, behavioral manipulation toolkit, analytics platform, or authorization system. It is a small set of contracts for saying: "The system noticed this scoped pattern and can adjust the experience in a way the user can inspect and override."
+
+### Interaction preferences
+
+`PreferenceDimensions` describes how a person wants to experience an application across seven independent dimensions:
+
+- `guidance`: how much help the interface offers.
+- `density`: how much information appears at once.
+- `dataDepth`: whether the app starts from summaries, details, or exhaustive evidence.
+- `control`: how much configuration and direct manipulation is exposed.
+- `media`: whether the experience prefers text, visuals, voice, or a hybrid.
+- `pace`: whether interactions should feel deliberate, balanced, or rapid.
+- `narrative`: whether content starts top-down, bottom-up, or adapts by context.
+
+These dimensions are software interaction preferences, not behavior labels and not permissions. `control: "full"` never grants access to features a user is not authorized to use.
+
+### Behavior support dimensions
+
+`BehaviorSupportDimensions` describes how the system supports action, momentum, recovery, and decision-making:
+
+- `attention`: how the system helps the user notice what matters next.
+- `activation`: how the system helps the user start.
+- `actionScale`: how large the next useful action should be.
+- `rhythm`: how work fits time, energy, urgency, or changing context.
+- `environment`: what surrounding structure makes action easier.
+- `challenge`: how much stretch or pressure is appropriate.
+- `meaningFrame`: what makes the action feel worthwhile.
+- `permission`: what helps the user begin, reduce, pause, or renegotiate.
+- `selfAuthority`: how the system supports confidence, composure, structure, and follow-through.
+- `accountability`: how much external structure or review the user wants.
+- `recovery`: what should happen after skipped actions, misses, contradictions, or failed attempts.
+- `reflection`: how much learning or review should happen after action.
+
+This layer is support strategy, not identity. Use language such as "start support", "smaller first step", "repair first", "private review", or "brief reflection". Avoid moral, clinical, or manipulative labels such as "lazy", "avoidant", "low motivation", "approval-seeking", "low-value user", or "manipulable user".
+
+### Presets are starting points
+
+The package exports a small interaction preset catalog that application builders can ship directly:
+
+- `balanced`: safe default for general use.
+- `guideMe`: slower, guided onboarding for new or uncertain users.
+- `summaryFirst`: compact, fast, dashboard-style usage.
+- `deepAnalyst`: data-rich, evidence-first investigation mode.
+- `builder`: fast, configurable mode for creating and adjusting workflows.
+- `opsWarRoom`: dense, visual, rapid mode for live operational surfaces.
+- `auditReview`: deliberate, traceable, detail-heavy review mode.
+- `minimalFocus`: low-noise, focused, simple experience.
+
+Presets are not identities. Use labels such as "Summary-first" or "Minimal focus", not labels such as "manager mode" or "junior user".
+
+```ts
+import {
+  getPreferencePresetDimensions,
+  PREFERENCE_PRESET_DEFINITIONS,
+} from "@contractspec/lib.personalization";
+
+const startingPreferences = getPreferencePresetDimensions("summaryFirst");
+const presetIntent = PREFERENCE_PRESET_DEFINITIONS.summaryFirst.intent;
+```
+
+Override or extend the catalog by merging your own named bundles of `PreferenceDimensions`:
+
+```ts
+import {
+  createPreferencePresetCatalog,
+  PREFERENCE_PRESET_DEFINITIONS,
+} from "@contractspec/lib.personalization";
+
+const catalog = createPreferencePresetCatalog({
+  calmReview: {
+    id: "calmReview",
+    label: "Calm review",
+    intent: "A slower review flow with fewer visual interruptions.",
+    dimensions: {
+      ...PREFERENCE_PRESET_DEFINITIONS.auditReview.dimensions,
+      media: "text",
+      pace: "deliberate",
+    },
+  },
+});
+```
+
+Behavior support presets are also editable starting points, not user types:
+
+- `steadyMomentum`: consistent progress with moderate support.
+- `activationFirst`: reduce start friction and help users begin.
+- `permissionFirst`: make smaller starts, pauses, or renegotiation easy.
+- `deepWorkBuilder`: protect focus, mastery, and intentional work.
+- `recoveryFirst`: help users resume after misses or interruptions.
+- `identityBuilder`: connect action to user-defined values or commitments.
+- `selfAuthorityBuilder`: build confidence, composure, structure, and follow-through.
+- `socialMomentum`: support shared rhythm or review when explicitly wanted.
+- `deadlineSprint`: support short-term urgency and focused execution.
+- `minimalNudge`: keep support low-noise with minimal intervention.
+
+Good UI wording: "Suggested support style: Recovery-first." Bad UI wording: "You are a recovery-first user."
+
+### Onboarding recommendation
+
+Recommend first settings from intent and product questions, not role stereotypes. Ask simple questions such as:
+
+- What kind of guidance do you prefer?
+- Do you prefer summaries or details?
+- Do you prefer simple controls or advanced controls?
+- What helps you start?
+- What action size feels easiest to trust?
+- What should happen when something is missed?
+- Do you want private progress, self-review, or shared review?
+- What makes progress meaningful?
+
+```ts
+import {
+  getPreferencePresetDimensions,
+  getBehaviorSupportPresetDimensions,
+  recommendAdaptiveExperience,
+} from "@contractspec/lib.personalization";
+
+const recommendation = recommendAdaptiveExperience({
+  interaction: {
+    primaryIntent: "reviewing",
+    detailPreference: "evidence",
+    controlPreference: "advanced",
+    role: "Manager", // recorded for context, not used for scoring
+  },
+  behaviorSupport: {
+    startSupport: "guided",
+    actionSize: "small",
+    recoveryPreference: "repair",
+  },
+});
+
+const preferences = getPreferencePresetDimensions(
+  recommendation.selectedInteractionPreset
+);
+const behaviorSupport = getBehaviorSupportPresetDimensions(
+  recommendation.selectedBehaviorSupportPreset
+);
+
+console.log(recommendation.reasons);
+console.log(recommendation.alternativeInteractionPresets);
+console.log(recommendation.alternativeBehaviorSupportPresets);
+```
+
+The recommendation returns selected interaction and behavior support presets, confidence, human-readable reasons, alternatives, and editable dimension lists. Role text may be recorded as context, but it does not score presets because a job title should not decide the experience.
+
+### Behavior signals are evidence
+
+`BehaviorSignalModel` records observations that may support an adaptation. A signal is not a conclusion about the user.
+
+Safe examples:
+
+- user repeatedly switches one table to a more detailed view
+- user completes smaller actions more often than large ones
+- user skips long reflections but completes short ones
+- user dismisses social/accountability prompts
+- user uses advanced controls often
+- user repeatedly chooses repair over reset
+
+Unsafe interpretations:
+
+- user is lazy
+- user lacks discipline
+- user wants to be controlled
+- user is unreliable
+- user has a psychological condition
+- user is low-performing
+
+```ts
+import { createBehaviorSignalModel } from "@contractspec/lib.personalization";
+
+const signal = createBehaviorSignalModel({
+  id: "brief-reflection-pattern",
+  kind: "repeated_pattern",
+  summary: "User completes brief reflections more often than long reflections.",
+  evidence: {
+    repeatedPattern: "Brief reflections completed in three sessions.",
+    timeWindow: { start: "2026-04-01T00:00:00Z" },
+    scope: { level: "workflow", id: "review" },
+    confidence: "high",
+    source: "system-observation",
+    userFeedback: "not-asked",
+    safetyLevel: "safe",
+    observations: [
+      "Completed brief reflection in session 1.",
+      "Completed brief reflection in session 2.",
+      "Completed brief reflection in session 3.",
+    ],
+    suggestedAdaptation: {
+      id: "brief-reflection-default",
+      label: "Use brief reflection",
+      description: "Use brief reflection by default for this workflow.",
+      target: "behaviorSupport",
+      dimension: "reflection",
+      value: "brief",
+      scope: { level: "workflow", id: "review" },
+      impact: "low",
+    },
+  },
+});
+```
+
+The helper rejects common unsafe labels so tests and logs stay observation-oriented.
+
+### Runtime resolution
+
+`ResolvedAdaptiveExperience` combines preferences, behavior support, signals, current context, surface, intent, product constraints, permissions, policies, and explicit overrides. It answers: "What should the application do now?"
+
+```ts
+import {
+  resolveAdaptiveExperience,
+  PREFERENCE_DIMENSION_PRESETS,
+  BEHAVIOR_SUPPORT_PRESETS,
+} from "@contractspec/lib.personalization";
+
+const resolved = resolveAdaptiveExperience({
+  preferences: PREFERENCE_DIMENSION_PRESETS.balanced,
+  behaviorSupport: BEHAVIOR_SUPPORT_PRESETS.steadyMomentum,
+  behaviorSignals: [signal],
+  context: { workflowId: "review" },
+  permissions: [
+    {
+      key: "advanced-controls",
+      allowed: false,
+      reason: "Advanced controls are not permitted.",
+    },
+  ],
+});
+```
+
+The resolved result is `runtime-only`. Do not persist it as a hidden user profile. Persist explicit choices, accepted suggestions, or scoped preference records instead.
+
+### Preference evolution
+
+Evolution suggestions are deterministic and explainable. They do not mutate preferences by themselves.
+
+Start with surface-level suggestions, then promote to workflow, workspace, or user scope only when behavior is consistent across multiple sessions and surfaces. Explicit user choices beat inferred behavior. Changes that affect `control`, `dataDepth`, `challenge`, `accountability`, or social exposure require confirmation because they can change perceived power, data exposure, pressure, or visibility.
+
+```ts
+import { suggestAdaptiveExperienceEvolution } from "@contractspec/lib.personalization";
+
+const result = suggestAdaptiveExperienceEvolution({
+  currentPreferences: preferences,
+  currentBehaviorSupport: behaviorSupport,
+  preferenceObservations: [
+    {
+      dimension: "density",
+      value: "detailed",
+      signal: "setting_changed",
+      surfaceId: "orders",
+      sessionId: "s1",
+      reason: "Changed orders density to detailed.",
+    },
+    {
+      dimension: "density",
+      value: "detailed",
+      signal: "setting_changed",
+      surfaceId: "orders",
+      sessionId: "s2",
+    },
+    {
+      dimension: "density",
+      value: "detailed",
+      signal: "setting_changed",
+      surfaceId: "orders",
+      sessionId: "s3",
+    },
+  ],
+  behaviorSignals: [signal],
+});
+
+console.log(result.preferenceSuggestions);
+console.log(result.behaviorSupportSuggestions);
+```
+
+Recommended UI wording:
+
+- "You often switch this table to detailed mode. Remember detailed mode here?"
+- "You complete more actions when they start small. Use smaller first steps for this workflow?"
+- "You often choose repair instead of reset. Suggest repair first after missed actions?"
+- "You often skip long reflections. Use brief reflection by default?"
+- "You regularly dismiss shared review prompts. Keep accountability private by default?"
+
+Avoid wording that implies an identity profile or hidden optimization.
+
+### Scope and examples
+
+Adapt narrowly first. If a user repeatedly changes one table to detailed mode, do not make every product screen detailed. If a user repeatedly asks for smaller actions in one workflow, do not shrink every task globally. Promote from surface to workflow, workspace, or user scope only with stronger evidence and confirmation.
+
+Generic integration examples:
+
+- Adaptive dashboard: compact UI with detailed mode remembered for one table after repeated explicit switches.
+- Guided onboarding: walkthrough interaction preset with activation-first support for the first setup flow.
+- Review workflow: detailed audit mode with brief reflection and neutral recovery language.
+- Focus workflow: minimal UI with protected focus blocks and self-review.
+- Recovery after skipped action: suggest repair first, not shame or reset by default.
+- Compact expert mode with gentle support: advanced controls stay visible, but first actions remain small and reversible.
+- Detailed audit mode with minimal nudging: exhaustive data remains available while behavior support stays private and low-noise.
+
+### Safety boundaries
+
+- Preferences do not grant authorization.
+- Behavior support does not replace business rules or permissions.
+- Behavior observations are evidence, not psychological explanations.
+- Resolved adaptive experiences are runtime outputs, not stored identities.
+- No black-box machine learning is used.
+- High-impact changes require confirmation.
+- Suggestions are reversible and scoped.
+- Applications should log or display what changed, why it changed, what evidence supported it, whether it was automatic or suggested, and how to undo or disable adaptation.
+- Adaptation should never silently increase pressure, accountability, challenge, or social exposure.
+
 ## Public entrypoints
 
 The root barrel at `src/index.ts` re-exports public symbols from:
 
 - `adapter`
+- `adaptive-evolution`
+- `adaptive-experience`
+- `adaptive-onboarding`
 - `analyzer`
+- `behavior-signals`
+- `behavior-support`
 - `data-view-preferences`
 - `preference-dimensions`
+- `preference-evolution`
+- `preference-evolution-types`
+- `preference-onboarding`
+- `preference-presets`
 - `store`
 - `tracker`
 - `types`
@@ -207,13 +543,26 @@ Published subpaths from `package.json`:
 
 - `.`
 - `./adapter`
+- `./adaptive-evolution`
+- `./adaptive-experience`
+- `./adaptive-onboarding`
+- `./adaptive-onboarding-scores`
 - `./analyzer`
+- `./behavior-signals`
+- `./behavior-support`
+- `./behavior-support-preset-definitions`
+- `./behavior-support-presets`
 - `./data-view-preferences`
 - `./docs`
 - `./docs/behavior-tracking.docblock`
 - `./docs/overlay-engine.docblock`
 - `./docs/workflow-composition.docblock`
+- `./personalization.feature`
 - `./preference-dimensions`
+- `./preference-evolution`
+- `./preference-evolution-types`
+- `./preference-onboarding`
+- `./preference-presets`
 - `./store`
 - `./tracker`
 - `./types`
@@ -230,6 +579,7 @@ For application code, prefer `.` or the focused subpaths above. The `./docs*` su
 - `insightsToOverlaySuggestion()` currently emits only `hideField` and `reorderFields` modifications.
 - `layoutPreference` is still inferred from field-count thresholds. Data-view-specific preferred modes are derived from `data_view_interaction` events when those events include a valid collection `viewMode`.
 - `PreferenceDimensions` and related types are contracts. Durable persistence and runtime resolution live elsewhere.
+- Preset recommendation and preference evolution helpers are deterministic utilities. They return explainable data for applications to display, log, confirm, or ignore.
 
 ## When not to use this package
 

package/dist/adaptive-evolution.d.ts

@@ -0,0 +1,40 @@
+import type { BehaviorSignalModel } from './behavior-signals';
+import type { BehaviorSupportDimension, BehaviorSupportDimensions, BehaviorSupportDimensionValue } from './behavior-support';
+import type { PreferenceDimensions } from './preference-dimensions';
+import { type PreferenceEvolutionInput, type PreferenceEvolutionSuggestion } from './preference-evolution';
+export interface AdaptiveExperienceEvolutionInput {
+    currentPreferences: PreferenceDimensions;
+    currentBehaviorSupport: BehaviorSupportDimensions;
+    preferenceObservations?: PreferenceEvolutionInput['observations'];
+    behaviorSignals?: BehaviorSignalModel[];
+    preferredScope?: PreferenceEvolutionInput['preferredScope'];
+}
+export interface BehaviorSupportEvolutionEvidence {
+    signalIds: string[];
+    confidence: 'low' | 'medium' | 'high';
+    observations: string[];
+}
+export interface BehaviorSupportEvolutionSuggestion {
+    id: string;
+    dimension: BehaviorSupportDimension;
+    from: BehaviorSupportDimensionValue;
+    to: BehaviorSupportDimensionValue;
+    scope: 'surface' | 'workflow' | 'workspace' | 'user';
+    requiresConfirmation: boolean;
+    reversible: true;
+    automatic: false;
+    reasons: string[];
+    evidence: BehaviorSupportEvolutionEvidence;
+    patch: Partial<BehaviorSupportDimensions>;
+}
+export interface SuppressedAdaptiveEvolutionSuggestion {
+    id: string;
+    reason: string;
+    signalIds: string[];
+}
+export interface AdaptiveExperienceEvolutionResult {
+    preferenceSuggestions: PreferenceEvolutionSuggestion[];
+    behaviorSupportSuggestions: BehaviorSupportEvolutionSuggestion[];
+    suppressedSuggestions: SuppressedAdaptiveEvolutionSuggestion[];
+}
+export declare function suggestAdaptiveExperienceEvolution({ currentPreferences, currentBehaviorSupport, preferenceObservations, behaviorSignals, preferredScope, }: AdaptiveExperienceEvolutionInput): AdaptiveExperienceEvolutionResult;

package/dist/adaptive-evolution.js

@@ -0,0 +1,2 @@
+// @bun
+var f=new Set(["control","dataDepth"]);function l({current:e,observations:r,preferredScope:n="surface",minimumEvidenceCount:i=3,minimumSessionCount:o=2,minimumSurfaceCountForGlobal:t=2}){let u=new Set(r.filter((c)=>c.explicit===!0).map((c)=>c.dimension));return v(r).filter((c)=>c.value!==e[c.dimension]).filter((c)=>!u.has(c.dimension)||c.explicit).map((c)=>P(c,e,{minimumEvidenceCount:i,minimumSessionCount:o,minimumSurfaceCountForGlobal:t,preferredScope:n})).filter((c)=>c!==void 0)}function v(e){let r=new Map;for(let n of e){if(!S(n.dimension,n.value))continue;let i=[n.dimension,n.value,n.signal,n.explicit?"explicit":"inferred"].join(":"),o=r.get(i);if(o)o.events.push(n);else r.set(i,{dimension:n.dimension,value:n.value,signal:n.signal,explicit:n.explicit===!0,events:[n]})}return Array.from(r.values())}function P(e,r,n){let i=a(e.events,e.signal);if(!e.explicit&&i.count<n.minimumEvidenceCount)return;if(!e.explicit&&i.sessionCount<n.minimumSessionCount)return;let o=d(e,i,n),t=!e.explicit||o!=="surface"||f.has(e.dimension);return{id:["preference-evolution",o,e.dimension,String(e.value)].join(":"),dimension:e.dimension,from:r[e.dimension],to:e.value,scope:o,requiresConfirmation:t,reversible:!0,reasons:C(e,i,o),evidence:i,patch:{[e.dimension]:e.value}}}function d(e,r,n){if(e.explicit)return n.preferredScope;if(n.preferredScope==="surface")return"surface";return r.surfaceCount>=n.minimumSurfaceCountForGlobal?n.preferredScope:"surface"}function a(e,r){let n=new Set(e.map((o)=>o.sessionId).filter(Boolean)),i=new Set(e.map((o)=>o.surfaceId).filter(Boolean));return{signal:r,count:e.reduce((o,t)=>o+(t.count??1),0),sessionCount:n.size||1,surfaceCount:i.size||1,reasons:Array.from(new Set(e.flatMap((o)=>o.reason?[o.reason]:[])))}}function C(e,r,n){let i=[`Observed ${r.count} ${e.signal.replaceAll("_"," ")} signals across ${r.sessionCount} session(s).`,`Suggested as a ${n} preference change, not a hidden global mutation.`];if(e.explicit)i.push("Explicit user choices take priority over inferred behavior.");if(f.has(e.dimension))i.push("This dimension can affect control or data exposure, so confirmation is required.");return[...i,...r.reasons]}var p={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|"};function S(e,r){return p[e].includes(`|${r}|`)}var m=new Set(["challenge","accountability","environment"]);function U({currentPreferences:e,currentBehaviorSupport:r,preferenceObservations:n=[],behaviorSignals:i=[],preferredScope:o="surface"}){let t=l({current:e,observations:n,preferredScope:o}),u=D({currentBehaviorSupport:r,behaviorSignals:i});return{preferenceSuggestions:t,behaviorSupportSuggestions:u.suggestions,suppressedSuggestions:u.suppressed}}function D({currentBehaviorSupport:e,behaviorSignals:r}){let n=[],i=[];for(let o of r??[]){let t=o.evidence.suggestedAdaptation;if(!t||t.target!=="behaviorSupport")continue;let u=t.dimension;if(!M(u)){i.push({id:t.id,reason:"Suggested behavior support dimension is not recognized.",signalIds:[o.id]});continue}if(!g(u,t.value)){i.push({id:t.id,reason:"Suggested behavior support value does not match the dimension.",signalIds:[o.id]});continue}let s=t.value;if(s===e[u])continue;let c=(t.requiresConfirmation??t.impact!=="low")||m.has(u);n.push({id:t.id,dimension:u,from:e[u],to:s,scope:t.scope.level,requiresConfirmation:c,reversible:!0,automatic:!1,reasons:I(o,u),evidence:{signalIds:[o.id],confidence:o.evidence.confidence,observations:o.evidence.observations},patch:{[u]:s}})}return{suggestions:n,suppressed:i}}function I(e,r){let n=["Behavior support changes are suggestions, not silent mutations.","The signal describes scoped observed behavior, not a user identity.","The suggestion is reversible and should be explainable in the UI."];if(m.has(r))n.push("Changes to challenge, accountability, or social exposure require confirmation.");if(e.evidence.userFeedback)n.push(`User feedback state: ${e.evidence.userFeedback}.`);return n}var E={attention:["ambient","next-step","priority","review"],activation:["self-start","prompted","guided-start","ritual"],actionScale:["tiny","small","standard","large"],rhythm:["flexible","steady","time-boxed","deadline-driven"],environment:["open","structured","focused","collaborative"],challenge:["low","moderate","stretch","high"],meaningFrame:["progress","mastery","impact","relief","belonging","agency"],permission:["proceed","start-smaller","pause","renegotiate"],selfAuthority:["light","structured","confidence-building","high-autonomy"],accountability:["private","self-review","peer-review","external-review"],recovery:["resume","repair","reset","renegotiate"],reflection:["none","brief","standard","deep"]};function M(e){return Object.prototype.hasOwnProperty.call(E,e)}function g(e,r){return r?E[e].includes(r):!1}export{U as suggestAdaptiveExperienceEvolution};

package/dist/adaptive-experience-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptive-experience.d.ts

@@ -0,0 +1,74 @@
+import type { AdaptiveScope, BehaviorSignalModel, BehaviorSignalSafetyLevel } from './behavior-signals';
+import type { BehaviorSupportDimensions } from './behavior-support';
+import type { PreferenceDimensions } from './preference-dimensions';
+export interface AdaptiveExperienceContext {
+    surfaceId?: string;
+    workflowId?: string;
+    workspaceId?: string;
+    userIntent?: string;
+    currentSurface?: string;
+    timestamp?: string;
+}
+export interface AdaptiveExperiencePermission {
+    key: string;
+    allowed: boolean;
+    reason?: string;
+}
+export interface AdaptiveExperienceConstraint {
+    id: string;
+    reason: string;
+    target?: string;
+    blocksAdaptation?: boolean;
+}
+export interface AdaptiveExperiencePolicy {
+    id: string;
+    effect: 'allow' | 'constrain' | 'block' | 'require-confirmation';
+    reason: string;
+    target?: string;
+}
+export interface AdaptiveExperienceOverride {
+    target: 'preference' | 'behaviorSupport' | 'runtimeAction';
+    key: string;
+    value: unknown;
+    reason?: string;
+}
+export interface AdaptiveExperienceAction {
+    id: string;
+    kind: 'ui' | 'guidance' | 'next-action' | 'recovery' | 'focus' | 'reflection';
+    scope: AdaptiveScope;
+    description: string;
+    requiresConfirmation: boolean;
+    reversible: boolean;
+    evidenceIds: string[];
+    safetyLevel: BehaviorSignalSafetyLevel;
+}
+export interface SuppressedAdaptiveExperienceAction extends AdaptiveExperienceAction {
+    suppressedReason: string;
+}
+export interface ResolveAdaptiveExperienceInput {
+    preferences: PreferenceDimensions;
+    behaviorSupport: BehaviorSupportDimensions;
+    behaviorSignals?: BehaviorSignalModel[];
+    context?: AdaptiveExperienceContext;
+    permissions?: AdaptiveExperiencePermission[];
+    constraints?: AdaptiveExperienceConstraint[];
+    policies?: AdaptiveExperiencePolicy[];
+    overrides?: AdaptiveExperienceOverride[];
+}
+export interface ResolvedAdaptiveExperience {
+    interaction: PreferenceDimensions;
+    behaviorSupport: BehaviorSupportDimensions;
+    context: AdaptiveExperienceContext;
+    appliedAdaptations: AdaptiveExperienceAction[];
+    suppressedAdaptations: SuppressedAdaptiveExperienceAction[];
+    reasons: string[];
+    evidenceIds: string[];
+    constraints: AdaptiveExperienceConstraint[];
+    permissions: AdaptiveExperiencePermission[];
+    policies: AdaptiveExperiencePolicy[];
+    overrides: AdaptiveExperienceOverride[];
+    persistence: 'runtime-only';
+    canUndo: boolean;
+    userFacingSummary: string;
+}
+export declare function resolveAdaptiveExperience({ preferences, behaviorSupport, behaviorSignals, context, permissions, constraints, policies, overrides, }: ResolveAdaptiveExperienceInput): ResolvedAdaptiveExperience;

package/dist/adaptive-experience.js

@@ -0,0 +1,2 @@
+// @bun
+function y({preferences:e,behaviorSupport:i,behaviorSignals:s=[],context:c={},permissions:a=[],constraints:r=[],policies:p=[],overrides:o=[]}){let d=s.flatMap(g),n=[],u=[];for(let t of d){let v=h(t,p,o),l=E(v,a,r,p,o);if(l)u.push({...v,suppressedReason:l});else n.push(v)}let A=s.map((t)=>t.id),x=b({appliedAdaptations:n,suppressedAdaptations:u,overrides:o});return{interaction:{...e},behaviorSupport:{...i},context:{...c},appliedAdaptations:n,suppressedAdaptations:u,reasons:x,evidenceIds:A,constraints:r.map((t)=>({...t})),permissions:a.map((t)=>({...t})),policies:p.map((t)=>({...t})),overrides:o.map((t)=>({...t})),persistence:"runtime-only",canUndo:!0,userFacingSummary:"This runtime result explains what changed, why it changed, and how it can be undone."}}function g(e){let i=e.evidence.suggestedAdaptation;if(!i)return[];return[{id:i.id,kind:m(i.target,i.dimension),scope:i.scope,description:i.description,requiresConfirmation:(i.requiresConfirmation??i.impact!=="low")||e.evidence.safetyLevel!=="safe",reversible:!0,evidenceIds:[e.id],safetyLevel:e.evidence.safetyLevel}]}function m(e,i){if(e==="preference")return"ui";if(i==="recovery")return"recovery";if(i==="reflection")return"reflection";if(i==="environment")return"focus";if(e==="behaviorSupport")return"next-action";return"guidance"}function E(e,i,s,c,a){let r=a.find((n)=>n.target==="runtimeAction"&&f(e,n.key)&&n.value===!1);if(r)return r.reason??"Explicit override disabled this action.";let p=i.find((n)=>!n.allowed&&e.id.includes(n.key));if(p)return p.reason??"Permission denied.";let o=s.find((n)=>n.blocksAdaptation&&(!n.target||e.id.includes(n.target)));if(o)return o.reason;let d=c.find((n)=>n.effect==="block"&&(!n.target||e.id.includes(n.target)));if(d)return d.reason;return}function h(e,i,s){let c=i.some((r)=>(r.effect==="require-confirmation"||r.effect==="constrain")&&(!r.target||f(e,r.target))),a=s.some((r)=>r.target==="runtimeAction"&&f(e,r.key)&&(r.value==="require-confirmation"||r.value==="confirm"));if(!c&&!a)return e;return{...e,requiresConfirmation:!0}}function f(e,i){return e.id.includes(i)||e.kind===i}function b(e){let i=["Resolved adaptive experience is runtime-only and should not be stored as a hidden user profile.","Permissions, constraints, policy, and explicit overrides bound all adaptation."];if(e.appliedAdaptations.length>0)i.push("Scoped behavior evidence produced explainable runtime actions.");if(e.suppressedAdaptations.length>0)i.push("Some suggested adaptations were suppressed by safety boundaries.");if(e.overrides.length>0)i.push("Explicit overrides were preserved as higher priority context.");return i}export{y as resolveAdaptiveExperience};

package/dist/adaptive-experience.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adaptive-onboarding-scores.d.ts

@@ -0,0 +1,9 @@
+import type { BehaviorSupportOnboardingSignals } from './adaptive-onboarding';
+import { type BehaviorSupportPresetId } from './behavior-support';
+export type BehaviorSupportPresetScores = Record<BehaviorSupportPresetId, number>;
+export declare function scoreBehaviorSupportSignals(signals: BehaviorSupportOnboardingSignals): {
+    scores: BehaviorSupportPresetScores;
+    reasons: string[];
+    signalCount: number;
+};
+export declare function calculateBehaviorRecommendationConfidence(score: number, nextScore: number, signalCount: number): number;

package/dist/adaptive-onboarding-scores.js

@@ -0,0 +1,2 @@
+// @bun
+var s=["steadyMomentum","activationFirst","permissionFirst","deepWorkBuilder","recoveryFirst","identityBuilder","selfAuthorityBuilder","socialMomentum","deadlineSprint","minimalNudge"],a={steadyMomentum:{attention:"next-step",activation:"prompted",actionScale:"standard",rhythm:"steady",environment:"structured",challenge:"moderate",meaningFrame:"progress",permission:"proceed",selfAuthority:"structured",accountability:"self-review",recovery:"resume",reflection:"brief"},activationFirst:{attention:"next-step",activation:"guided-start",actionScale:"small",rhythm:"flexible",environment:"structured",challenge:"low",meaningFrame:"relief",permission:"start-smaller",selfAuthority:"confidence-building",accountability:"private",recovery:"resume",reflection:"brief"},permissionFirst:{attention:"ambient",activation:"prompted",actionScale:"small",rhythm:"flexible",environment:"open",challenge:"low",meaningFrame:"agency",permission:"renegotiate",selfAuthority:"confidence-building",accountability:"private",recovery:"renegotiate",reflection:"brief"},deepWorkBuilder:{attention:"priority",activation:"ritual",actionScale:"standard",rhythm:"time-boxed",environment:"focused",challenge:"stretch",meaningFrame:"mastery",permission:"proceed",selfAuthority:"high-autonomy",accountability:"self-review",recovery:"repair",reflection:"standard"},recoveryFirst:{attention:"next-step",activation:"guided-start",actionScale:"small",rhythm:"flexible",environment:"structured",challenge:"low",meaningFrame:"relief",permission:"renegotiate",selfAuthority:"confidence-building",accountability:"private",recovery:"repair",reflection:"brief"},identityBuilder:{attention:"review",activation:"ritual",actionScale:"standard",rhythm:"steady",environment:"structured",challenge:"moderate",meaningFrame:"agency",permission:"proceed",selfAuthority:"structured",accountability:"self-review",recovery:"repair",reflection:"standard"},selfAuthorityBuilder:{attention:"priority",activation:"prompted",actionScale:"standard",rhythm:"steady",environment:"structured",challenge:"moderate",meaningFrame:"agency",permission:"proceed",selfAuthority:"confidence-building",accountability:"self-review",recovery:"repair",reflection:"standard"},socialMomentum:{attention:"priority",activation:"prompted",actionScale:"standard",rhythm:"steady",environment:"collaborative",challenge:"moderate",meaningFrame:"belonging",permission:"proceed",selfAuthority:"structured",accountability:"peer-review",recovery:"repair",reflection:"brief"},deadlineSprint:{attention:"priority",activation:"prompted",actionScale:"small",rhythm:"deadline-driven",environment:"focused",challenge:"stretch",meaningFrame:"impact",permission:"proceed",selfAuthority:"structured",accountability:"self-review",recovery:"resume",reflection:"brief"},minimalNudge:{attention:"ambient",activation:"self-start",actionScale:"standard",rhythm:"flexible",environment:"open",challenge:"moderate",meaningFrame:"progress",permission:"proceed",selfAuthority:"high-autonomy",accountability:"private",recovery:"resume",reflection:"none"}};function b(e){return{...a[e]}}var u={steadyMomentum:i("steadyMomentum","Steady momentum","Consistent progress with moderate support."),activationFirst:i("activationFirst","Activation-first","Reduces start friction and makes the first useful action easier."),permissionFirst:i("permissionFirst","Permission-first","Helps users start smaller, pause, or renegotiate without friction."),deepWorkBuilder:i("deepWorkBuilder","Deep work builder","Protects focus, mastery, and intentional work."),recoveryFirst:i("recoveryFirst","Recovery-first","Makes repair and resumption easier after misses or interruptions."),identityBuilder:i("identityBuilder","Identity builder","Connects action to user-defined values or commitments."),selfAuthorityBuilder:i("selfAuthorityBuilder","Self-authority builder","Builds confidence, composure, structure, and follow-through."),socialMomentum:i("socialMomentum","Social momentum","Uses shared rhythm, collaboration, or review when explicitly wanted."),deadlineSprint:i("deadlineSprint","Deadline sprint","Supports short-term urgency and focused execution."),minimalNudge:i("minimalNudge","Minimal nudge","Keeps behavior support low-noise with minimal intervention.")};function A(e){let r=u[e];return{...r,dimensions:{...r.dimensions}}}function i(e,r,o){return{id:e,label:r,intent:o,dimensions:a[e]}}function k(e){let r=f(),o=[],t=0,n=(m,p,c)=>{if(r[m]+=p,c)o.push(c)};if(e.startSupport)t+=1,l(e.startSupport,n);if(e.actionSize)t+=1,d(e.actionSize,n);if(e.recoveryPreference)t+=1,y(e.recoveryPreference,n);if(e.accountabilityPreference)t+=1,h(e.accountabilityPreference,n);if(e.rhythmPreference)t+=1,v(e.rhythmPreference,n);if(e.meaningPreference)t+=1,S(e.meaningPreference,n);if(e.reflectionPreference)t+=1,g(e.reflectionPreference,n);if(e.role)o.push("Role text was recorded for context but did not score support presets.");return{scores:r,reasons:o,signalCount:t}}function I(e,r,o){if(o===0)return 0.35;let t=0.45+Math.min(e/(o*4),0.4)+Math.min((e-r)*0.05,0.15);return Math.round(Math.min(t,0.95)*100)/100}function f(){return s.reduce((e,r)=>({...e,[r]:r==="steadyMomentum"?1:0}),{})}function l(e,r){if(e==="self-start")r("minimalNudge",4,"You prefer low-noise starts.");if(e==="prompt")r("steadyMomentum",3,"You prefer a clear prompt to begin.");if(e==="guided")r("activationFirst",4,"You prefer guided start support.");if(e==="ritual")r("deepWorkBuilder",4,"You prefer a repeatable start ritual.")}function d(e,r){if(e==="tiny")r("activationFirst",3,"Tiny first steps feel easier to trust.");if(e==="small")r("permissionFirst",3,"Small first steps feel easier to trust.");if(e==="standard")r("steadyMomentum",2,"Standard next actions fit you.");if(e==="large")r("deepWorkBuilder",2,"You prefer substantial action blocks.")}function y(e,r){if(e==="repair")r("recoveryFirst",5,"Repair should be easy after a miss.");if(e==="renegotiate")r("permissionFirst",4,"Renegotiation should stay available.");if(e==="resume")r("steadyMomentum",2,"You prefer to resume without a reset.");if(e==="reset")r("activationFirst",2,"A clean restart can be useful.")}function h(e,r){if(e==="private")r("minimalNudge",3,"You prefer private progress.");if(e==="self-review")r("selfAuthorityBuilder",3,"You prefer self-review.");if(e==="shared-review")r("socialMomentum",4,"You prefer shared review.")}function v(e,r){if(e==="flexible")r("permissionFirst",2);if(e==="steady")r("steadyMomentum",3);if(e==="focus-block")r("deepWorkBuilder",4);if(e==="deadline")r("deadlineSprint",4)}function S(e,r){if(e==="mastery")r("deepWorkBuilder",3);if(e==="impact")r("deadlineSprint",2);if(e==="relief")r("recoveryFirst",3);if(e==="agency")r("identityBuilder",3);if(e==="progress")r("steadyMomentum",2)}function g(e,r){if(e==="none")r("minimalNudge",3);if(e==="brief")r("steadyMomentum",2);if(e==="standard")r("selfAuthorityBuilder",2);if(e==="deep")r("deepWorkBuilder",3)}export{k as scoreBehaviorSupportSignals,I as calculateBehaviorRecommendationConfidence};

package/dist/adaptive-onboarding.d.ts

@@ -0,0 +1,46 @@
+import type { BehaviorSupportDimension } from './behavior-support';
+import { type BehaviorSupportPresetId } from './behavior-support';
+import type { PreferenceDimensions } from './preference-dimensions';
+import { type PreferenceOnboardingSignals, type PreferencePresetAlternative } from './preference-onboarding';
+import type { PreferencePresetId } from './preference-presets';
+export interface BehaviorSupportOnboardingSignals {
+    startSupport?: 'self-start' | 'prompt' | 'guided' | 'ritual';
+    actionSize?: 'tiny' | 'small' | 'standard' | 'large';
+    recoveryPreference?: 'resume' | 'repair' | 'reset' | 'renegotiate';
+    accountabilityPreference?: 'private' | 'self-review' | 'shared-review';
+    rhythmPreference?: 'flexible' | 'steady' | 'focus-block' | 'deadline';
+    meaningPreference?: 'progress' | 'mastery' | 'impact' | 'relief' | 'agency';
+    reflectionPreference?: 'none' | 'brief' | 'standard' | 'deep';
+    /** Weak context only. Role text must not score behavior support presets. */
+    role?: string;
+}
+export interface BehaviorSupportPresetAlternative {
+    preset: BehaviorSupportPresetId;
+    confidence: number;
+    reason: string;
+}
+export interface BehaviorSupportPresetRecommendation {
+    selectedPreset: BehaviorSupportPresetId;
+    confidence: number;
+    reasons: string[];
+    alternatives: BehaviorSupportPresetAlternative[];
+    editableDimensions: BehaviorSupportDimension[];
+}
+export interface AdaptiveExperienceOnboardingSignals {
+    interaction?: PreferenceOnboardingSignals;
+    behaviorSupport?: BehaviorSupportOnboardingSignals;
+}
+export interface AdaptiveExperienceRecommendation {
+    selectedInteractionPreset: PreferencePresetId;
+    selectedBehaviorSupportPreset: BehaviorSupportPresetId;
+    confidence: number;
+    reasons: string[];
+    alternativeInteractionPresets: PreferencePresetAlternative[];
+    alternativeBehaviorSupportPresets: BehaviorSupportPresetAlternative[];
+    editableDimensions: {
+        interaction: (keyof PreferenceDimensions)[];
+        behaviorSupport: BehaviorSupportDimension[];
+    };
+}
+export declare function recommendAdaptiveExperience(signals: AdaptiveExperienceOnboardingSignals): AdaptiveExperienceRecommendation;
+export declare function recommendBehaviorSupportPreset(signals: BehaviorSupportOnboardingSignals): BehaviorSupportPresetRecommendation;