@contractspec/module.learning-journey 1.44.0

package/dist/contracts/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","names":[],"sources":["../../src/contracts/operations.ts"],"sourcesContent":[],"mappings":";;;;;;;cAkBa,sDAAsB,0CAAA;EAAtB,QAAA,EAAA;IAgCX,IAAA,EAAA,2BAAA,CAAA,SAAA,CAAA,MAAA,EAAA,MAAA,CAAA;;EAhCiC,CAAA;;;UAAA,2BAAA,CAAA;;;;;;;;IAAA,IAAA,uCAAA,CAAA,MAAA,EAAA,MAAA,CAAA;IAqCtB,UAAA,EAAA,KAAA;EAgCX,CAAA;;;;EAhCiC,CAAA;;;;EAAA,CAAA;EAqCtB,SAAA,EAAA;IAgCX,IAAA,uCAAA,KAAA,EAAA,MAAA,CAAA;;;;IAhCmC,IAAA,uCAAA,KAAA,EAAA,MAAA,CAAA;;;;;AAqCrC;;cA1Ea,sDAAsB,0CAAA;;IA0EH,IAAA,EA1C9B,2BAAA,CAAA,SA0C8B,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;;;;;;2CAAA,CAAA;EAAA,OAAA,EAAA;IAuBnB,IAAA,EAjGsB,2BAAA,CAAA,SAmHjC,CAAA,OAAA,EAAA,OAAA,CAAA;IAAA,UAAA,EAAA,KAAA;;EAlBsC,QAAA,EAAA;;;;;;;;cA5D3B,wDAAwB,0CAAA;;UAgCnC,2BAAA,CAAA;;;;;;;;;;;;;UAhCmC,2BAAA,CAAA;;;;;;;;;;;cAqCxB,mBAuB2B,gCAvBR,aAuBQ,6BAvBR,WAuBQ,CAAA;EAAA,MAAA,EAAA;UALtC,2BAAA,CAAA;;;;;;;;;;;cAlB8B,2BAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuBnB,2DAA2B,0CAAA;;UAkBtC,2BAAA,CAAA;;;;;;;cAlBsC,2BAAA,CAAA"}

package/dist/contracts/operations.js

