@lssm/example.learning-patterns 0.0.0-canary-20251213172311

package/dist/libs/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/libs/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/tracks/ambient-coach.js

@@ -0,0 +1 @@
+import{LEARNING_EVENTS as e}from"../events.js";const t={id:`learning_patterns_ambient_coach_basics`,name:`Ambient Coach Basics`,description:`Contextual tips triggered by behavior events.`,targetUserSegment:`learner`,targetRole:`individual`,totalXp:30,steps:[{id:`tip_shown`,title:`See a contextual tip`,order:1,completion:{kind:`event`,eventName:e.COACH_TIP_SHOWN},xpReward:10},{id:`tip_acknowledged`,title:`Acknowledge a tip`,order:2,completion:{kind:`event`,eventName:e.COACH_TIP_ACKNOWLEDGED},xpReward:10},{id:`tip_action_taken`,title:`Take an action from a tip`,order:3,completion:{kind:`event`,eventName:e.COACH_TIP_ACTION_TAKEN},xpReward:10}]},n=[t];export{t as ambientCoachTrack,n as ambientCoachTracks};

package/dist/tracks/drills.js

@@ -0,0 +1 @@
+import{LEARNING_EVENTS as e}from"../events.js";const t={id:`learning_patterns_drills_basics`,name:`Drills Basics`,description:`Short drill sessions with an SRS-style mastery step.`,targetUserSegment:`learner`,targetRole:`individual`,totalXp:50,steps:[{id:`complete_first_session`,title:`Complete your first session`,order:1,completion:{kind:`event`,eventName:e.DRILL_SESSION_COMPLETED},xpReward:10},{id:`hit_accuracy_threshold`,title:`Hit high accuracy 3 times`,order:2,completion:{kind:`count`,eventName:e.DRILL_SESSION_COMPLETED,atLeast:3,payloadFilter:{accuracyBucket:`high`}},xpReward:20},{id:`master_cards`,title:`Master 5 cards`,order:3,completion:{kind:`srs_mastery`,eventName:e.DRILL_CARD_MASTERED,minimumMastery:.8,requiredCount:5,skillIdField:`skillId`,masteryField:`mastery`},xpReward:20}]},n=[t];export{n as drillTracks,t as drillsTrack};

package/dist/tracks/index.js

@@ -0,0 +1 @@
+import{drillTracks as e,drillsTrack as t}from"./drills.js";import{ambientCoachTrack as n,ambientCoachTracks as r}from"./ambient-coach.js";import{questTrack as i,questTracks as a}from"./quests.js";export{n as ambientCoachTrack,r as ambientCoachTracks,e as drillTracks,t as drillsTrack,i as questTrack,a as questTracks};

package/dist/tracks/quests.js

@@ -0,0 +1 @@
+import{LEARNING_EVENTS as e}from"../events.js";const t={id:`learning_patterns_quest_7day`,name:`Quest (7-day)`,description:`Time-bounded quest with day unlocks.`,targetUserSegment:`learner`,targetRole:`individual`,totalXp:70,steps:[{id:`day1_start`,title:`Start the quest`,order:1,completion:{kind:`event`,eventName:e.QUEST_STARTED},xpReward:10},{id:`day1_complete`,title:`Complete day 1 step`,order:2,completion:{kind:`event`,eventName:e.QUEST_STEP_COMPLETED},availability:{unlockOnDay:1,dueWithinHours:48},xpReward:10},{id:`day2_complete`,title:`Complete day 2 step`,order:3,completion:{kind:`event`,eventName:e.QUEST_STEP_COMPLETED},availability:{unlockOnDay:2,dueWithinHours:48},xpReward:10}]},n=[t];export{t as questTrack,n as questTracks};

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lssm/example.learning-patterns",
+  "version": "0.0.0-canary-20251213172311",
+  "description": "Example: drills + ambient coach + quests learning patterns, powered by Learning Journey (event-driven, deterministic).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/learning-patterns.docblock": "./src/docs/learning-patterns.docblock.ts",
+    "./events": "./src/events.ts",
+    "./example": "./src/example.ts",
+    "./tracks": "./src/tracks/index.ts",
+    "./tracks/ambient-coach": "./src/tracks/ambient-coach.ts",
+    "./tracks/drills": "./src/tracks/drills.ts",
+    "./tracks/quests": "./src/tracks/quests.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@lssm/module.learning-journey": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/learning-patterns.docblock": "./dist/docs/learning-patterns.docblock.js",
+      "./events": "./dist/events.js",
+      "./example": "./dist/example.js",
+      "./tracks": "./dist/tracks/index.js",
+      "./tracks/ambient-coach": "./dist/tracks/ambient-coach.js",
+      "./tracks/drills": "./dist/tracks/drills.js",
+      "./tracks/quests": "./dist/tracks/quests.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+import './learning-patterns.docblock';
+
+

