@lssm/lib.personalization 0.3.1 → 1.41.1

package/dist/contracts/src/docs/tech/telemetry-ingest.docblock.js

@@ -0,0 +1,122 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.telemetry.ingest`,title:`Telemetry Ingest Endpoint`,summary:`Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).`,kind:`reference`,visibility:`internal`,route:`/docs/tech/telemetry/ingest`,tags:[`telemetry`,`api`,`posthog`,`analytics`],body:`# Telemetry Ingest Endpoint
+
+The ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.
+
+## Endpoint
+
+\`\`\`
+POST /api/telemetry/ingest
+\`\`\`
+
+## Request
+
+\`\`\`json
+{
+  "event": "contractspec.vscode.command_run",
+  "distinct_id": "client-uuid",
+  "properties": {
+    "command": "validate"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+\`\`\`
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| \`x-contractspec-client-id\` | Optional client identifier (used as fallback for distinct_id) |
+| \`Content-Type\` | Must be \`application/json\` |
+
+### Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`event\` | string | Yes | Event name (e.g., \`contractspec.vscode.activated\`) |
+| \`distinct_id\` | string | Yes | Anonymous client identifier |
+| \`properties\` | object | No | Event properties |
+| \`timestamp\` | string | No | ISO 8601 timestamp |
+
+## Response
+
+\`\`\`json
+{
+  "success": true
+}
+\`\`\`
+
+## Configuration
+
+The endpoint requires \`POSTHOG_PROJECT_KEY\` environment variable to be set. If not configured, events are accepted but not forwarded.
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| \`POSTHOG_HOST\` | PostHog host URL | \`https://eu.posthog.com\` |
+| \`POSTHOG_PROJECT_KEY\` | PostHog project API key | (required) |
+
+## Privacy
+
+- No PII is collected or stored
+- \`distinct_id\` is an anonymous client-generated UUID
+- File paths and source code are never included in events
+- Respects VS Code telemetry settings on the client side
+
+## Events
+
+### Extension Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.vscode.activated\` | Extension activated | \`version\` |
+| \`contractspec.vscode.command_run\` | Command executed | \`command\` |
+| \`contractspec.vscode.mcp_call\` | MCP call made | \`endpoint\`, \`tool\` |
+
+### API Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.api.mcp_request\` | MCP request processed | \`endpoint\`, \`method\`, \`success\`, \`duration_ms\` |
+`},{id:`docs.tech.telemetry.hybrid`,title:`Hybrid Telemetry Model`,summary:`How ContractSpec clients choose between direct PostHog and API-routed telemetry.`,kind:`usage`,visibility:`internal`,route:`/docs/tech/telemetry/hybrid`,tags:[`telemetry`,`architecture`,`posthog`],body:`# Hybrid Telemetry Model
+
+ContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.
+
+## Decision Flow
+
+\`\`\`
+Is contractspec.api.baseUrl configured?
+├── Yes → Send via /api/telemetry/ingest
+└── No → Is posthogProjectKey configured?
+    ├── Yes → Send directly to PostHog
+    └── No → Telemetry disabled
+\`\`\`
+
+## Benefits
+
+### Direct PostHog
+- No server dependency
+- Works offline (with batching)
+- Lower latency
+
+### Via API
+- Centralized key management (no client-side keys)
+- Server-side enrichment and validation
+- Rate limiting and abuse prevention
+- Easier migration to other providers
+
+## Recommendation
+
+- **Development**: Use direct PostHog with a dev project key
+- **Production**: Route via API for better governance
+
+## Future: OpenTelemetry
+
+The current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:
+
+\`\`\`typescript
+interface TelemetryClient {
+  send(event: TelemetryEvent): Promise<void>;
+}
+\`\`\`
+
+This allows future migration without changing client code.
+`}]);