@@ -0,0 +1,151 @@
+import { LEARNING_JOURNEY_OWNERS } from "./shared.js";
+import { CompleteLessonInput, EnrollInCourseInput, EnrollmentModel, GetDueCardsInput, GetDueCardsOutput, GetLearnerDashboardInput, LearnerDashboardModel, SubmitCardReviewInput, SuccessOutput } from "./models.js";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+
+//#region src/contracts/operations.ts
+/**
+* Enroll in a course.
+*/
+const EnrollInCourseContract = defineCommand({
+	meta: {
+		key: "learning.enroll",
+		version: 1,
+		stability: "stable",
+		owners: [...LEARNING_JOURNEY_OWNERS],
+		tags: ["learning", "enrollment"],
+		description: "Enroll in a course.",
+		goal: "Start learning a new course.",
+		context: "Called when a learner wants to start a course."
+	},
+	io: {
+		input: EnrollInCourseInput,
+		output: EnrollmentModel,
+		errors: {
+			COURSE_NOT_FOUND: {
+				description: "Course does not exist",
+				http: 404,
+				gqlCode: "COURSE_NOT_FOUND",
+				when: "Course ID is invalid"
+			},
+			ALREADY_ENROLLED: {
+				description: "Already enrolled in course",
+				http: 409,
+				gqlCode: "ALREADY_ENROLLED",
+				when: "Learner is already enrolled"
+			}
+		}
+	},
+	policy: { auth: "user" }
+});
+/**
+* Complete a lesson.
+*/
+const CompleteLessonContract = defineCommand({
+	meta: {
+		key: "learning.completeLesson",
+		version: 1,
+		stability: "stable",
+		owners: [...LEARNING_JOURNEY_OWNERS],
+		tags: ["learning", "progress"],
+		description: "Mark a lesson as completed.",
+		goal: "Record lesson completion and earn XP.",
+		context: "Called when a learner finishes a lesson."
+	},
+	io: {
+		input: CompleteLessonInput,
+		output: SuccessOutput,
+		errors: {
+			LESSON_NOT_FOUND: {
+				description: "Lesson does not exist",
+				http: 404,
+				gqlCode: "LESSON_NOT_FOUND",
+				when: "Lesson ID is invalid"
+			},
+			NOT_ENROLLED: {
+				description: "Not enrolled in course",
+				http: 403,
+				gqlCode: "NOT_ENROLLED",
+				when: "Learner is not enrolled in the course"
+			}
+		}
+	},
+	policy: { auth: "user" }
+});
+/**
+* Submit a card review.
+*/
+const SubmitCardReviewContract = defineCommand({
+	meta: {
+		key: "learning.submitCardReview",
+		version: 1,
+		stability: "stable",
+		owners: [...LEARNING_JOURNEY_OWNERS],
+		tags: ["learning", "flashcards"],
+		description: "Submit a flashcard review.",
+		goal: "Record review and update SRS schedule.",
+		context: "Called when reviewing flashcards."
+	},
+	io: {
+		input: SubmitCardReviewInput,
+		output: SuccessOutput,
+		errors: {
+			CARD_NOT_FOUND: {
+				description: "Card does not exist",
+				http: 404,
+				gqlCode: "CARD_NOT_FOUND",
+				when: "Card ID is invalid"
+			},
+			INVALID_RATING: {
+				description: "Invalid rating",
+				http: 400,
+				gqlCode: "INVALID_RATING",
+				when: "Rating must be AGAIN, HARD, GOOD, or EASY"
+			}
+		}
+	},
+	policy: { auth: "user" }
+});
+/**
+* Get cards due for review.
+*/
+const GetDueCardsContract = defineQuery({
+	meta: {
+		key: "learning.getDueCards",
+		version: 1,
+		stability: "stable",
+		owners: [...LEARNING_JOURNEY_OWNERS],
+		tags: ["learning", "flashcards"],
+		description: "Get flashcards due for review.",
+		goal: "Get the next batch of cards to review.",
+		context: "Called when starting a review session."
+	},
+	io: {
+		input: GetDueCardsInput,
+		output: GetDueCardsOutput
+	},
+	policy: { auth: "user" }
+});
+/**
+* Get learner dashboard.
+*/
+const GetLearnerDashboardContract = defineQuery({
+	meta: {
+		key: "learning.getDashboard",
+		version: 1,
+		stability: "stable",
+		owners: [...LEARNING_JOURNEY_OWNERS],
+		tags: ["learning", "dashboard"],
+		description: "Get learner dashboard data.",
+		goal: "Display learner progress and stats.",
+		context: "Called when viewing the learning dashboard."
+	},
+	io: {
+		input: GetLearnerDashboardInput,
+		output: LearnerDashboardModel
+	},
+	policy: { auth: "user" }
+});
+
+//#endregion
+export { CompleteLessonContract, EnrollInCourseContract, GetDueCardsContract, GetLearnerDashboardContract, SubmitCardReviewContract };
+//# sourceMappingURL=operations.js.map

