lib.personalization

@lssm-tech/lib.personalization

@lssm-tech/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

Installation

bun add @lssm-tech/lib.personalization

or

npm install @lssm-tech/lib.personalization

What belongs here

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 adaptive contracts: preference-dimensions, behavior support, behavior signals, and runtime resolution define the generic adaptive-experience model consumed by runtime layers.
• Ontology trace alignment: adaptive events, behavior signals, DataView interactions, and sanitized fine-tuning receipts can carry graph/evidence references without storing raw user context as training data.
• 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.

The root entrypoint keeps ontology trace and sanitized receipt references unambiguous while the existing ./adaptive-events, ./adaptive-experience, and ./ontology-trace subpaths remain compatible. Prefer the focused subpath when only one adaptive concern is needed.

Core workflow

import {
  BehaviorAnalyzer,
  createBehaviorTracker,
  insightsToOverlaySuggestion,
  InMemoryBehaviorStore,
} from "@lssm-tech/lib.personalization";

const store = new InMemoryBehaviorStore();

const tracker = createBehaviorTracker({
  store,
  context: {
    tenantId: "acme",
    userId: "user-123",
    role: "manager",
    roles: ["manager"],
    permissions: ["billing.order.read"],
    policyDecisions: {
      internalNotes: {
        effect: "deny",
        fields: ["internalNotes"],
        missing: { permissions: ["billing.notes.read"] },
      },
    },
  },
  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.

DataView preferences

Use the data-view preference helpers when a collection DataViewSpec should honor preferred list/grid/table mode, density, or data depth without coupling the design-system renderer to personalization:

import { DataViewRenderer } from "@lssm-tech/lib.design-system";
import { resolveDataViewPreferences } from "@lssm-tech/lib.personalization/data-view-preferences";

const resolved = resolveDataViewPreferences({
  spec: AccountsDataView,
  preferences: profile.canonical,
  insights,
  record: savedDataViewPreference,
});

<DataViewRenderer
  spec={AccountsDataView}
  items={rows}
  defaultViewMode={resolved.viewMode}
  defaultDensity={resolved.density}
  defaultDataDepth={resolved.dataDepth}
/>;

The helper returns plain data and never imports React or the design-system package. Stored data-view preference records win over behavior insights, preference dimensions, and authored contract defaults. Disallowed inferred view modes are ignored so the renderer only receives modes allowed by the spec.

Private projection cache

createPrivateProjectionCache<T>() holds private rows, drafts and citations for one exact server authority (tenant, workspace, subject, actor, session, grant and entitlement revisions). Call observeAuthority(next) before rendering a context: any change purges every entry and notifies onInvalidate listeners, and writes produced under an older scope are refused. Attach privateProjectionCacheIdentityBuffer(identity, cache) to PersonalizationIdentityLifecycle so sign-out and account or tenant switches purge it too. It is presentation state only; servers still authorize every read and command.

Adaptive shell projection

Utiliser @lssm-tech/lib.personalization/adaptive-shell when a product shell needs to translate the existing seven preference dimensions into plain layout, navigation, density, data-depth, and control hints. The projection is runtime-only, has no persistence store, and accepts RoleMorph/policy/workspace safety boundaries so preferences can tune presentation without granting hidden routes, restricted evidence, or actions.

import { resolveAdaptiveShellProjection } from "@lssm-tech/lib.personalization/adaptive-shell";

const shell = resolveAdaptiveShellProjection({
  resolvedExperience,
  safetyBoundaries: [
    {
      id: "policy:auditor-read-only",
      target: "actions",
      effect: "read-only",
      reason: "Auditor shell actions stay read-only.",
    },
  ],
});

console.log(shell.navigation, shell.layoutVariant, shell.control);

Every applied or suppressed shell adaptation carries a reason, evidence IDs, ontology refs, and a safety level. Use createAdaptiveShellRuntimeActionEvents() to emit these records through the existing adaptive runtime-action event channel.

For hosts that already receive the narrower RoleMorph presentation hint, use adaptRoleMorphPresentationToPreferences() from ./rolemorph-adapter. It maps supported RoleMorph values into all seven canonical preference dimensions, falls back to authored defaults for missing or unknown values, reports rejected and not-applicable inputs, and returns a presentation-only projection that can never grant authority.

Record renderer interactions with the behavior tracker so later analysis can derive scoped preferred modes:

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  dataViewVersion: AccountsDataView.meta.version,
  action: "view_mode_changed",
  viewMode: "grid",
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: "data_depth_changed",
  dataDepth: "detailed",
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: "selection_changed",
  selectedCount: 3,
  selectionScope: "multiple",
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: "action_invoked",
  actionKey: "accounts.archive",
  actionPlacement: "selection-toolbar",
  actionIntent: "destructive",
});

