@happyvertical/smrt-education 0.57.49 → 0.57.51

package/README.md

@@ -109,7 +109,12 @@ host setting and optional evidence submission; guardian `attestLesson` is
 unchanged. `setEnrollmentPace` sets or clears an enrollment's planned lessons
 per week (1 to 14) under the host's `education.enrollment.set-pace` decision with
 an immutable change row, and `nextLessons({ count })` returns a week's set of
-unfinished lessons (default one).
+unfinished lessons (default one). `setInterestTheme` stores a learner's interest
+theme (a short plain label and an optional stable key such as `minecraft`; the
+host owns its starter list) under `education.learner.set-interest-theme`: a
+guardian may set any of their learners' themes, a learner only their own
+(the host decides), nobody another learner's. Each change appends an immutable
+row; `getLearner` and the tutor context read it back.
 `TutorContextService.compose` builds a bounded, learner-safe `TutorContext`
 (lesson text, learner-visible questions, own progress, released feedback; for the
 learner audience only `answerKeyAvailable`, never keys, rubrics, notes or storage
@@ -123,6 +128,18 @@ or file set under hard size, ratio, path and entry bounds, keeps unsupported and
 duplicate members as append-only evidence, hands accepted members to ingestion and
 proposes sections and lessons through `CourseGenerationReviewService`; see
 [bundle import](agents/course-bundle-import.md).
+`requestGeneration` also accepts a structured `brief` (subject, category, area,
+grade, objective, a `course` or one-`lesson` target and a per-request interest
+theme that beats the learner's saved theme for that request only); the theme used
+and whether it was an override show on the guardian's review, and `release`
+accepts a `policyBasis` so a host can honour its own approve-requested-lessons
+setting without bypassing the review gate; see
+[generation and review](agents/course-generation-review.md).
+`CourseAuthoringService.appendLesson` adds one lesson (materials and question
+records included) to a released course as a new, optionally released revision:
+append-only, idempotent by request key, refused on archived, unreleased or
+foreign courses; enrollments stay on their pinned release until the host
+upgrades them; see [course authoring](agents/course-authoring-service.md).
 Repeated starts preserve the existing progress, including attempts and scores.
 A new curriculum/year creates a distinct enrollment and fresh progress history.
 An unscored lesson has `bestScore: null`, distinct from zero. The service does

package/agents/course-authoring-service.md

@@ -78,6 +78,45 @@ lesson identity; `Lesson.externalRef` and `ReleasedLesson` carry the stable
 lesson identity for progress/reporting. Learners on different releases never
 share mutable rows. Personal-use releases stay `draft` status (the existing rule).
 
+## Append a lesson to a released course
+
+`appendLesson({ courseId, expectedHeadRevisionId, requestKey, sectionKey,
+sectionTitle?, lesson, release?, policyBasis? })` adds exactly one lesson (a
+`CourseLessonInput` with a required `lessonKey`, its `materials` and `questions`
+exactly as `saveDraft` takes them) to a course that already has a release, as one
+new revision, and releases that revision in the same transaction (`release:
+false` only appends). Returns `CourseAppendLessonView` (`revisionId`, `version`,
+`lessonKey`, `release | null`). Host mapping: action `education.course.author`,
+operation `append-lesson` (also `generate` for generated provenance), and, when
+releasing, `education.course.release` with the usual `policyBasis` and delegation
+rules. Hosts that grant `author` but not `release` use `release: false`.
+
+- **Append-only.** The new revision is the head plus the lesson at the end of
+  `sectionKey` (a new section needs `sectionTitle`). No lesson, revision or release
+  is changed; the release is a new Course row with the next release number.
+- **Refused.** Unknown or foreign-tenant course (`CourseNotFoundError`), discarded,
+  archived (`CourseArchivedError`), no release yet (`CourseAppendRefusedError`
+  `not-released`), head with changes that were never released (`unreleased-changes`:
+  nothing unreviewed rides along; release or discard it first), `lessonKey` already
+  in the course (`duplicate-lesson`), stale `expectedHeadRevisionId`
+  (`CourseStaleHeadError`).
+- **Review gate.** Releasing goes through the injected `releaseReviewGate` unchanged.
+  The default review-backed gate needs a current review of the new revision, which
+  cannot exist before it does, so with that gate use `release: false`, `recordReview`,
+  then `release`. A host whose gate honours its own approval (the guardian already
+  approved the requested lesson) can release in the one call. A gate that is not
+  current rolls the append back entirely.
+- **Idempotent.** The same `requestKey` and request replays the original result, also
+  after the head moved (a no-op: no revision, release or lesson rows); a changed lesson
+  or section or release intent (`release` true versus false) under the same key is
+  `CourseRequestKeyConflictError`; publish a `release: false` append later with
+  `release` and its own key.
+- **Enrollment pins.** Existing enrollments keep their pinned release and so never see
+  the new lesson implicitly. The host advances them with `upgradeEnrollment` on the new
+  release (explicit, recorded), or an enrollment/course that opted in with
+  `setAutoUpgrade` is moved by the release exactly as for any release (unstarted
+  lessons follow, started lessons stay on their row). Nothing else moves a pin.
+
 ## Enrollment pin and upgrades
 
 `Enrollment` is untouched (its `courseId` stays immutable): enroll through

package/agents/course-generation-review.md

@@ -40,6 +40,59 @@ a revision on `expectedHeadRevisionId` and records the decision; supplied conten
 is replaced only that way. Never write generated content to a released revision or
 assign it to a learner.
 
+## Structured requests and one-lesson generation
+
+`requestGeneration` also takes an optional `brief` (`CourseGenerationBriefInput`)
+next to the free `instruction`: `target` (`'course'`, the default and today's
+behaviour, or `'lesson'`), `subject`, `category`, `area`, `grade` (whole 0-12),
+`objective`, `learningObjectiveId`, `learnerId` and a per-request `theme`
+(`{ label, key? }`). Text is bounded and sent to the provider as data. A request
+without `brief` behaves exactly as before and `brief` reads back `null`.
+
+- **Objective.** A `lesson` target needs an objective (`objective`, else `area`);
+  without one `CourseGenerationBriefError` is thrown before anything is written.
+  The objective is stored on the job's `CourseGenerationBriefRecord`, sent in the
+  generation brief as fixed, and copied verbatim onto the proposed lesson. The
+  theme changes story and examples only: output that states a different
+  objective fails the job (`CourseGenerationOutputError`).
+- **Theme.** The per-request `theme` is an override that wins for that request
+  only. Without one the learner's saved `interestTheme` (read-only, from
+  `brief.learnerId`) applies; with neither there is no theme. The brief records
+  `theme` and `themeSource` (`'override' | 'saved' | 'none'`) at request time, and
+  `CourseGenerationView.brief` / `CourseProposalView.brief` show it to the
+  guardian reviewing. Nothing in generation writes to the learner, so the saved
+  preference is never changed, on success or failure.
+- **Authority.** The host authorizer is asked for `education.course.generate`
+  with `learnerId` in the context so it can enforce its own "may this learner ask
+  for a lesson" policy; an unknown or foreign-tenant learner is `CourseNotFoundError`.
+  The package does not check the requester's relationship to `brief.learnerId` (the
+  brief echoes that learner's saved theme): the host authorizer MUST deny `generate`
+  when the actor is not that learner or a guardian with an effective relationship, as
+  it does for `assign`.
+  Replaying a request key with the same brief returns the same job; a changed
+  brief is `CourseRequestKeyConflictError`.
+- **Output.** For `lesson` the generator is given `request.brief` and
+  `COURSE_LESSON_PROPOSAL_ARGS_SCHEMA` (via `createProposalCourseGenerator`):
+  exactly one new lesson with `title`, `body` (the themed explanation) and
+  `questions` (worksheet; every question needs an `answerKey`), and no course-level
+  fields. The worksheet becomes immutable question records, linked to
+  `learningObjectiveId`, in the same transaction as the draft revision; answer keys
+  stay out of learner views. Review, `decideProposal` and release are unchanged.
+- **Approving requested lessons.** The package has no per-learner setting. To honour
+  the host's own "approve requested lessons" setting without bypassing authority,
+  the host calls `recordReview` then `release` under the guardian delegation as for
+  any course, passing `policyBasis` (for example `'auto-approve-requested-lessons'`)
+  to `release`, or returning `policyBasis` from its authorizer decision (the two
+  must agree). The basis is recorded on `CourseRelease.policyBasis` and
+  `CourseReleaseView.policyBasis`; it grants nothing and the review gate, the
+  `education.course.release` grant and the delegation check still apply. The
+  explicit alternative, a guardian approving each lesson, is the existing
+  `recordReview` plus `release` by the guardian.
+
+Additive schema: table `course_generation_briefs` and column
+`course_releases.policy_basis`. On a host without the table, plain requests still
+work and structured ones fail closed with `schema-unavailable`.
+
 ## Review
 
 `recordReview` (action `education.course.review`) binds to an exact revision and a

package/agents/learner-service.md

@@ -131,6 +131,26 @@ Same-tenant membership alone never grants sibling access.
   without `enrollment_pace_changes` gets `LearnerHistoryUnavailableError`.
   Apply the additive migration (new column plus table) before deploying writes;
   reads of an un-migrated table report no pace.
+- `setInterestTheme({ theme: { label, key? } | null, policyBasis })` stores the
+  learner's interest theme under `education.learner.set-interest-theme`. The
+  label is a short plain string (1-60 characters after whitespace is collapsed;
+  control characters, `@`, `://` and `www.` are refused so it cannot carry
+  contact details) and the optional key is lowercase `[a-z0-9-]` up to 40
+  characters. The package ships no starter list: the host owns its keys
+  (for Hearth `minecraft`, `roman`, `hockey`, `baseball`, `football`, `soccer`,
+  `cars`) and family-added themes are free labels without a key. A guardian with
+  an effective relationship may set any of their learners' themes; the learner
+  may set their own when the host authorizer answers `own: true` as allowed;
+  another learner's theme needs the actor's own guardian relationship, so a
+  learner, sibling or stranger is refused by the same actor/tenant checks as
+  every other operation. It is a skin for stories and examples only; it never
+  changes an objective. Columns `learners.interest_theme_label` and
+  `interest_theme_key` (additive; empty = none) hold the value and each change
+  appends a `LearnerInterestThemeChange` (actor, `policyBasis`, previous and new
+  value). An unchanged value is `{ changed: false }`; a bad value is
+  `InterestThemeError`; a host without `learner_interest_theme_changes` gets
+  `LearnerHistoryUnavailableError`. `getLearner` returns `interestTheme`
+  (`{ label, key } | null`). Apply the additive migration before deploying.
 - `nextLessons({ enrollmentId?, count? })`: `count` is an integer from 1 to
   14 (`MAX_NEXT_LESSONS_COUNT`, default 1, else `LearnerValidationError`) and
   returns up to that many unfinished (not complete or skipped) lessons per

package/agents/tutor-context.md

@@ -15,7 +15,8 @@ enrollment's effective set; a focus question must belong to that lesson
 (otherwise `LearnerAuthorizationError`). The guardian audience is refused for
 the learner's own actor whatever the host answers.
 
-Result: learner (name, level), enrollment (status, pace; no notes), course,
+Result: learner (name, level, `interestTheme`: the learner-safe label and key or
+null, read-only; never the free `settings`), enrollment (status, pace; no notes), course,
 section and lesson titles, learner-facing lesson body (withheld for
 personal-use-copy), objectives, own progress status, the learner-visible
 question rendering (prompt, response type, choices, subpart prompts, points; no