package/dist/contracts/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","names":[],"sources":["../../src/contracts/operations.ts"],"sourcesContent":["import { defineCommand, defineQuery } from '@contractspec/lib.contracts';\n\nimport {\n  CompleteLessonInput,\n  EnrollInCourseInput,\n  EnrollmentModel,\n  GetDueCardsInput,\n  GetDueCardsOutput,\n  GetLearnerDashboardInput,\n  LearnerDashboardModel,\n  SubmitCardReviewInput,\n  SuccessOutput,\n} from './models';\nimport { LEARNING_JOURNEY_OWNERS } from './shared';\n\n/**\n * Enroll in a course.\n */\nexport const EnrollInCourseContract = defineCommand({\n  meta: {\n    key: 'learning.enroll',\n    version: 1,\n    stability: 'stable',\n    owners: [...LEARNING_JOURNEY_OWNERS],\n    tags: ['learning', 'enrollment'],\n    description: 'Enroll in a course.',\n    goal: 'Start learning a new course.',\n    context: 'Called when a learner wants to start a course.',\n  },\n  io: {\n    input: EnrollInCourseInput,\n    output: EnrollmentModel,\n    errors: {\n      COURSE_NOT_FOUND: {\n        description: 'Course does not exist',\n        http: 404,\n        gqlCode: 'COURSE_NOT_FOUND',\n        when: 'Course ID is invalid',\n      },\n      ALREADY_ENROLLED: {\n        description: 'Already enrolled in course',\n        http: 409,\n        gqlCode: 'ALREADY_ENROLLED',\n        when: 'Learner is already enrolled',\n      },\n    },\n  },\n  policy: {\n    auth: 'user',\n  },\n});\n\n/**\n * Complete a lesson.\n */\nexport const CompleteLessonContract = defineCommand({\n  meta: {\n    key: 'learning.completeLesson',\n    version: 1,\n    stability: 'stable',\n    owners: [...LEARNING_JOURNEY_OWNERS],\n    tags: ['learning', 'progress'],\n    description: 'Mark a lesson as completed.',\n    goal: 'Record lesson completion and earn XP.',\n    context: 'Called when a learner finishes a lesson.',\n  },\n  io: {\n    input: CompleteLessonInput,\n    output: SuccessOutput,\n    errors: {\n      LESSON_NOT_FOUND: {\n        description: 'Lesson does not exist',\n        http: 404,\n        gqlCode: 'LESSON_NOT_FOUND',\n        when: 'Lesson ID is invalid',\n      },\n      NOT_ENROLLED: {\n        description: 'Not enrolled in course',\n        http: 403,\n        gqlCode: 'NOT_ENROLLED',\n        when: 'Learner is not enrolled in the course',\n      },\n    },\n  },\n  policy: {\n    auth: 'user',\n  },\n});\n\n/**\n * Submit a card review.\n */\nexport const SubmitCardReviewContract = defineCommand({\n  meta: {\n    key: 'learning.submitCardReview',\n    version: 1,\n    stability: 'stable',\n    owners: [...LEARNING_JOURNEY_OWNERS],\n    tags: ['learning', 'flashcards'],\n    description: 'Submit a flashcard review.',\n    goal: 'Record review and update SRS schedule.',\n    context: 'Called when reviewing flashcards.',\n  },\n  io: {\n    input: SubmitCardReviewInput,\n    output: SuccessOutput,\n    errors: {\n      CARD_NOT_FOUND: {\n        description: 'Card does not exist',\n        http: 404,\n        gqlCode: 'CARD_NOT_FOUND',\n        when: 'Card ID is invalid',\n      },\n      INVALID_RATING: {\n        description: 'Invalid rating',\n        http: 400,\n        gqlCode: 'INVALID_RATING',\n        when: 'Rating must be AGAIN, HARD, GOOD, or EASY',\n      },\n    },\n  },\n  policy: {\n    auth: 'user',\n  },\n});\n\n/**\n * Get cards due for review.\n */\nexport const GetDueCardsContract = defineQuery({\n  meta: {\n    key: 'learning.getDueCards',\n    version: 1,\n    stability: 'stable',\n    owners: [...LEARNING_JOURNEY_OWNERS],\n    tags: ['learning', 'flashcards'],\n    description: 'Get flashcards due for review.',\n    goal: 'Get the next batch of cards to review.',\n    context: 'Called when starting a review session.',\n  },\n  io: {\n    input: GetDueCardsInput,\n    output: GetDueCardsOutput,\n  },\n  policy: {\n    auth: 'user',\n  },\n});\n\n/**\n * Get learner dashboard.\n */\nexport const GetLearnerDashboardContract = defineQuery({\n  meta: {\n    key: 'learning.getDashboard',\n    version: 1,\n    stability: 'stable',\n    owners: [...LEARNING_JOURNEY_OWNERS],\n    tags: ['learning', 'dashboard'],\n    description: 'Get learner dashboard data.',\n    goal: 'Display learner progress and stats.',\n    context: 'Called when viewing the learning dashboard.',\n  },\n  io: {\n    input: GetLearnerDashboardInput,\n    output: LearnerDashboardModel,\n  },\n  policy: {\n    auth: 'user',\n  },\n});\n"],"mappings":";;;;;;;;AAkBA,MAAa,yBAAyB,cAAc;CAClD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,GAAG,wBAAwB;EACpC,MAAM,CAAC,YAAY,aAAa;EAChC,aAAa;EACb,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACR,QAAQ;GACN,kBAAkB;IAChB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,kBAAkB;IAChB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACF;EACF;CACD,QAAQ,EACN,MAAM,QACP;CACF,CAAC;;;;AAKF,MAAa,yBAAyB,cAAc;CAClD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,GAAG,wBAAwB;EACpC,MAAM,CAAC,YAAY,WAAW;EAC9B,aAAa;EACb,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACR,QAAQ;GACN,kBAAkB;IAChB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,cAAc;IACZ,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACF;EACF;CACD,QAAQ,EACN,MAAM,QACP;CACF,CAAC;;;;AAKF,MAAa,2BAA2B,cAAc;CACpD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,GAAG,wBAAwB;EACpC,MAAM,CAAC,YAAY,aAAa;EAChC,aAAa;EACb,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACR,QAAQ;GACN,gBAAgB;IACd,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,gBAAgB;IACd,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACF;EACF;CACD,QAAQ,EACN,MAAM,QACP;CACF,CAAC;;;;AAKF,MAAa,sBAAsB,YAAY;CAC7C,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,GAAG,wBAAwB;EACpC,MAAM,CAAC,YAAY,aAAa;EAChC,aAAa;EACb,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACT;CACD,QAAQ,EACN,MAAM,QACP;CACF,CAAC;;;;AAKF,MAAa,8BAA8B,YAAY;CACrD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,GAAG,wBAAwB;EACpC,MAAM,CAAC,YAAY,YAAY;EAC/B,aAAa;EACb,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACT;CACD,QAAQ,EACN,MAAM,QACP;CACF,CAAC"}

