@contractspec/example.learning-journey-duo-drills 0.0.0-canary-20260113162409

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@contractspec/example.learning-journey-duo-drills",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Drill-based learning journey example with SRS, XP, and streak hooks.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/duo-drills.docblock": "./dist/docs/duo-drills.docblock.js",
+    "./example": "./dist/example.js",
+    "./track": "./dist/track.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "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": {
+    "@contractspec/module.learning-journey": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./example": "./dist/example.js",
+      "./track": "./dist/track.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/duo-drills.docblock": "./dist/docs/duo-drills.docblock.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/learning-journey-duo-drills"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/duo-drills.docblock.ts

@@ -0,0 +1,33 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const duoDrillsDocBlocks: DocBlock[] = [
+  {
+    id: 'docs.learning-journey.duo-drills',
+    title: 'Learning Journey — Duo Drills',
+    summary:
+      'Short drill/SRS example with XP and streak hooks for language, finance, or ContractSpec concept drills.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/learning-journey/duo-drills',
+    tags: ['learning', 'drills', 'srs', 'xp'],
+    body: `## Track
+- **Key**: \`drills_language_basics\`
+- **Persona**: learner running quick drills (language/finance/spec concepts)
+- **Goal**: complete first session, maintain high-accuracy sessions, master cards in the first skill
+
+## Steps & Conditions
+1) \`complete_first_session\` → event \`drill.session.completed\`
+2) \`reach_accuracy_threshold\` → count 3 sessions with payload \`accuracyBucket: "high"\` (within default window)
+3) \`unlock_new_skill\` → SRS mastery: \`drill.card.mastered\` events with \`mastery >= 0.8\`, count 5 cards
+
+XP: 20 + 30 + 40. Streak: daily session completion can be used to drive streak rewards.
+
+## Wiring
+- Tracks export from \`@contractspec/example.learning-journey-duo-drills/track\`.
+- Use registry helper \`recordEvent\` to advance steps from drill/session events.
+- SRS mastery events should include payload: \`{ skillId, mastery }\`.`,
+  },
+];
+
+registerDocBlocks(duoDrillsDocBlocks);

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './duo-drills.docblock';

package/src/example.ts