package/dist/contracts/src/docs/tech/templates/runtime.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";e([{id:`docs.tech.templates.runtime`,title:`ContractSpec Template Runtime (Phase 9)`,summary:`Phase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.`,kind:`reference`,visibility:`public`,route:`/docs/tech/templates/runtime`,tags:[`tech`,`templates`,`runtime`],body:"## ContractSpec Template Runtime (Phase 9)\n\nPhase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.\n\n### Building Blocks\n\n- **Local database** – `@lssm/lib.runtime-local` wraps `sql.js` (SQLite WASM) and `IndexedDB` so we can seed demo data, run migrations, and persist state between sessions. Tests point the runtime to `node_modules/sql.js/dist` so CI doesn’t need a browser.\n- **Local GraphQL** – `LocalGraphQLClient` wires Apollo Client + SchemaLink to resolvers for tasks, messaging, and i18n recipes. All `/templates`, `/studio`, and `/sandbox` previews use those resolvers so we never call remote APIs during demos.\n- **Template registry + installer** – `.../templates/registry.ts` stores the catalog (todos, messaging, recipes). `TemplateInstaller` can seed the runtime (`install`) or export a base64 snapshot via the new `saveTemplateToStudio` mutation.\n- **TemplateShell** – Shared UI wrapper that creates a `TemplateRuntimeProvider`, shows `LocalDataIndicator`, and (optionally) surfaces the new `SaveToStudioButton`.\n\n### Runtime Flows\n\n1. `/templates` now opens a modal that renders `TemplateShell` for each template. Users can explore without leaving the marketing site.\n2. `/studio` switches to a tabbed mini-app (Projects, Canvas, Specs, Deploy) to showcase Studio surfaces with mock data. Visitors see a **preview** shell, while authenticated users (Better Auth via Sigil) unlock full persistence, versioning, and deployment controls.\n3. `/sandbox` lets visitors pick a template and mode (Playground, Spec Editor, Visual Builder). The console at the bottom streams runtime events for transparency.\n\n### GraphQL Mutations\n\n- `saveTemplateToStudio(input: SaveTemplateInput!): SaveTemplateResult!` writes a placeholder project + spec so that templates installed from the sandbox appear in Studio. The mutation is intentionally simple right now: it records which template was imported, stores metadata, and returns `{ projectId, status: 'QUEUED' }` for the UI.\n- `saveCanvasDraft(input: SaveCanvasDraftInput!): CanvasVersion!` snapshots the current Visual Builder nodes to a draft version tied to a canvas overlay. Inputs include `canvasId`, arbitrary `nodes` JSON, and an optional `label`. The resolver enforces org/org access before calling `CanvasVersionManager`.\n- `deployCanvasVersion(input: DeployCanvasVersionInput!): CanvasVersion!` promotes a previously saved draft (`versionId`) to the deployed state. The returned object includes `status`, `nodes`, `createdAt`, and `createdBy` for UI timelines.\n- `undoCanvasVersion(input: UndoCanvasInput!): CanvasVersion` rewinds the visual builder to the prior snapshot (returns `null` when history is empty) so Studio’s toolbar can surface “Undo” without shelling out to local storage.\n\n### Studio GraphQL endpoint\n\n- The landing app exposes the Studio schema at `/api/studio/graphql` via Yoga so React Query hooks (`useStudioProjects`, `useCreateStudioProject`, `useDeployStudioProject`, etc.) can talk to the bundle without spinning up a separate server.\n\n### Spec Editor typing\n\n- Studio’s spec editor now preloads Monaco with ambient declarations for `@lssm/lib.contracts` and `zod`, so snippets receive autocomplete and inline errors even before the spec ships to the backend. The helper lives in `presentation/components/studio/organisms/monaco-spec-types.ts` and registers the extra libs once per browser session via `monaco.languages.typescript.typescriptDefaults.addExtraLib`.\n- Compiler options are aligned with our frontend toolchain (ES2020 + React JSX) which means drafts written in the editor behave like the compiled artifacts that flow through Studio pipelines.\n\n### Spec templates\n\n- Selecting a spec type now injects a ready-to-edit scaffold (capability, workflow, policy, dataview, component) so authors start from a canonical layout instead of a blank file. Templates live alongside `SpecEditor.tsx`, and we only overwrite the content when the previous value is empty or when the author explicitly switches types via the dropdown.\n\n### Spec preview\n\n- The validation side panel now embeds a `SpecPreview` widget that shows validation errors alongside transport artifacts (GraphQL schema, REST endpoints, component summaries) once a preview run completes. Tabs let authors toggle between “Validation” and “Artifacts,” mirroring the UX described in the Studio plan.\n\n### Testing\n\n- `src/templates/__tests__/runtime.test.ts` covers todos CRUD, messaging delivery, and recipe locale switching through the local GraphQL API.\n- Studio infrastructure tests live in `src/__tests__/e2e/project-lifecycle.test.ts` and continue to exercise project creation + deploy flows.\n\n### Next Steps\n\nFuture templates can register their React components via `registerTemplateComponents(templateId, components)` so TemplateShell can render them automatically. When new templates are added, remember to:\n\n1. Update the registry entry (schema + tags).\n2. Register components inside `presentation/components/templates`.\n3. Document the template under `docs/templates/`.\n\n\n\n\n\n"}]);