package/dist/contracts/shared.d.ts

@@ -0,0 +1,5 @@
+//#region src/contracts/shared.d.ts
+declare const LEARNING_JOURNEY_OWNERS: readonly ["modules.learning-journey"];
+//#endregion
+export { LEARNING_JOURNEY_OWNERS };
+//# sourceMappingURL=shared.d.ts.map

package/dist/contracts/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","names":[],"sources":["../../src/contracts/shared.ts"],"sourcesContent":[],"mappings":";cAAa"}

package/dist/contracts/shared.js

@@ -0,0 +1,6 @@
+//#region src/contracts/shared.ts
+const LEARNING_JOURNEY_OWNERS = ["modules.learning-journey"];
+
+//#endregion
+export { LEARNING_JOURNEY_OWNERS };
+//# sourceMappingURL=shared.js.map

package/dist/contracts/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","names":[],"sources":["../../src/contracts/shared.ts"],"sourcesContent":["export const LEARNING_JOURNEY_OWNERS = ['modules.learning-journey'] as const;\n"],"mappings":";AAAA,MAAa,0BAA0B,CAAC,2BAA2B"}

package/dist/docs/index.d.ts

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

package/dist/docs/index.js

@@ -0,0 +1 @@
+import "./learning-journey.docblock.js";

package/dist/docs/learning-journey.docblock.d.ts

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

package/dist/docs/learning-journey.docblock.js