@@ -0,0 +1,31 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'learning-journey-duo-drills',
+    version: '1.0.0',
+    title: 'Learning Journey — Duo Drills',
+    description:
+      'Short drill/SRS example with XP and streak hooks for language, finance, or ContractSpec concept drills.',
+    kind: 'template',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['learning', 'drills', 'srs', 'xp'],
+  },
+  docs: {
+    rootDocId: 'docs.learning-journey.duo-drills',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.learning-journey-duo-drills',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'markdown'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './track';
+export { default as example } from './example';
+import './docs';

package/src/track.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'bun:test';
+
+import { drillsLanguageBasicsTrack } from './track';
+
+interface TestEvent {
+  name: string;
+  payload?: Record<string, unknown>;
+  occurredAt?: Date;
+}
+
+const matchesFilter = (
+  filter: Record<string, unknown> | undefined,
+  payload: Record<string, unknown> | undefined
+) => {
+  if (!filter) return true;
+  if (!payload) return false;
+  return Object.entries(filter).every(([key, value]) => payload[key] === value);
+};
+
+interface StepState {
+  id: string;
+  status: 'PENDING' | 'COMPLETED';
+  occurrences: number;
+  masteryCount: number;
+}
+
+describe('duo drills track', () => {
+  it('advances on session completion, accuracy counts, and SRS mastery', () => {
+    const events: TestEvent[] = [
+      {
+        name: 'drill.session.completed',
+        payload: { accuracyBucket: 'high' },
+      },
+      {
+        name: 'drill.session.completed',
+        payload: { accuracyBucket: 'high' },
+      },
+      {
+        name: 'drill.session.completed',
+        payload: { accuracyBucket: 'high' },
+      },
+      ...Array.from({ length: 5 }).map<TestEvent>(() => ({
+        name: 'drill.card.mastered',
+        payload: { skillId: 'language_basics', mastery: 0.9 },
+      })),
+    ];
+
+    const progress: StepState[] =
+      drillsLanguageBasicsTrack.steps.map<StepState>((step) => ({
+        id: step.id,
+        status: 'PENDING',
+        occurrences: 0,
+        masteryCount: 0,
+      }));
+
+    events.forEach((event) => {
+      drillsLanguageBasicsTrack.steps.forEach((stepSpec, index) => {
+        const step = progress[index];
+        if (!step || step.status === 'COMPLETED') return;
+        const completion = stepSpec.completion;
+        if ((completion.kind ?? 'event') === 'event') {
+          if (completion.eventName !== event.name) return;
+          if (
+            matchesFilter(
+              completion.payloadFilter,
+              event.payload as Record<string, unknown> | undefined
+            )
+          ) {
+            step.status = 'COMPLETED';
+          }
+          return;
+        }
+        if (completion.kind === 'count') {
+          if (
+            completion.eventName === event.name &&
+            matchesFilter(
+              completion.payloadFilter,
+              event.payload as Record<string, unknown> | undefined
+            )
+          ) {
+            step.occurrences = step.occurrences + 1;
+            if (step.occurrences >= completion.atLeast) {
+              step.status = 'COMPLETED';
+            }
+          }
+          return;
+        }
+        if (completion.kind === 'srs_mastery') {
+          if (completion.eventName !== event.name) return;
+          if (!matchesFilter(completion.payloadFilter, event.payload)) return;
+          const masteryValue = (
+            event.payload as Record<string, unknown> | undefined
+          )?.[completion.masteryField ?? 'mastery'];
+          if (typeof masteryValue !== 'number') return;
+          if (masteryValue < completion.minimumMastery) return;
+          step.masteryCount = step.masteryCount + 1;
+          if (step.masteryCount >= (completion.requiredCount ?? 1)) {
+            step.status = 'COMPLETED';
+          }
+        }
+      });
+    });
+
+    expect(progress.every((s) => s.status === 'COMPLETED')).toBeTrue();
+  });
+});

package/src/track.ts

@@ -0,0 +1,62 @@
+import type { LearningJourneyTrackSpec } from '@contractspec/module.learning-journey/track-spec';
+
+export const drillsLanguageBasicsTrack: LearningJourneyTrackSpec = {
+  id: 'drills_language_basics',
+  name: 'Language Basics Drills',
+  description:
+    'Short SRS-driven drills to master a first skill, modeled after Duolingo-style sessions.',
+  targetUserSegment: 'learner',
+  targetRole: 'individual',
+  totalXp: 50,
+  completionRewards: { xpBonus: 25 },
+  steps: [
+    {
+      id: 'complete_first_session',
+      title: 'Complete first drill session',
+      description: 'Finish a drill session to get started.',
+      order: 1,
+      completion: {
+        kind: 'event',
+        eventName: 'drill.session.completed',
+      },
+      xpReward: 20,
+      metadata: { surface: 'drills' },
+    },
+    {
+      id: 'reach_accuracy_threshold',
+      title: 'Hit high accuracy in sessions',
+      description: 'Achieve three high-accuracy sessions to build confidence.',
+      order: 2,
+      completion: {
+        kind: 'count',
+        eventName: 'drill.session.completed',
+        atLeast: 3,
+        payloadFilter: { accuracyBucket: 'high' },
+      },
+      xpReward: 30,
+      metadata: { metric: 'accuracy', target: '>=85%' },
+    },
+    {
+      id: 'unlock_new_skill',
+      title: 'Master core cards in first skill',
+      description:
+        'Reach mastery on at least five cards in the first skill to unlock the next one.',
+      order: 3,
+      completion: {
+        kind: 'srs_mastery',
+        eventName: 'drill.card.mastered',
+        minimumMastery: 0.8,
+        requiredCount: 5,
+        skillIdField: 'skillId',
+        masteryField: 'mastery',
+        payloadFilter: { skillId: 'language_basics' },
+      },
+      xpReward: 40,
+      metadata: { surface: 'srs', skill: 'language_basics' },
+    },
+  ],
+};
+
+export const drillTracks: LearningJourneyTrackSpec[] = [
+  drillsLanguageBasicsTrack,
+];

package/tsconfig.json

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