package/dist/contracts/src/docs/tech/vscode-extension.docblock.js

@@ -0,0 +1,68 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.vscode.extension`,title:`ContractSpec VS Code Extension`,summary:`VS Code extension for spec-first development with validation, scaffolding, and MCP integration.`,kind:`reference`,visibility:`public`,route:`/docs/tech/vscode/extension`,tags:[`vscode`,`extension`,`tooling`,`dx`],body:`# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@lssm/module.contractspec-workspace\` for pure analysis + templates
+- \`@lssm/bundle.contractspec-workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`},{id:`docs.tech.vscode.snippets`,title:`ContractSpec Snippets`,summary:`Code snippets for common ContractSpec patterns in VS Code.`,kind:`reference`,visibility:`public`,route:`/docs/tech/vscode/snippets`,tags:[`vscode`,`snippets`,`dx`],body:`# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`}]);

package/dist/contracts/src/docs/tech/workflows/overview.docblock.js

@@ -0,0 +1 @@
+import{registerDocBlocks as e}from"../../registry.js";e([{id:`docs.tech.workflows.overview`,title:`WorkflowSpec Overview`,summary:"WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",kind:`reference`,visibility:`public`,route:`/docs/tech/workflows/overview`,tags:[`tech`,`workflows`,`overview`],body:"# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` → `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@lssm/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"}]);

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

@@ -0,0 +1,80 @@
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.behavior-tracking`,title:`Behavior Tracking`,summary:"`@lssm/lib.personalization` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.",kind:`reference`,visibility:`public`,route:`/docs/personalization/behavior-tracking`,tags:[`personalization`,`behavior-tracking`],body:`# Behavior Tracking
+
+\`@lssm/lib.personalization\` provides primitives to observe how tenants/users interact with specs and turn that telemetry into personalization insights.
+
+## Tracker
+
+\`\`\`ts
+import { createBehaviorTracker } from '@lssm/lib.personalization';
+import { InMemoryBehaviorStore } from '@lssm/lib.personalization/store';
+
+const tracker = createBehaviorTracker({
+  store: new InMemoryBehaviorStore(),
+  context: { tenantId: ctx.tenant.id, userId: ctx.identity.userId },
+  autoFlushIntervalMs: 5000,
+});
+
+tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'internalNotes' });
+tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
+tracker.trackWorkflowStep({ workflow: 'invoice-approval', step: 'review', status: 'entered' });
+\`\`\`
+
+All events are buffered and flushed either when the buffer hits 25 entries or when \`autoFlushIntervalMs\` elapses. Tracked metrics flow to OpenTelemetry via the meter/counter built into the tracker.
+
+## Analyzer
+
+\`\`\`ts
+import { BehaviorAnalyzer } from '@lssm/lib.personalization/analyzer';
+
+const analyzer = new BehaviorAnalyzer(store, { fieldInactivityThreshold: 2 });
+const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'manager-42', windowMs: 7 * 24 * 60 * 60 * 1000 });
+
+/*
+{
+  unusedFields: ['internalNotes'],
+  suggestedHiddenFields: ['internalNotes'],
+  frequentlyUsedFields: ['customerReference', 'items'],
+  workflowBottlenecks: [{ workflow: 'invoice-approval', step: 'finance-review', dropRate: 0.6 }],
+  layoutPreference: 'table'
+}
+*/
+\`\`\`
+
+Use the analyzer output with the overlay adapter to generate suggestions automatically.
+
+## Adapter
+
+\`\`\`ts
+import { insightsToOverlaySuggestion } from '@lssm/lib.personalization/adapter';
+
+const overlay = insightsToOverlaySuggestion(insights, {
+  overlayId: 'acme-order-form',
+  tenantId: 'acme',
+  capability: 'billing.createOrder',
+});
+\`\`\`
+
+When the adapter returns an overlay spec, pass it to the overlay engine to register or sign it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`}];e(t);export{t as personalization_behavior_tracking_DocBlocks};

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./behavior-tracking.docblock.js";import"./overlay-engine.docblock.js";import"./workflow-composition.docblock.js";

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