selection_changed records only the selection count and scope, and action_invoked only the action key, placement and intent. The tracker copies declared input fields into the event, so row ids or row data passed alongside an interaction never reach the behavior store.

Agent prompt for a DataView preference integration:

Add DataView personalization for <screen>.

- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
- Apply resolved values to DataViewRenderer as default or controlled props.
- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, page_changed, selection_changed (selectedCount and selectionScope only) and action_invoked (actionKey, actionPlacement, actionIntent) actions with trackDataViewInteraction. Never pass row ids.
- Persist only the dimensions enabled by view.collection.personalization.persist.
- Ignore behavior-derived modes not allowed by view.collection.viewModes.allowedModes.
- Keep @lssm-tech/lib.personalization free of React and design-system imports.

Adaptive application integration

Applications should keep product-specific rules in their own packages and reuse the ContractSpec adaptive foundation for the generic wiring:

• Utiliser @lssm-tech/lib.personalization for low-level contracts, event builders, emitters, behavior signals, and runtime adaptive resolution.
• Utiliser @lssm-tech/lib.presentation-runtime-core/adaptive-experience to map ResolvedAdaptiveExperience into platform-neutral presentation defaults.
• Utiliser @lssm-tech/lib.presentation-runtime-react/useAdaptiveDataView to resolve DataView defaults and translate manual renderer changes into data_view_interaction events.
• Utiliser @lssm-tech/lib.contracts-runtime-client-react/adaptive-form to derive form guidance, density, recovery, and reflection hints from the same runtime adaptive result.

DataViewRenderer and DataTableToolbar remain generic design-system components. They accept plain adaptive/default props and generic interaction callbacks, but they do not import personalization or store behavior data.

import { DataViewRenderer } from "@lssm-tech/lib.design-system";
import { useAdaptiveDataView } from "@lssm-tech/lib.presentation-runtime-react/useAdaptiveDataView";

const adaptive = useAdaptiveDataView({
  spec: AccountsDataView,
  preferences,
  behaviorSupport,
  behaviorSignals,
  behaviorEventBase: {
    tenantId,
    userId,
  },
  onBehaviorEvent: (event) => tracker.trackDataViewInteraction(event),
});

<DataViewRenderer
  spec={AccountsDataView}
  items={rows}
  {...adaptive.dataViewRendererProps}
/>;

Recommended application layering:

• Backend: persist explicit preference records, accepted suggestions, and behavior events. Do not persist ResolvedAdaptiveExperience as a hidden user identity.
• Runtime adapter: combine product policy, permissions, current context, preferences, behavior support, and signals into a resolved runtime result.
• Design-system surface: consume plain props, emit generic interaction callbacks, and let the runtime adapter translate them into behavior evidence.
• Application package: add only product-specific wording, policy, permissions, persistence, and workflow decisions.

Ontology refs and sanitized fine-tuning receipts

Adaptive traces can reference the canonical Company Work Graph by ID while remaining payload-safe:

import {
  createSanitizedAdaptiveFineTuningReceipt,
  resolveAdaptiveExperience,
} from "@lssm-tech/lib.personalization";

const resolved = resolveAdaptiveExperience({
  preferences,
  behaviorSupport,
  behaviorSignals,
  context: {
    ontologyRefs: {
      graphId: "company-work-graph",
      nodes: [{ id: "surface:approval-panel", domain: "surface" }],
      evidence: [{ id: "receipt:audit-1", kind: "auditReceipt" }],
    },
  },
  trace: { traceId: "trace-1", trainingJobId: "train-1" },
});

