@contractspec/module.learning-journey 1.57.0 → 1.58.0

package/dist/contracts/operations.js

@@ -1,151 +1,327 @@
-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";
+// @bun
+// src/contracts/shared.ts
+var LEARNING_JOURNEY_OWNERS = ["modules.learning-journey"];
 
-//#region src/contracts/operations.ts
-/**
-* Enroll in a course.
-*/
-const EnrollInCourseContract = defineCommand({
-	meta: {
-		key: "learning.enroll",
-		version: "1.0.0",
-		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.0.0",
-		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.0.0",
-		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.0.0",
-		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.0.0",
-		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" }
+// src/contracts/models.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+var CourseModel = defineSchemaModel({
+  name: "Course",
+  description: "A learning course",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    slug: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    difficulty: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    estimatedDuration: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    thumbnailUrl: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var LearnerModel = defineSchemaModel({
+  name: "Learner",
+  description: "A learner profile",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    userId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    displayName: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    level: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    longestStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var EnrollmentModel = defineSchemaModel({
+  name: "Enrollment",
+  description: "A course enrollment",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var ProgressModel = defineSchemaModel({
+  name: "LessonProgress",
+  description: "Lesson progress",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    progress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    completedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var DeckModel = defineSchemaModel({
+  name: "Deck",
+  description: "A flashcard deck",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    cardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    isPublic: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var CardModel = defineSchemaModel({
+  name: "Card",
+  description: "A flashcard",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    front: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    back: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    hints: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    isDue: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    nextReviewAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var AchievementModel = defineSchemaModel({
+  name: "Achievement",
+  description: "An achievement",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    icon: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    unlockedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var EnrollInCourseInput = defineSchemaModel({
+  name: "EnrollInCourseInput",
+  description: "Input for enrolling in a course",
+  fields: {
+    courseId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var CompleteLessonInput = defineSchemaModel({
+  name: "CompleteLessonInput",
+  description: "Input for completing a lesson",
+  fields: {
+    lessonId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    score: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    timeSpent: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var SubmitCardReviewInput = defineSchemaModel({
+  name: "SubmitCardReviewInput",
+  description: "Input for submitting a card review",
+  fields: {
+    cardId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    rating: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    responseTimeMs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetDueCardsInput = defineSchemaModel({
+  name: "GetDueCardsInput",
+  description: "Input for getting due cards",
+  fields: {
+    deckId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetDueCardsOutput = defineSchemaModel({
+  name: "GetDueCardsOutput",
+  description: "Output for getting due cards",
+  fields: {
+    cards: { type: CardModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var GetLearnerDashboardInput = defineSchemaModel({
+  name: "GetLearnerDashboardInput",
+  description: "Input for getting learner dashboard",
+  fields: {
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var LearnerDashboardModel = defineSchemaModel({
+  name: "LearnerDashboard",
+  description: "Learner dashboard data",
+  fields: {
+    learner: { type: LearnerModel, isOptional: false },
+    currentStreak: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    dailyXpGoal: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    dailyXpProgress: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    activeEnrollments: {
+      type: EnrollmentModel,
+      isArray: true,
+      isOptional: false
+    },
+    recentAchievements: {
+      type: AchievementModel,
+      isArray: true,
+      isOptional: false
+    },
+    dueCardCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var SuccessOutput = defineSchemaModel({
+  name: "SuccessOutput",
+  description: "Generic success output",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    xpEarned: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
 });
 
-//#endregion
-export { CompleteLessonContract, EnrollInCourseContract, GetDueCardsContract, GetLearnerDashboardContract, SubmitCardReviewContract };
-//# sourceMappingURL=operations.js.map
+// src/contracts/operations.ts
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var EnrollInCourseContract = defineCommand({
+  meta: {
+    key: "learning.enroll",
+    version: "1.0.0",
+    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"
+  }
+});
+var CompleteLessonContract = defineCommand({
+  meta: {
+    key: "learning.completeLesson",
+    version: "1.0.0",
+    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"
+  }
+});
+var SubmitCardReviewContract = defineCommand({
+  meta: {
+    key: "learning.submitCardReview",
+    version: "1.0.0",
+    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"
+  }
+});
+var GetDueCardsContract = defineQuery({
+  meta: {
+    key: "learning.getDueCards",
+    version: "1.0.0",
+    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"
+  }
+});
+var GetLearnerDashboardContract = defineQuery({
+  meta: {
+    key: "learning.getDashboard",
+    version: "1.0.0",
+    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"
+  }
+});
+export {
+  SubmitCardReviewContract,
+  GetLearnerDashboardContract,
+  GetDueCardsContract,
+  EnrollInCourseContract,
+  CompleteLessonContract
+};

package/dist/contracts/shared.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","names":[],"sources":["../../src/contracts/shared.ts"],"mappings":";cAAa,uBAAA"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/contracts/shared.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,uCAAwC,CAAC"}

package/dist/contracts/shared.js

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

package/dist/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './learning-journey.docblock';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,6BAA6B,CAAC"}

package/dist/docs/index.js

@@ -1 +1,125 @@
-import "./learning-journey.docblock.js";
+// @bun
+// src/docs/learning-journey.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var learningJourneyDocBlocks = [
+  {
+    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 \u2014 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 \u2014 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 \u2014 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.`
+  }
+];
+registerDocBlocks(learningJourneyDocBlocks);

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

@@ -1 +1,2 @@
-export { };
+export {};
+//# sourceMappingURL=learning-journey.docblock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"learning-journey.docblock.d.ts","sourceRoot":"","sources":["../../src/docs/learning-journey.docblock.ts"],"names":[],"mappings":""}