@@ -0,0 +1,81 @@
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.overlay-engine`,title:`Overlay Engine`,summary:"`@lssm/lib.overlay-engine` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.",kind:`reference`,visibility:`public`,route:`/docs/personalization/overlay-engine`,tags:[`personalization`,`overlay-engine`],body:`# Overlay Engine
+
+\`@lssm/lib.overlay-engine\` is the canonical runtime for OverlaySpecs. It validates specs, tracks scope precedence, and exposes hooks for React renderers.
+
+## Key APIs
+
+- \`defineOverlay(spec)\` – helper to keep specs typed.
+- \`OverlayRegistry\` – register signed overlays and retrieve them per context.
+- \`OverlayEngine\` – apply overlays to renderable targets, emit audit events, and merge modifications deterministically.
+- \`signOverlay(spec, privateKey)\` – Ed25519/RSA-PSS signer.
+- \`verifyOverlaySignature(overlay)\` – verify public key signatures.
+- \`useOverlay(engine, params)\` – client hook that returns \`{ target, overlaysApplied }\`.
+
+## Scope Precedence
+
+Registrations are sorted by specificity:
+
+1. Tenant overlays
+2. Role overlays
+3. User overlays
+4. Device overlays
+
+Less specific overlays run first; more specific overlays override later.
+
+## Example
+
+\`\`\`ts
+const registry = new OverlayRegistry();
+const engine = new OverlayEngine({
+  registry,
+  audit: (event) => auditLogService.record(event),
+});
+
+const overlay = defineOverlay({
+  overlayId: 'acme-order-form',
+  version: '1.0.0',
+  appliesTo: {
+    capability: 'billing.createOrder',
+    tenantId: 'acme',
+  },
+  modifications: [
+    { type: 'hideField', field: 'internalNotes' },
+    { type: 'renameLabel', field: 'customerReference', newLabel: 'PO Number' },
+  ],
+});
+
+const signedOverlay = await signOverlay(overlay, privateKeyPem);
+registry.register(signedOverlay);
+
+const result = engine.apply({
+  target: { fields: baseFields },
+  capability: 'billing.createOrder',
+  tenantId: 'acme',
+  userId: 'manager-7',
+});
+\`\`\`
+
+\`result.target.fields\` now carries the hidden and renamed outputs ready for rendering.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`}];e(t);export{t as personalization_overlay_engine_DocBlocks};

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

@@ -0,0 +1,66 @@
+import{registerDocBlocks as e}from"../contracts/src/docs/registry.js";import"../contracts/src/docs/index.js";const t=[{id:`docs.personalization.workflow-composition`,title:`Workflow Composition`,summary:"`@lssm/lib.workflow-composer` composes base WorkflowSpecs with tenant/role/device-specific extensions.",kind:`reference`,visibility:`public`,route:`/docs/personalization/workflow-composition`,tags:[`personalization`,`workflow-composition`],body:`# Workflow Composition
+
+\`@lssm/lib.workflow-composer\` composes base WorkflowSpecs with tenant/role/device-specific extensions.
+
+## Extensions
+
+\`\`\`ts
+import { WorkflowComposer } from '@lssm/lib.workflow-composer';
+import { approvalStepTemplate } from '@lssm/lib.workflow-composer/templates';
+
+const composer = new WorkflowComposer();
+
+composer.register({
+  workflow: 'billing.invoiceApproval',
+  tenantId: 'acme',
+  priority: 10,
+  customSteps: [
+    {
+      after: 'validate-invoice',
+      inject: approvalStepTemplate({
+        id: 'acme-legal-review',
+        label: 'Legal Review (ACME)',
+        description: 'Tenant-specific compliance step.',
+      }),
+      transitionTo: 'final-approval',
+    },
+  ],
+  hiddenSteps: ['internal-audit'],
+});
+\`\`\`
+
+## Compose
+
+\`\`\`ts
+const runtimeSpec = composer.compose({
+  base: BaseInvoiceWorkflow,
+  tenantId: 'acme',
+});
+
+workflowRunner.execute(runtimeSpec, ctx);
+\`\`\`
+
+The composer uses anchor references (\`after\`/\`before\`) to place injected steps and cleans up transitions when steps are hidden.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`}];e(t);export{t as personalization_workflow_composition_DocBlocks};

package/dist/index.js