const receipt = createSanitizedAdaptiveFineTuningReceipt({
  id: "receipt:train-1",
  createdAt: "2026-05-17T00:00:00Z",
  trace: resolved.trace,
  ontologyRefs: resolved.ontologyRefs,
  policy: {
    policyDecisionRef: "policy:allow-sanitized-training",
    consentRef: "consent:training-1",
    authorityScopeRef: "authority:workspace",
    exportAllowed: true,
    trainingAllowed: true,
    reason: "Only redacted graph/evidence refs and trace IDs are exported.",
  },
  redaction: {
    status: "redacted",
    redactionDecisionId: "redaction:1",
    excludedFields: ["metadata", "context.userIntent"],
  },
  verification: {
    consent: {
      ref: "consent:training-1",
      status: "granted",
      scopes: ["export", "training"],
      grantedAt: "2026-05-16T00:00:00Z",
      expiresAt: "2026-06-16T00:00:00Z",
    },
    policy: {
      decisionRef: "policy:allow-sanitized-training",
      effect: "allow",
      authorityScopeRef: "authority:workspace",
      evaluatedAt: "2026-05-17T00:00:00Z",
    },
    redaction: {
      decisionId: "redaction:1",
      executedAt: "2026-05-17T00:00:00Z",
      verified: true,
      rawPayloadExcluded: true,
    },
    evidenceDigest: "sha256:0123456789abcdef",
  },
});

Receipt construction fails closed unless consent is granted, unexpired, and scoped to export and training; the policy and authority refs match an allow decision; redaction was executed and verified; raw payloads are excluded; and the evidence has a SHA-256 integrity digest. Receipts contain refs and explicit prohibited conclusions, never raw metadata, user intent, or hidden profiles.

Autonomous Work Order traces use the same rule: adaptive events and behavior signals may identify the work order, surface DataView/page, RoleMorph decision, evidence receipt, policy decision, and redaction receipt by ref. They must not store raw user intent, hidden profile claims, or sensitive payloads as training data. Fine-tuning receipts export only sanitized trace IDs, ontology refs, policy/redaction refs, and prohibited-conclusion metadata.

API map

Main runtime APIs

• BehaviorStore: persistence boundary for recording, querying, and summarizing BehaviorEvent Les données.
• 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.
• Authorization context: events may carry roles, permissions, and policy decision summaries so analyzers can suppress denied fields/actions without granting access.
• insightsToOverlaySuggestion: turns analysis output into an overlay-engine OverlaySpec.
• insightsToWorkflowAdaptations: turns workflow bottlenecks into lightweight adaptation notes.

Core data contracts

• BehaviorEvent: discriminated union with four event kinds: field_access, feature_usage, workflow_step, and data_view_interaction.
• 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. When authorization decisions are supplied, denied fields/actions are surfaced for suppression and are not promoted in overlay reorder suggestions.
• 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.
• DataView preference helpers: resolveDataViewPreferences, DataViewPreferenceRecord, DataViewPreferencePatch, and mapping helpers for density and view-mode patches.
• Adaptive integration helpers: AdaptiveExperienceEmitter, adaptive event builders, resolveAdaptiveDataViewState, createDataViewInteractionEvent, resolveAdaptiveShellProjection, createAdaptiveShellRuntimeActionEvents, ontology trace refs, and sanitized fine-tuning receipt builders.

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.
• Adoption helpers: adaptive templates, UI-agnostic onboarding flows, explanation templates, risk helpers, recipes, scenarios, and migration paths.
• 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.
• PREFERENCE_DIMENSION_VALUES: the allowed values of each dimension in scale order (menu/radio builders and validation share it).
• createPreferenceDimensionsStore(defaults) and createUsePreferenceDimensions({ dimensions, fine, serverSnapshot }, React) (./preference-dimensions-store): subscribable 7-dimension client store and a React-injected hook combining it with the RichReference fine-layer store. Hosts own the defaults, singleton instances and server hydration. Call replace(snapshot) instead of hydrate(snapshot) when the identity or workspace changes, so dimensions set in the previous scope cannot leak.

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 "skill level".

import {
  getPreferencePresetDimensions,
  PREFERENCE_PRESET_DEFINITIONS,
} from "@lssm-tech/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:

import {
  createPreferencePresetCatalog,
  PREFERENCE_PRESET_DEFINITIONS,
} from "@lssm-tech/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."

Templates

Adaptive experience templates combine an interaction preset, behavior support preset, onboarding path, evolution policy, recommended scopes, safety notes, explanation copy, and generic product intent.

Templates are starting points for builders. They are not user identities, not permanent classifications, and not product domains.

Available templates:

• balancedAdaptive: safe default for most applications.
• guidedFirstRun: more guidance, smaller first actions, and safe first-run defaults.
• expertOperator: compact UI, faster pace, more control, and fewer interruptions when explicitly wanted.
• summaryDecision: summary-first dashboards, overviews, triage, and decision surfaces.
• deepReview: detailed, deliberate, evidence-heavy review workflows.
• focusExecution: action-oriented workflows where start, focus, and recovery matter.
• recoverySupport: neutral repair-first defaults after missed steps or interruptions.
• collaborativeMomentum: shared rhythm and review support with consent boundaries.
• minimalAssist: low-noise adaptation with minimal intervention.
• learningBuilder: guided capability growth and mastery support.

import {
  getAdaptiveExperienceTemplate,
  recommendAdaptiveTemplate,
} from "@lssm-tech/lib.personalization/adaptive-templates";

const template = getAdaptiveExperienceTemplate("guidedFirstRun");

const recommendation = recommendAdaptiveTemplate({
  selectedInteractionPreset: "guideMe",
  selectedBehaviorSupportPreset: "activationFirst",
});

console.log(template.productIntent);
console.log(recommendation.reasons);

Template categories help builders browse defaults by product intent: general, onboarding, expert, decision, review, execution, recovery, collaboration, minimal, and learning. Each category describes when to use it, when not to use it, the experience it creates, and the safety concerns that matter.

UI-agnostic onboarding flows

The package exports onboarding definitions that applications can render in any UI. They contain flow IDs, titles, descriptions, recommended templates, human-readable questions, options, answer mappings, skip behavior, fallback behavior, and result summaries.

Available flows:

• quickStartAdaptive: short flow with a few questions for most apps.
• fullAdaptiveSetup: longer setup when adaptation matters deeply.
• interactionOnlySetup: configures only PreferenceDimensions.
• behaviorSupportSetup: configures only BehaviorSupportDimensions.
• expertSetup: lets advanced users inspect and directly select dimensions.
• progressiveSetup: starts from a template and asks questions when confidence is low.

import {
  ADAPTIVE_ONBOARDING_FLOWS,
  ADAPTIVE_ONBOARDING_QUESTIONS,
  resolveAdaptiveOnboardingRecommendation,
} from "@lssm-tech/lib.personalization/adaptive-onboarding-flows";

const flow = ADAPTIVE_ONBOARDING_FLOWS.quickStartAdaptive;
const questions = flow.questionIds.map(
  (id) => ADAPTIVE_ONBOARDING_QUESTIONS[id]
);

const result = resolveAdaptiveOnboardingRecommendation("quickStartAdaptive", {
  guidancePreference: "walkthrough",
  dataDepthPreference: "standard",
  actionScalePreference: "small",
  recoveryPreference: "repair",
});

console.log(result.selectedAdaptiveTemplate);
console.log(result.dimensionsInferredFromAnswers);
console.log(result.dimensionsUsingFallbackDefaults);

The recommendation result includes the selected interaction preset, behavior support preset, adaptive template, confidence, reasons, alternative templates, inferred dimensions, explicitly selected dimensions, fallback dimensions, safety notes, and a suggested next step.

Skipped onboarding uses safe defaults with low confidence. Role text can be passed for context, but role alone does not determine a template.

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?

import {
  getPreferencePresetDimensions,
  getBehaviorSupportPresetDimensions,
  recommendAdaptiveExperience,
} from "@lssm-tech/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.

Explanation templates and risk levels

Applications should explain adaptive changes in product language:

• observed pattern
• suggested change
• Périmètre
• reversibility
• confidence when useful
• no shame or moral judgment

import {
  ADAPTIVE_EXPLANATION_TEMPLATES,
  getAdaptiveSuggestionRisk,
  shouldRequireAdaptiveConfirmation,
} from "@lssm-tech/lib.personalization/adaptive-explanations";

const explanation = ADAPTIVE_EXPLANATION_TEMPLATES.find(
  (item) => item.id === "smaller-first-steps"
);

const risk = getAdaptiveSuggestionRisk({
  target: "behaviorSupport",
  dimension: "accountability",
  impact: "medium",
});

const needsConfirmation = shouldRequireAdaptiveConfirmation({
  target: "preference",
  dimension: "control",
  impact: "low",
});

Risk levels:

• low: safe surface-level interaction changes such as view mode, density, or brief hints.
• medium: workflow structure or behavior support changes such as action scale, reflection, or recovery defaults.
• high: changes affecting control, accountability, challenge, social exposure, data depth, or user trust.