package/src/docs/learning-patterns.docblock.ts

@@ -0,0 +1,30 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/lib.contracts/docs';
+
+const docBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.learning-patterns.goal',
+    title: 'Learning Patterns — Goal',
+    summary: 'Domain-agnostic drills, ambient coaching, and quests built on Learning Journey.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/learning-patterns/goal',
+    tags: ['learning', 'drills', 'quests', 'coaching'],
+    body: `## Why it matters
+- Demonstrates multiple learning archetypes without vertical coupling.\n- Progress is event-driven (no client-side hacks).\n- SRS logic is deterministic and testable.`,
+  },
+  {
+    id: 'docs.examples.learning-patterns.reference',
+    title: 'Learning Patterns — Reference',
+    summary: 'Track specs and event names exported by the learning patterns example.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/learning-patterns',
+    tags: ['learning', 'reference'],
+    body: `## Tracks\n- Drills + SRS\n- Ambient Coach\n- Quests\n\n## Events\n- drill.*\n- coach.*\n- quest.*`,
+  },
+];
+
+registerDocBlocks(docBlocks);
+
+

package/src/events.ts

@@ -0,0 +1,17 @@
+export const LEARNING_EVENTS = {
+  DRILL_CARD_ANSWERED: 'drill.card.answered',
+  DRILL_SESSION_COMPLETED: 'drill.session.completed',
+  DRILL_CARD_MASTERED: 'drill.card.mastered',
+
+  COACH_TIP_TRIGGERED: 'coach.tip.triggered',
+  COACH_TIP_SHOWN: 'coach.tip.shown',
+  COACH_TIP_ACKNOWLEDGED: 'coach.tip.acknowledged',
+  COACH_TIP_ACTION_TAKEN: 'coach.tip.actionTaken',
+
+  QUEST_STARTED: 'quest.started',
+  QUEST_STEP_COMPLETED: 'quest.step.completed',
+} as const;
+
+export type LearningEventName = (typeof LEARNING_EVENTS)[keyof typeof LEARNING_EVENTS];
+
+

package/src/example.ts