@@ -1 +1 @@
-import{InMemoryBehaviorStore as e}from"./store.js";import{BehaviorTracker as t,createBehaviorTracker as n}from"./tracker.js";import{BehaviorAnalyzer as r}from"./analyzer.js";import{insightsToOverlaySuggestion as i,insightsToWorkflowAdaptations as a}from"./adapter.js";export{r as BehaviorAnalyzer,t as BehaviorTracker,e as InMemoryBehaviorStore,n as createBehaviorTracker,i as insightsToOverlaySuggestion,a as insightsToWorkflowAdaptations};
+import{insightsToOverlaySuggestion as e,insightsToWorkflowAdaptations as t}from"./adapter.js";import{BehaviorAnalyzer as n}from"./analyzer.js";import{InMemoryBehaviorStore as r}from"./store.js";import{BehaviorTracker as i,createBehaviorTracker as a}from"./tracker.js";import"./docs/index.js";export{n as BehaviorAnalyzer,i as BehaviorTracker,r as InMemoryBehaviorStore,a as createBehaviorTracker,e as insightsToOverlaySuggestion,t as insightsToWorkflowAdaptations};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.personalization",
-  "version": "0.3.1",
+  "version": "1.41.1",
   "description": "Behavior tracking, analysis, and adaptation helpers for ContractSpec personalization.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
     "build": "bun build:bundle && bun build:types",
     "build:bundle": "tsdown",
     "build:types": "tsc --noEmit",
@@ -23,24 +24,46 @@
     "test": "bun run"
   },
   "dependencies": {
-    "@lssm/lib.bus": "1.11.1",
-    "@lssm/lib.overlay-engine": "0.3.1",
+    "@lssm/lib.bus": "1.41.1",
+    "@lssm/lib.overlay-engine": "1.41.1",
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.12.1",
-    "@lssm/tool.typescript": "0.11.1",
-    "tsdown": "^0.16.6",
+    "@lssm/tool.tsdown": "1.41.1",
+    "@lssm/tool.typescript": "1.41.1",
+    "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "exports": {
-    ".": "./dist/index.js",
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
+    "./analyzer": "./src/analyzer.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/behavior-tracking.docblock": "./src/docs/behavior-tracking.docblock.ts",
+    "./docs/overlay-engine.docblock": "./src/docs/overlay-engine.docblock.ts",
+    "./docs/workflow-composition.docblock": "./src/docs/workflow-composition.docblock.ts",
+    "./store": "./src/store.ts",
+    "./tracker": "./src/tracker.ts",
+    "./types": "./src/types.ts",
     "./*": "./*"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./adapter": "./dist/adapter.js",
+      "./analyzer": "./dist/analyzer.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/behavior-tracking.docblock": "./dist/docs/behavior-tracking.docblock.js",
+      "./docs/overlay-engine.docblock": "./dist/docs/overlay-engine.docblock.js",
+      "./docs/workflow-composition.docblock": "./dist/docs/workflow-composition.docblock.js",
+      "./store": "./dist/store.js",
+      "./tracker": "./dist/tracker.js",
+      "./types": "./dist/types.js",
+      "./*": "./*"
+    }
   }
 }

package/dist/adapter.d.ts

@@ -1,21 +0,0 @@
-import { BehaviorInsights } from "./types.js";
-import { OverlaySpec } from "@lssm/lib.overlay-engine";
-
-//#region src/adapter.d.ts
-interface OverlaySuggestionOptions {
-  overlayId: string;
-  tenantId: string;
-  capability: string;
-  userId?: string;
-  role?: string;
-  version?: string;
-}
-interface WorkflowAdaptation {
-  workflow: string;
-  step: string;
-  note: string;
-}
-declare function insightsToOverlaySuggestion(insights: BehaviorInsights, options: OverlaySuggestionOptions): OverlaySpec | null;
-declare function insightsToWorkflowAdaptations(insights: BehaviorInsights): WorkflowAdaptation[];
-//#endregion
-export { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };

package/dist/analyzer.d.ts

@@ -1,22 +0,0 @@
-import { BehaviorInsights } from "./types.js";
-import { BehaviorStore } from "./store.js";
-
-//#region src/analyzer.d.ts
-interface BehaviorAnalyzerOptions {
-  fieldInactivityThreshold?: number;
-  minSamples?: number;
-}
-interface AnalyzeParams {
-  tenantId: string;
-  userId?: string;
-  role?: string;
-  windowMs?: number;
-}
-declare class BehaviorAnalyzer {
-  private readonly store;
-  private readonly options;
-  constructor(store: BehaviorStore, options?: BehaviorAnalyzerOptions);
-  analyze(params: AnalyzeParams): Promise<BehaviorInsights>;
-}
-//#endregion
-export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions };

package/dist/index.d.ts

@@ -1,6 +0,0 @@
-import { BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorSummary, FeatureUsageEvent, FieldAccessEvent, WorkflowStepEvent } from "./types.js";
-import { BehaviorStore, InMemoryBehaviorStore } from "./store.js";
-import { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker } from "./tracker.js";
-import { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions } from "./analyzer.js";
-import { OverlaySuggestionOptions, WorkflowAdaptation, insightsToOverlaySuggestion, insightsToWorkflowAdaptations } from "./adapter.js";
-export { AnalyzeParams, BehaviorAnalyzer, BehaviorAnalyzerOptions, BehaviorEvent, BehaviorEventBase, BehaviorEventType, BehaviorInsights, BehaviorQuery, BehaviorStore, BehaviorSummary, BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, FeatureUsageEvent, FieldAccessEvent, InMemoryBehaviorStore, OverlaySuggestionOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, WorkflowAdaptation, WorkflowStepEvent, createBehaviorTracker, insightsToOverlaySuggestion, insightsToWorkflowAdaptations };

package/dist/store.d.ts

@@ -1,20 +0,0 @@
-import { BehaviorEvent, BehaviorQuery, BehaviorSummary } from "./types.js";
-
-//#region src/store.d.ts
-interface BehaviorStore {
-  record(event: BehaviorEvent): Promise<void> | void;
-  bulkRecord(events: BehaviorEvent[]): Promise<void> | void;
-  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
-  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
-  clear?(): Promise<void> | void;
-}
-declare class InMemoryBehaviorStore implements BehaviorStore {
-  private events;
-  record(event: BehaviorEvent): Promise<void>;
-  bulkRecord(events: BehaviorEvent[]): Promise<void>;
-  query(query: BehaviorQuery): Promise<BehaviorEvent[]>;
-  summarize(query: BehaviorQuery): Promise<BehaviorSummary>;
-  clear(): Promise<void>;
-}
-//#endregion
-export { BehaviorStore, InMemoryBehaviorStore };

package/dist/tracker.d.ts

@@ -1,52 +0,0 @@
-import { BehaviorStore } from "./store.js";
-
-//#region src/tracker.d.ts
-interface BehaviorTrackerContext {
-  tenantId: string;
-  userId?: string;
-  role?: string;
-  device?: string;
-  metadata?: Record<string, unknown>;
-}
-interface BehaviorTrackerOptions {
-  store: BehaviorStore;
-  context: BehaviorTrackerContext;
-  tracerName?: string;
-  autoFlushIntervalMs?: number;
-  bufferSize?: number;
-}
-interface TrackFieldAccessInput {
-  operation: string;
-  field: string;
-  metadata?: Record<string, unknown>;
-}
-interface TrackFeatureUsageInput {
-  feature: string;
-  action: 'opened' | 'completed' | 'dismissed';
-  metadata?: Record<string, unknown>;
-}
-interface TrackWorkflowStepInput {
-  workflow: string;
-  step: string;
-  status: 'entered' | 'completed' | 'skipped' | 'errored';
-  metadata?: Record<string, unknown>;
-}
-declare class BehaviorTracker {
-  private readonly store;
-  private readonly context;
-  private readonly tracer;
-  private readonly counter;
-  private buffer;
-  private readonly bufferSize;
-  private flushTimer?;
-  constructor(options: BehaviorTrackerOptions);
-  trackFieldAccess(input: TrackFieldAccessInput): void;
-  trackFeatureUsage(input: TrackFeatureUsageInput): void;
-  trackWorkflowStep(input: TrackWorkflowStepInput): void;
-  flush(): Promise<void>;
-  dispose(): Promise<void>;
-  private enqueue;
-}
-declare const createBehaviorTracker: (options: BehaviorTrackerOptions) => BehaviorTracker;
-//#endregion
-export { BehaviorTracker, BehaviorTrackerContext, BehaviorTrackerOptions, TrackFeatureUsageInput, TrackFieldAccessInput, TrackWorkflowStepInput, createBehaviorTracker };