Never silently increase social accountability, external accountability, challenge, pressure, data exposure, control level, social visibility, or commitment strength.

Good explanation copy:

• "You often complete smaller actions."
• "This workflow seems to work better with brief reflection."
• "You can change this anytime."
• "This only applies to this surface."
• "This suggestion is based on repeated behavior."

Bad explanation copy:

• "You procrastinate."
• "You failed."
• "You lack discipline."
• "You need more accountability."
• "The system classified you."
• "This is your type."
• "We detected your personality."

Evolution lifecycle

Use this lifecycle for behavior-driven adaptation:

1. Observe scoped behavior signals.
2. Normalize events into safe signal summaries.
3. Compare evidence with current preferences and support dimensions.
4. Detect repeated patterns, deviations, and clusters.
5. Suggest explainable adaptations.
6. Confirm or apply based on risk and scope.
7. Record accept, reject, ignore, or revert feedback.
8. Reduce confidence after rejected suggestions.
9. Let users revert changes.
10. Promote from narrow scope only with stronger evidence.

Rejected suggestions should reduce future confidence. Explicit user choices beat inferred behavior. High-risk suggestions require confirmation.

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

import { createBehaviorSignalModel } from "@lssm-tech/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?"

import {
  resolveAdaptiveExperience,
  PREFERENCE_DIMENSION_PRESETS,
  BEHAVIOR_SUPPORT_PRESETS,
} from "@lssm-tech/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.

import { suggestAdaptiveExperienceEvolution } from "@lssm-tech/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.

Adoption recipes

Use the exported recipes when choosing an integration path:

• Use presets only.
• Use templates without onboarding.
• Use onboarding to choose a template.
• Use behavior signals to suggest changes.
• Use interaction preferences only.
• Use behavior support only.
• Resolve an adaptive experience for a surface.
• Show users why something changed.
• Handle rejected suggestions.
• Promote surface preferences safely.
• Disable behavior adaptation.
• Keep adaptation transparent.

import {
  ADAPTIVE_ADOPTION_RECIPES,
  ADAPTIVE_MIGRATION_PATHS,
  ADAPTIVE_SCENARIO_EXAMPLES,
} from "@lssm-tech/lib.personalization/adaptive-recipes";

const recipe = ADAPTIVE_ADOPTION_RECIPES.find(
  (item) => item.id === "use-onboarding-to-choose-template"
);

console.log(recipe?.integrationFlow);
console.log(ADAPTIVE_SCENARIO_EXAMPLES.map((scenario) => scenario.title));
console.log(ADAPTIVE_MIGRATION_PATHS.map((path) => path.title));

Extension guide

Products can define their own templates, onboarding flows, behavior signals, explanation messages, evolution policies, risk policies, and domain-specific mappings. Keep those extensions outside ContractSpec OSS when they depend on domain language or product policy.

Use ContractSpec defaults as reusable patterns:

• Reuse PreferenceDimensions for how software presents itself.
• Reuse BehaviorSupportDimensions for how the system supports action.
• Reuse BehaviorSignalModel for scoped evidence.
• Reuse ResolvedAdaptiveExperience for runtime decisions.
• Add product-specific templates and mappings in application packages.
• Keep safety rules: explainable, reversible, scoped, and bounded by permissions.

Migration paths

Existing consumers do not need to adopt the full model at once:

1. Continue using only PreferenceDimensions.
2. Add behavior support presets, but no behavior signals.
3. Add onboarding recommendation.
4. Add evolution suggestions.
5. Use full resolved adaptive experience.

The model is additive. Existing users can keep interaction preferences only and add behavior support, onboarding, templates, or evolution when the product needs them.

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-events
• adaptive-evolution
• adaptive-explanations
• adaptive-experience
• adaptive-onboarding
• adaptive-onboarding-flows
• adaptive-recipes
• adaptive-surface
• adaptive-templates
• analyzer
• behavior-signals
• behavior-support
• data-view-preferences
• preference-dimensions
• preference-evolution
• preference-evolution-types
• preference-onboarding
• preference-presets
• store
• support-surface
• tracker
• types

Published subpaths from package.json:

• .
• ./adapter
• ./adaptive-events
• ./adaptive-evolution
• ./adaptive-explanations
• ./adaptive-experience
• ./adaptive-onboarding
• ./adaptive-onboarding-flows
• ./adaptive-onboarding-scores
• ./adaptive-recipes
• ./adaptive-surface
• ./adaptive-templates
• ./analyzer
• ./behavior-signals
• ./behavior-support
• ./behavior-support-preset-definitions
• ./behavior-support-presets
• ./data-view-preferences
• ./durable-lifecycle
• ./durable-preferences
• ./docs
• ./docs/behavior-tracking.docblock
• ./docs/overlay-engine.docblock
• ./docs/workflow-composition.docblock
• ./personalization.feature
• ./preference-dimensions
• ./preference-dimensions-store
• ./preference-evolution
• ./preference-evolution-types
• ./preference-onboarding
• ./preference-presets
• ./privacy
• ./rolemorph-adapter
• ./store
• ./support-surface
• ./tracker
• ./types

For application code, prefer . or the focused subpaths above. The ./docs* subpaths exist for docblock registration and documentation surfaces.

Durable behavior lifecycle

@lssm-tech/lib.personalization/durable-lifecycle defines host boundaries for encrypted behavior persistence without coupling this library to a database or key provider. Collection authorization is exact-bound to event, tenant, subject, type, purpose, active consent, revocation freshness, and retention. Export and deletion use a separate fresh rights decision. Cipher and integrity ports keep key custody and canonical SHA-256 implementation with the host.

The production PersonalOS adapter is @lssm-tech/integration.personal-os-state-postgres/personalization. It implements BehaviorStore plus correction, export, delete, and retention operations with forced RLS and ciphertext-only rows. Unknown, sensitive, or non-scalar metadata is rejected unless it was already sanitized through an explicit allowlist.

This is a behavior-evidence lifecycle, not a durable hidden profile. The separate ./durable-preferences contract persists only explicit subject-owned user, workspace-user, or surface patches. It binds every save/reset to the exact subject, scope, revision, idempotency key, request digest, decision, and fresh request time. Export and deletion require the same fresh rights boundary as behavior evidence. Resolved adaptive experiences, inferred hints, authority, and session state are never durable preference records.

The production preference adapter is @lssm-tech/integration.personal-os-state-postgres/personalization-preferences. It keeps explicit patches in host-encrypted AES-256-GCM documents under forced RLS, maintains monotonic revisions through reset, stores digest-only idempotency receipts, and verifies semantic plus cipher integrity on every read.

Denied personalization export and fine-tuning decisions use the focused ./denial-audit contract. The server adapter at @lssm-tech/integration.personal-os-state-postgres/personalization-denial-audit persists only categorical bindings and canonical SHA-256 digests after an external verifier binds the exact tenant, subject, actor, operation, idempotency key, request digest, reason, decision reference, and timestamp. Attempted payloads and preference values are never denial-audit columns. createAuditedSanitizedFineTuningReceipt remains the compatible denial-audited structural validator. Production issuance uses issueAuditedSanitizedFineTuningReceipt: it derives a domain-separated digest from the exact receipt attempt, requires a trusted verifier to bind that digest and the 64-byte SHA-256 evidence digest, returns the verifier reference and time as an issuance proof, and durably records a derived categorical denial before propagating any fail-closed error. Request or evidence substitutions cannot be resealed with caller-authored proof, and raw attempted payload fields never enter the returned receipt or denial table.

Identity transitions use the additive ./identity-lifecycle contract. Create one PersonalizationIdentityLifecycle per authenticated client session, bind trackers with lifecycleScope, and attach trackers or scoped signal emitters through the exact-binding adapters. Sign-out, account switch, tenant switch, and consent change must choose an explicit drain-or-discard disposition before the next scope becomes active. A failed drain discards all retiring buffers and leaves the lifecycle signed out, preventing another subject, actor, tenant, or consent context from inheriting pending events.

Analyzer qualification uses ./analyzer-evaluation. Hosts provide labeled aggregate summaries grouped only by opaque SHA-256 cohort references. The gate reports unexpected field-hiding suggestions, per-cohort false-positive rates, and maximum disparity; raw profiles, raw cohort labels, unsafe identifiers, and unsupported fields are rejected. Results are always advisory and cannot grant authority. Local passing metrics do not replace longitudinal manual acceptance or production canary evaluation.

Operational semantics and gotchas