@@ -0,0 +1,136 @@
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/learning-journey.docblock.ts
+registerDocBlocks([
+	{
+		id: "docs.learning-journey.engine",
+		title: "Learning Journey Engine",
+		summary: "Tracks learners, tracks/modules/steps, progress, quizzes, streaks, XP, and AI coaching hooks for product-integrated onboarding.",
+		kind: "reference",
+		visibility: "public",
+		route: "/docs/learning-journey/engine",
+		tags: [
+			"learning",
+			"onboarding",
+			"journey",
+			"education"
+		],
+		body: `## Capabilities
+
+- **Entities**: Learner, Track, Module, Step, Progress, Quiz, Flashcard, AI Coach, Gamification (XP, streaks, badges).
+- **Contracts**: enroll/resume/advance steps, complete quizzes, record streaks, assign XP, fetch progress dashboards, onboarding list/progress/recordEvent.
+- **Engines**: spaced-repetition (SRS), streak calculator, XP progression.
+- **Events**: learner.enrolled, step.completed, quiz.scored, streak.reset, xp.awarded, onboarding.started/completed/step_completed.
+
+## Completion conditions
+- Event-based: name/version/source + payload filter
+- Count-based: require N events (optional time window)
+- Time-bounded: must complete within a window; steps can unlock by day/hour
+- SRS mastery: complete when cards/skills hit mastery thresholds (with required counts)
+
+## Usage
+
+1) Compose schema
+- Include \`learningJourneySchemaContribution\` (entities export) in composition.
+
+2) Register contracts/events
+- Import from \`@contractspec/module.learning-journey\` into your spec registry.
+
+3) Bind to product actions
+- Tie \`Step\` completion conditions to domain events (e.g., deal.created, agent.run.completed, drill.session.completed).
+- Trigger notifications via Notification Center and audits on completion.
+
+4) Gamification
+- Use \`XP\` and \`Streak\` engines to update learner stats; emit analytics for UI.
+
+## Example
+
+\`\`\`ts
+import { learningJourneyEntities } from '@contractspec/module.learning-journey';
+import { StreakEngine } from '@contractspec/module.learning-journey/engines';
+
+const streak = new StreakEngine({ graceDays: 1 });
+const updated = streak.compute({ lastActiveAt: new Date(), today: new Date() });
+\`\`\`,
+
+## Guardrails
+
+- Keep steps bound to real product events, not just button clicks.
+- Avoid storing PII in content; keep org/user scoping for multi-tenant isolation.
+- Emit analytics and audit logs for completions; respect \`prefers-reduced-motion\` in UIs consuming these specs.
+- Track completion bonuses: \`completionXpBonus\`, \`completionBadgeKey\`, optional \`streakHoursWindow\` + \`streakBonusXp\`.
+`
+	},
+	{
+		id: "docs.learning-journey.goal",
+		title: "Learning Journey — Goal",
+		summary: "Why the learning journey engine exists and the outcomes it targets.",
+		kind: "goal",
+		visibility: "public",
+		route: "/docs/learning-journey/goal",
+		tags: ["learning", "goal"],
+		body: `## Why it matters
+- Provides a regenerable onboarding/education engine tied to product signals.
+- Keeps tracks, steps, quizzes, and gamification consistent across surfaces.
+
+## Business/Product goal
+- Drive activation and retention with measurable progress, SRS, and streaks.
+- Allow product teams to adjust journeys safely via specs.
+
+## Success criteria
+- Journey changes regenerate UI/API/events without drift.
+- Analytics/audit hooks exist for completions and streaks.`
+	},
+	{
+		id: "docs.learning-journey.usage",
+		title: "Learning Journey — Usage",
+		summary: "How to compose, bind, and regenerate journeys safely.",
+		kind: "usage",
+		visibility: "public",
+		route: "/docs/learning-journey/usage",
+		tags: ["learning", "usage"],
+		body: `## Setup
+1) Include \`learningJourneyEntities\` in schema composition.
+2) Register contracts/events from \`@contractspec/module.learning-journey\`.
+3) Bind steps to real product events (e.g., deal.created, run.completed).
+
+## Extend & regenerate
+1) Update track/module/step definitions or quiz schemas in spec.
+2) Regenerate to sync UI/API/events; mark PII paths where needed.
+3) Use Feature Flags to trial new tracks or streak rules.
+
+## Guardrails
+- Avoid hardcoded progression; keep engines declarative.
+- Emit analytics/audit for completions; respect user locale/accessibility in presentations.
+- Keep content free of PII; scope learners by org/tenant.`
+	},
+	{
+		id: "docs.learning-journey.constraints",
+		title: "Learning Journey — Constraints & Safety",
+		summary: "Internal guardrails for progression, telemetry, and regeneration semantics.",
+		kind: "reference",
+		visibility: "internal",
+		route: "/docs/learning-journey/constraints",
+		tags: [
+			"learning",
+			"constraints",
+			"internal"
+		],
+		body: `## Constraints
+- Progression (tracks/modules/steps) and engines (SRS, streaks, XP) must stay declarative in spec.
+- Events to emit: learner.enrolled, step.completed, quiz.scored, streak.reset, xp.awarded.
+- Regeneration should not change scoring/streak rules without explicit spec change.
+
+## PII & Telemetry
+- Mark PII (learner identifiers) and redact in presentations; keep telemetry aggregated when possible.
+- Respect accessibility (prefers-reduced-motion) in UIs consuming these specs.
+
+## Verification
+- Add fixtures for streak/XP rule changes and quiz scoring.
+- Ensure Notifications/Audit wiring persists for completions; analytics emitted for progress.
+- Use Feature Flags to trial new tracks or reward rules; default safe/off.`
+	}
+]);
+
+//#endregion
+//# sourceMappingURL=learning-journey.docblock.js.map