@@ -0,0 +1,25 @@
+const example = {
+  id: 'learning-patterns',
+  title: 'Learning Patterns',
+  summary: 'Domain-agnostic learning archetypes implemented as Learning Journey tracks.',
+  tags: ['learning', 'journey', 'patterns'],
+  kind: 'library',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-patterns',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.learning-patterns',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;
+
+

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Learning Patterns Example
+ *
+ * Domain-agnostic learning archetypes implemented as Learning Journey tracks.
+ */
+export * from './events';
+export * from './tracks';
+export { default as example } from './example';
+
+import './docs';
+
+

package/src/learning-patterns.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  LearningJourneyTrackSpec,
+  StepAvailabilitySpec,
+  StepCompletionConditionSpec,
+} from '@lssm/module.learning-journey/track-spec';
+import { SRSEngine } from '@lssm/module.learning-journey/engines/srs';
+import { StreakEngine } from '@lssm/module.learning-journey/engines/streak';
+import { XPEngine } from '@lssm/module.learning-journey/engines/xp';
+
+import { ambientCoachTrack } from './tracks/ambient-coach';
+import { drillsTrack } from './tracks/drills';
+import { questTrack } from './tracks/quests';
+import { LEARNING_EVENTS } from './events';
+
+interface LearningEvent {
+  name: string;
+  payload?: Record<string, unknown>;
+  occurredAt?: Date;
+}
+
+interface StepState {
+  id: string;
+  status: 'PENDING' | 'COMPLETED';
+  occurrences: number;
+  masteryCount: number;
+  availableAt?: Date;
+  dueAt?: Date;
+}
+
+const matchesFilter = (
+  filter: Record<string, unknown> | undefined,
+  payload: Record<string, unknown> | undefined
+): boolean => {
+  if (!filter) return true;
+  if (!payload) return false;
+  return Object.entries(filter).every(([k, v]) => payload[k] === v);
+};
+
+const getAvailability = (
+  availability: StepAvailabilitySpec | undefined,
+  startedAt: Date | undefined
+): { availableAt?: Date; dueAt?: Date } => {
+  if (!availability || !startedAt) return {};
+  const baseTime = startedAt.getTime();
+  let unlockTime = baseTime;
+  if (availability.unlockOnDay !== undefined) {
+    unlockTime = baseTime + (availability.unlockOnDay - 1) * 24 * 60 * 60 * 1000;
+  }
+  if (availability.unlockAfterHours !== undefined) {
+    unlockTime = baseTime + availability.unlockAfterHours * 60 * 60 * 1000;
+  }
+  const availableAt = new Date(unlockTime);
+  const dueAt =
+    availability.dueWithinHours !== undefined
+      ? new Date(availableAt.getTime() + availability.dueWithinHours * 60 * 60 * 1000)
+      : undefined;
+  return { availableAt, dueAt };
+};
+
+const matchesCondition = (
+  condition: StepCompletionConditionSpec,
+  event: LearningEvent,
+  step: StepState
+): { matched: boolean; occurrences?: number; masteryCount?: number } => {
+  if ((condition.kind ?? 'event') === 'event') {
+    if (condition.eventName !== event.name) return { matched: false };
+    if (!matchesFilter(condition.payloadFilter, event.payload)) return { matched: false };
+    return { matched: true };
+  }
+  if (condition.kind === 'count') {
+    if (condition.eventName !== event.name) return { matched: false };
+    if (!matchesFilter(condition.payloadFilter, event.payload)) return { matched: false };
+    const occurrences = step.occurrences + 1;
+    return { matched: occurrences >= condition.atLeast, occurrences };
+  }
+  if (condition.kind === 'srs_mastery') {
+    if (condition.eventName !== event.name) return { matched: false };
+    if (!matchesFilter(condition.payloadFilter, event.payload)) return { matched: false };
+    const masteryKey = condition.masteryField ?? 'mastery';
+    const masteryValue = event.payload?.[masteryKey];
+    if (typeof masteryValue !== 'number') return { matched: false };
+    if (masteryValue < condition.minimumMastery) return { matched: false };
+    const masteryCount = step.masteryCount + 1;
+    const required = condition.requiredCount ?? 1;
+    return { matched: masteryCount >= required, masteryCount };
+  }
+  if (condition.kind === 'time_window') {
+    // For this example suite, we treat time_window as a direct match on eventName
+    if (condition.eventName !== event.name) return { matched: false };
+    return { matched: true };
+  }
+  return { matched: false };
+};
+
+function initProgress(track: LearningJourneyTrackSpec): StepState[] {
+  return track.steps.map((s) => ({
+    id: s.id,
+    status: 'PENDING',
+    occurrences: 0,
+    masteryCount: 0,
+  }));
+}
+
+function applyEvents(track: LearningJourneyTrackSpec, events: LearningEvent[]): StepState[] {
+  const steps = initProgress(track);
+  let startedAt: Date | undefined;
+  for (const event of events) {
+    const eventTime = event.occurredAt ?? new Date();
+    if (!startedAt) startedAt = eventTime;
+    for (let index = 0; index < track.steps.length; index++) {
+      const spec = track.steps[index];
+      const state = steps[index];
+      if (!spec || !state) continue;
+      if (state.status === 'COMPLETED') continue;
+      const { availableAt, dueAt } = getAvailability(spec.availability, startedAt);
+      state.availableAt = availableAt;
+      state.dueAt = dueAt;
+      if (availableAt && eventTime < availableAt) continue;
+      if (dueAt && eventTime > dueAt) continue;
+      const res = matchesCondition(spec.completion, event, state);
+      if (res.occurrences !== undefined) state.occurrences = res.occurrences;
+      if (res.masteryCount !== undefined) state.masteryCount = res.masteryCount;
+      if (res.matched) state.status = 'COMPLETED';
+    }
+  }
+  return steps;
+}
+
+describe('@lssm/example.learning-patterns tracks', () => {
+  it('drills track progresses via session count + mastery', () => {
+    const events: LearningEvent[] = [
+      { name: LEARNING_EVENTS.DRILL_SESSION_COMPLETED },
+      { name: LEARNING_EVENTS.DRILL_SESSION_COMPLETED, payload: { accuracyBucket: 'high' } },
+      { name: LEARNING_EVENTS.DRILL_SESSION_COMPLETED, payload: { accuracyBucket: 'high' } },
+      { name: LEARNING_EVENTS.DRILL_SESSION_COMPLETED, payload: { accuracyBucket: 'high' } },
+      ...Array.from({ length: 5 }).map(() => ({
+        name: LEARNING_EVENTS.DRILL_CARD_MASTERED,
+        payload: { skillId: 's1', mastery: 0.9 },
+      })),
+    ];
+    const progress = applyEvents(drillsTrack, events);
+    expect(progress.every((s) => s.status === 'COMPLETED')).toBeTrue();
+  });
+
+  it('ambient coach track progresses via shown -> acknowledged -> actionTaken', () => {
+    const progress = applyEvents(ambientCoachTrack, [
+      { name: LEARNING_EVENTS.COACH_TIP_SHOWN },
+      { name: LEARNING_EVENTS.COACH_TIP_ACKNOWLEDGED },
+      { name: LEARNING_EVENTS.COACH_TIP_ACTION_TAKEN },
+    ]);
+    expect(progress.every((s) => s.status === 'COMPLETED')).toBeTrue();
+  });
+
+  it('quest track respects unlockOnDay availability', () => {
+    const start = new Date('2026-01-01T10:00:00.000Z');
+    const day1 = new Date('2026-01-01T12:00:00.000Z');
+    const day2 = new Date('2026-01-02T12:00:00.000Z');
+
+    // Attempt to complete steps on day1 (only day1 step should unlock)
+    const p1 = applyEvents(questTrack, [
+      { name: LEARNING_EVENTS.QUEST_STARTED, occurredAt: start },
+      { name: LEARNING_EVENTS.QUEST_STEP_COMPLETED, occurredAt: day1 },
+    ]);
+    expect(p1[0]?.status).toBe('COMPLETED');
+    expect(p1[1]?.status).toBe('COMPLETED');
+    expect(p1[2]?.status).toBe('PENDING'); // day2 step not yet available
+
+    // Now complete on day2
+    const p2 = applyEvents(questTrack, [
+      { name: LEARNING_EVENTS.QUEST_STARTED, occurredAt: start },
+      { name: LEARNING_EVENTS.QUEST_STEP_COMPLETED, occurredAt: day2 },
+    ]);
+    expect(p2[2]?.status).toBe('COMPLETED');
+  });
+});
+
+describe('@lssm/example.learning-patterns XP + streak + SRS determinism', () => {
+  it('XP engine produces deterministic results for streak bonus inputs', () => {
+    const xp = new XPEngine();
+    const r1 = xp.calculate({ activity: 'lesson_complete', score: 90, attemptNumber: 1, currentStreak: 7 });
+    const r2 = xp.calculate({ activity: 'lesson_complete', score: 90, attemptNumber: 1, currentStreak: 7 });
+    expect(r1.totalXp).toBe(r2.totalXp);
+    expect(r1.totalXp).toBeGreaterThan(0);
+  });
+
+  it('streak engine increments on consecutive days deterministically', () => {
+    const streak = new StreakEngine({ timezone: 'UTC' });
+    const initial = {
+      currentStreak: 0,
+      longestStreak: 0,
+      lastActivityAt: null,
+      lastActivityDate: null,
+      freezesRemaining: 0,
+      freezeUsedAt: null,
+    };
+    const day1 = streak.update(initial, new Date('2026-01-01T10:00:00.000Z')).state;
+    const day2 = streak.update(day1, new Date('2026-01-02T10:00:00.000Z')).state;
+    expect(day2.currentStreak).toBe(2);
+  });
+
+  it('SRS engine nextReviewAt is deterministic for a fixed now + rating', () => {
+    const srs = new SRSEngine();
+    const now = new Date('2026-01-01T00:00:00.000Z');
+    const state = {
+      interval: 0,
+      easeFactor: 2.5,
+      repetitions: 0,
+      learningStep: 0,
+      isGraduated: false,
+      isRelearning: false,
+      lapses: 0,
+    };
+    const result = srs.calculateNextReview(state, 'GOOD', now);
+    // default learningSteps are minutes; first GOOD advances to next step (10 minutes)
+    expect(result.nextReviewAt.toISOString()).toBe('2026-01-01T00:10:00.000Z');
+  });
+});
+
+