• BehaviorStore.query() applies kind-specific filters conjunctively, orders by timestamp with stable insertion ties, then applies limit.
• BehaviorTracker accepts only scalar metadata declared by metadataPolicy; unknown or invalid keys are dropped and sensitive strings are redacted by default.
• Tracker and signal flushes retain failed batches for retry with stable event/idempotency keys. dispose() drains safely and can be retried after a sink failure.
• PersonalizationIdentityLifecycle rejects lookalike scope bindings and semantically invalid transitions; transition failure retires every old buffer and fails closed without a next identity.
• OpenTelemetry metrics and spans receive pseudonymous tenant/user attributes, never raw identifiers.
• Prefer createScopedBehaviorSignalEmitter() with an explicit identity, consent, collection-policy, and retention boundary. The compatibility singleton refuses reconfiguration while scoped events remain pending.
• BehaviorAnalyzer requires the configured field sample floor before producing inactivity evidence. Field-hiding hints are advisory and insightsToOverlaySuggestion() applies them only through confirmedHiddenFields.
• evaluateBehaviorAnalyzer() fails its bounded qualification result when unexpected hiding or cohort disparity exceeds the configured thresholds; it never applies an overlay itself.
• Confirmation-required, review, and high-impact adaptive actions remain in suppressedAdaptations until a host runs an explicit confirmation workflow.
• Authority matching is exact. New integrations should bind permission, constraint, policy, and override identifiers through suggestedAdaptation.authority; legacy string targets remain exact-match adapters.
• 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. The focused durable-preference port and PostgreSQL adapter persist explicit choices; runtime resolution remains separate.
• 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

• Do not use it as a full analytics warehouse or reporting system.
• Do not persist inferred or resolved adaptive state through the explicit durable preference port.
• 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

• @lssm-tech/lib.overlay-engine: runtime for registering, validating, and applying overlays.
• @lssm-tech/lib.surface-runtime: runtime consumer of preference resolution and adaptive surface behavior.
• @lssm-tech/lib.workflow-composer: workflow extension and composition runtime.
• @lssm-tech/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

Rich code and diff preferences

resolveRichCodePreferences maps preference dimensions to governed code/diff presentation defaults: density, data depth, reference verbosity, context lines, and default expansion. The resolver is deterministic and runtime-only; it does not persist hidden profiles or bypass permissions.

Import it from the RichReference subpath introduced in slice S-4:

import { resolveRichCodePreferences } from "@lssm-tech/lib.personalization/rich-reference/preferences";

The legacy ./rich-code-preferences subpath has been removed; the slice S-10 codemod handles the import rename.

RichReference hybrid personalization

@lssm-tech/lib.personalization/rich-reference implements the CoarsePreferencesProvider port owned by @lssm-tech/lib.contracts-spec/rich-reference/ports. The model is two-layer by design:

• Server-coarse (enrichedKinds, density) resolves on the server via createServerCoarsePreferencesResolver, caches results by (tenantId, subjectId, scopeHash) for cross-tenant isolation, and is the only layer that ever appears in agent payloads.
• Client-fine (verbosity, trigger, panelMode, expansion, perKindOptOut) lives in a session-only store created via createRichReferenceClientStore. Mutations stay local until the consumer calls persistPreferences(), which invokes a persistence sink and emits a structured rich-reference.preferences.persist audit log event.

import {
  createServerCoarsePreferencesResolver,
  createRichReferenceClientStore,
  createUseRichReferencePreferences,
  resolveInherited,
  toAgentPayloadPreferences,
} from "@lssm-tech/lib.personalization/rich-reference";

resolveInherited({ defaults, tenant, role, user, context }) applies explicit last-wins precedence per dimension. toAgentPayloadPreferences(prefs) strips fine-layer dimensions before serializing to an agent surface.

Published browser conditions select the emitted browser artifacts alongside existing Node/Bun/type targets. Export keys and source behavior are preserved; this packaging metadata does not activate providers or grant execution authority.

Whole canonical preference contract suppliers

Preserve the complete existing preference, tracking, adaptive-surface, ontology and coarse-provider behavior and every original assertion. Bind the existing RichCodeDisplayPreferences family to its complete canonical PresentationRuntimeCore model and use existing Core, Kernel, Surface and Orchestration suppliers. Do not remove a declared dependency before its entire source and test return is closed.

This is a Source-only compatible ownership proposal. Fresh task-bound adoption, owning production, declarations, affected runtime tests and platform qualification remain required.