package/dist/docs/learning-journey.docblock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-journey.docblock.js","names":[],"sources":["../../src/docs/learning-journey.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@contractspec/lib.contracts/docs';\nimport { registerDocBlocks } from '@contractspec/lib.contracts/docs';\n\nconst learningJourneyDocBlocks: DocBlock[] = [\n  {\n    id: 'docs.learning-journey.engine',\n    title: 'Learning Journey Engine',\n    summary:\n      'Tracks learners, tracks/modules/steps, progress, quizzes, streaks, XP, and AI coaching hooks for product-integrated onboarding.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/learning-journey/engine',\n    tags: ['learning', 'onboarding', 'journey', 'education'],\n    body: `## Capabilities\n\n- **Entities**: Learner, Track, Module, Step, Progress, Quiz, Flashcard, AI Coach, Gamification (XP, streaks, badges).\n- **Contracts**: enroll/resume/advance steps, complete quizzes, record streaks, assign XP, fetch progress dashboards, onboarding list/progress/recordEvent.\n- **Engines**: spaced-repetition (SRS), streak calculator, XP progression.\n- **Events**: learner.enrolled, step.completed, quiz.scored, streak.reset, xp.awarded, onboarding.started/completed/step_completed.\n\n## Completion conditions\n- Event-based: name/version/source + payload filter\n- Count-based: require N events (optional time window)\n- Time-bounded: must complete within a window; steps can unlock by day/hour\n- SRS mastery: complete when cards/skills hit mastery thresholds (with required counts)\n\n## Usage\n\n1) Compose schema\n- Include \\`learningJourneySchemaContribution\\` (entities export) in composition.\n\n2) Register contracts/events\n- Import from \\`@contractspec/module.learning-journey\\` into your spec registry.\n\n3) Bind to product actions\n- Tie \\`Step\\` completion conditions to domain events (e.g., deal.created, agent.run.completed, drill.session.completed).\n- Trigger notifications via Notification Center and audits on completion.\n\n4) Gamification\n- Use \\`XP\\` and \\`Streak\\` engines to update learner stats; emit analytics for UI.\n\n## Example\n\n${'```'}ts\nimport { learningJourneyEntities } from '@contractspec/module.learning-journey';\nimport { StreakEngine } from '@contractspec/module.learning-journey/engines';\n\nconst streak = new StreakEngine({ graceDays: 1 });\nconst updated = streak.compute({ lastActiveAt: new Date(), today: new Date() });\n${'```'},\n\n## Guardrails\n\n- Keep steps bound to real product events, not just button clicks.\n- Avoid storing PII in content; keep org/user scoping for multi-tenant isolation.\n- Emit analytics and audit logs for completions; respect \\`prefers-reduced-motion\\` in UIs consuming these specs.\n- Track completion bonuses: \\`completionXpBonus\\`, \\`completionBadgeKey\\`, optional \\`streakHoursWindow\\` + \\`streakBonusXp\\`.\n`,\n  },\n  {\n    id: 'docs.learning-journey.goal',\n    title: 'Learning Journey — Goal',\n    summary:\n      'Why the learning journey engine exists and the outcomes it targets.',\n    kind: 'goal',\n    visibility: 'public',\n    route: '/docs/learning-journey/goal',\n    tags: ['learning', 'goal'],\n    body: `## Why it matters\n- Provides a regenerable onboarding/education engine tied to product signals.\n- Keeps tracks, steps, quizzes, and gamification consistent across surfaces.\n\n## Business/Product goal\n- Drive activation and retention with measurable progress, SRS, and streaks.\n- Allow product teams to adjust journeys safely via specs.\n\n## Success criteria\n- Journey changes regenerate UI/API/events without drift.\n- Analytics/audit hooks exist for completions and streaks.`,\n  },\n  {\n    id: 'docs.learning-journey.usage',\n    title: 'Learning Journey — Usage',\n    summary: 'How to compose, bind, and regenerate journeys safely.',\n    kind: 'usage',\n    visibility: 'public',\n    route: '/docs/learning-journey/usage',\n    tags: ['learning', 'usage'],\n    body: `## Setup\n1) Include \\`learningJourneyEntities\\` in schema composition.\n2) Register contracts/events from \\`@contractspec/module.learning-journey\\`.\n3) Bind steps to real product events (e.g., deal.created, run.completed).\n\n## Extend & regenerate\n1) Update track/module/step definitions or quiz schemas in spec.\n2) Regenerate to sync UI/API/events; mark PII paths where needed.\n3) Use Feature Flags to trial new tracks or streak rules.\n\n## Guardrails\n- Avoid hardcoded progression; keep engines declarative.\n- Emit analytics/audit for completions; respect user locale/accessibility in presentations.\n- Keep content free of PII; scope learners by org/tenant.`,\n  },\n  {\n    id: 'docs.learning-journey.constraints',\n    title: 'Learning Journey — Constraints & Safety',\n    summary:\n      'Internal guardrails for progression, telemetry, and regeneration semantics.',\n    kind: 'reference',\n    visibility: 'internal',\n    route: '/docs/learning-journey/constraints',\n    tags: ['learning', 'constraints', 'internal'],\n    body: `## Constraints\n- Progression (tracks/modules/steps) and engines (SRS, streaks, XP) must stay declarative in spec.\n- Events to emit: learner.enrolled, step.completed, quiz.scored, streak.reset, xp.awarded.\n- Regeneration should not change scoring/streak rules without explicit spec change.\n\n## PII & Telemetry\n- Mark PII (learner identifiers) and redact in presentations; keep telemetry aggregated when possible.\n- Respect accessibility (prefers-reduced-motion) in UIs consuming these specs.\n\n## Verification\n- Add fixtures for streak/XP rule changes and quiz scoring.\n- Ensure Notifications/Audit wiring persists for completions; analytics emitted for progress.\n- Use Feature Flags to trial new tracks or reward rules; default safe/off.`,\n  },\n];\n\nregisterDocBlocks(learningJourneyDocBlocks);\n"],"mappings":";;;AAgIA,kBA7H6C;CAC3C;EACE,IAAI;EACJ,OAAO;EACP,SACE;EACF,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAY;GAAc;GAAW;GAAY;EACxD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6CP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SACE;EACF,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM,CAAC,YAAY,OAAO;EAC1B,MAAM;;;;;;;;;;;EAWP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SAAS;EACT,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM,CAAC,YAAY,QAAQ;EAC3B,MAAM;;;;;;;;;;;;;;EAcP;CACD;EACE,IAAI;EACJ,OAAO;EACP,SACE;EACF,MAAM;EACN,YAAY;EACZ,OAAO;EACP,MAAM;GAAC;GAAY;GAAe;GAAW;EAC7C,MAAM;;;;;;;;;;;;;EAaP;CACF,CAE0C"}