package/src/tracks/ambient-coach.ts

@@ -0,0 +1,44 @@
+import type { LearningJourneyTrackSpec } from '@lssm/module.learning-journey/track-spec';
+import { LEARNING_EVENTS } from '../events';
+
+export const ambientCoachTrack: LearningJourneyTrackSpec = {
+  id: 'learning_patterns_ambient_coach_basics',
+  name: 'Ambient Coach Basics',
+  description: 'Contextual tips triggered by behavior events.',
+  targetUserSegment: 'learner',
+  targetRole: 'individual',
+  totalXp: 30,
+  steps: [
+    {
+      id: 'tip_shown',
+      title: 'See a contextual tip',
+      order: 1,
+      completion: { kind: 'event', eventName: LEARNING_EVENTS.COACH_TIP_SHOWN },
+      xpReward: 10,
+    },
+    {
+      id: 'tip_acknowledged',
+      title: 'Acknowledge a tip',
+      order: 2,
+      completion: {
+        kind: 'event',
+        eventName: LEARNING_EVENTS.COACH_TIP_ACKNOWLEDGED,
+      },
+      xpReward: 10,
+    },
+    {
+      id: 'tip_action_taken',
+      title: 'Take an action from a tip',
+      order: 3,
+      completion: {
+        kind: 'event',
+        eventName: LEARNING_EVENTS.COACH_TIP_ACTION_TAKEN,
+      },
+      xpReward: 10,
+    },
+  ],
+};
+
+export const ambientCoachTracks: LearningJourneyTrackSpec[] = [ambientCoachTrack];
+
+