package/dist/engines/index.d.ts

@@ -0,0 +1,4 @@
+import { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine } from "./srs.js";
+import { DEFAULT_XP_CONFIG, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, xpEngine } from "./xp.js";
+import { DEFAULT_STREAK_CONFIG, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, streakEngine } from "./streak.js";
+export { CardRating, DEFAULT_SRS_CONFIG, DEFAULT_STREAK_CONFIG, DEFAULT_XP_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, srsEngine, streakEngine, xpEngine };

package/dist/engines/index.js

@@ -0,0 +1,5 @@
+import { DEFAULT_SRS_CONFIG, SRSEngine, srsEngine } from "./srs.js";
+import { DEFAULT_XP_CONFIG, XPEngine, xpEngine } from "./xp.js";
+import { DEFAULT_STREAK_CONFIG, StreakEngine, streakEngine } from "./streak.js";
+
+export { DEFAULT_SRS_CONFIG, DEFAULT_STREAK_CONFIG, DEFAULT_XP_CONFIG, SRSEngine, StreakEngine, XPEngine, srsEngine, streakEngine, xpEngine };

package/dist/engines/srs.d.ts

@@ -0,0 +1,111 @@
+//#region src/engines/srs.d.ts
+/**
+ * Spaced Repetition System (SRS) Engine
+ *
+ * Implements the SM-2 algorithm variant for optimal flashcard scheduling.
+ *
+ * The algorithm calculates the optimal time to review a card based on:
+ * - User's rating of recall difficulty (again, hard, good, easy)
+ * - Current interval between reviews
+ * - Ease factor (how easy the card is for this user)
+ * - Number of successful repetitions
+ */
+type CardRating = 'AGAIN' | 'HARD' | 'GOOD' | 'EASY';
+interface SRSState {
+  /** Current interval in days */
+  interval: number;
+  /** Ease factor (typically 1.3 to 2.5+) */
+  easeFactor: number;
+  /** Number of successful repetitions */
+  repetitions: number;
+  /** Current learning step (for new cards) */
+  learningStep: number;
+  /** Whether card has graduated to review phase */
+  isGraduated: boolean;
+  /** Whether card is being relearned after a lapse */
+  isRelearning: boolean;
+  /** Number of times card was forgotten */
+  lapses: number;
+}
+interface ReviewResult {
+  /** New interval in days */
+  interval: number;
+  /** New ease factor */
+  easeFactor: number;
+  /** New repetition count */
+  repetitions: number;
+  /** Next review date */
+  nextReviewAt: Date;
+  /** New learning step */
+  learningStep: number;
+  /** Whether card has graduated */
+  isGraduated: boolean;
+  /** Whether card is being relearned */
+  isRelearning: boolean;
+  /** Updated lapse count */
+  lapses: number;
+}
+interface SRSConfig {
+  /** Learning steps in minutes [1, 10] = 1 min, 10 min */
+  learningSteps: number[];
+  /** Graduating interval in days */
+  graduatingInterval: number;
+  /** Easy interval (for easy button on new cards) */
+  easyInterval: number;
+  /** Relearning steps in minutes */
+  relearningSteps: number[];
+  /** Minimum ease factor */
+  minEaseFactor: number;
+  /** Maximum interval in days */
+  maxInterval: number;
+  /** Interval modifier (1.0 = 100%) */
+  intervalModifier: number;
+  /** New cards interval modifier */
+  newIntervalModifier: number;
+  /** Hard interval modifier */
+  hardIntervalModifier: number;
+  /** Easy bonus modifier */
+  easyBonus: number;
+}
+declare const DEFAULT_SRS_CONFIG: SRSConfig;
+declare class SRSEngine {
+  private config;
+  constructor(config?: Partial<SRSConfig>);
+  /**
+   * Calculate the next review state based on rating.
+   */
+  calculateNextReview(state: SRSState, rating: CardRating, now?: Date): ReviewResult;
+  /**
+   * Get initial SRS state for a new card.
+   */
+  getInitialState(): SRSState;
+  /**
+   * Check if a card is due for review.
+   */
+  isDue(nextReviewAt: Date, now?: Date): boolean;
+  /**
+   * Calculate overdue days (negative if not yet due).
+   */
+  getOverdueDays(nextReviewAt: Date, now?: Date): number;
+  /**
+   * Handle learning phase (new cards).
+   */
+  private handleLearningCard;
+  /**
+   * Handle relearning phase (lapsed cards).
+   */
+  private handleRelearningCard;
+  /**
+   * Handle review phase (graduated cards).
+   */
+  private handleReviewCard;
+  private addMinutes;
+  private addDays;
+}
+/**
+ * Default SRS engine instance.
+ */
+declare const srsEngine: SRSEngine;
+//#endregion
+export { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine };
+//# sourceMappingURL=srs.d.ts.map

package/dist/engines/srs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"srs.d.ts","names":[],"sources":["../../src/engines/srs.ts"],"sourcesContent":[],"mappings":";;AAcA;AAEA;AAiBA;AAmBA;AAyBA;AAeA;;;;;AAaS,KA3FG,UAAA,GA2FH,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,MAAA;AACJ,UA1FY,QAAA,CA0FZ;EAkBgB;EAeC,QAAA,EAAA,MAAA;EAAW;EAOF,UAAA,EAAA,MAAA;EAAW;EAAiB,WAAA,EAAA,MAAA;EA4O9C;;;;;;;;;UA7VI,YAAA;;;;;;;;gBAQD;;;;;;;;;;UAWC,SAAA;;;;;;;;;;;;;;;;;;;;;;cAyBJ,oBAAoB;cAepB,SAAA;;uBAGS,QAAQ;;;;6BAQnB,kBACC,kBACH,OACJ;;;;qBAkBgB;;;;sBAeC,YAAW;;;;+BAOF,YAAW;;;;;;;;;;;;;;;;;;;cA4O7B,WAAS"}