package/src/tracks/drills.ts

@@ -0,0 +1,50 @@
+import type { LearningJourneyTrackSpec } from '@lssm/module.learning-journey/track-spec';
+import { LEARNING_EVENTS } from '../events';
+
+export const drillsTrack: LearningJourneyTrackSpec = {
+  id: 'learning_patterns_drills_basics',
+  name: 'Drills Basics',
+  description: 'Short drill sessions with an SRS-style mastery step.',
+  targetUserSegment: 'learner',
+  targetRole: 'individual',
+  totalXp: 50,
+  steps: [
+    {
+      id: 'complete_first_session',
+      title: 'Complete your first session',
+      order: 1,
+      completion: { kind: 'event', eventName: LEARNING_EVENTS.DRILL_SESSION_COMPLETED },
+      xpReward: 10,
+    },
+    {
+      id: 'hit_accuracy_threshold',
+      title: 'Hit high accuracy 3 times',
+      order: 2,
+      completion: {
+        kind: 'count',
+        eventName: LEARNING_EVENTS.DRILL_SESSION_COMPLETED,
+        atLeast: 3,
+        payloadFilter: { accuracyBucket: 'high' },
+      },
+      xpReward: 20,
+    },
+    {
+      id: 'master_cards',
+      title: 'Master 5 cards',
+      order: 3,
+      completion: {
+        kind: 'srs_mastery',
+        eventName: LEARNING_EVENTS.DRILL_CARD_MASTERED,
+        minimumMastery: 0.8,
+        requiredCount: 5,
+        skillIdField: 'skillId',
+        masteryField: 'mastery',
+      },
+      xpReward: 20,
+    },
+  ],
+};
+
+export const drillTracks: LearningJourneyTrackSpec[] = [drillsTrack];
+
+

package/src/tracks/index.ts

@@ -0,0 +1,5 @@
+export * from './drills';
+export * from './ambient-coach';
+export * from './quests';
+
+

package/src/tracks/quests.ts

@@ -0,0 +1,40 @@
+import type { LearningJourneyTrackSpec } from '@lssm/module.learning-journey/track-spec';
+import { LEARNING_EVENTS } from '../events';
+
+export const questTrack: LearningJourneyTrackSpec = {
+  id: 'learning_patterns_quest_7day',
+  name: 'Quest (7-day)',
+  description: 'Time-bounded quest with day unlocks.',
+  targetUserSegment: 'learner',
+  targetRole: 'individual',
+  totalXp: 70,
+  steps: [
+    {
+      id: 'day1_start',
+      title: 'Start the quest',
+      order: 1,
+      completion: { kind: 'event', eventName: LEARNING_EVENTS.QUEST_STARTED },
+      xpReward: 10,
+    },
+    {
+      id: 'day1_complete',
+      title: 'Complete day 1 step',
+      order: 2,
+      completion: { kind: 'event', eventName: LEARNING_EVENTS.QUEST_STEP_COMPLETED },
+      availability: { unlockOnDay: 1, dueWithinHours: 48 },
+      xpReward: 10,
+    },
+    {
+      id: 'day2_complete',
+      title: 'Complete day 2 step',
+      order: 3,
+      completion: { kind: 'event', eventName: LEARNING_EVENTS.QUEST_STEP_COMPLETED },
+      availability: { unlockOnDay: 2, dueWithinHours: 48 },
+      xpReward: 10,
+    },
+  ],
+};
+
+export const questTracks: LearningJourneyTrackSpec[] = [questTrack];
+
+

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@lssm/tool.typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+
+