@happyvertical/smrt-education 0.57.43 → 0.57.44

package/AGENTS.md

@@ -34,6 +34,18 @@ sharing separate from guardian Grade authority. Photo-first receipt/context
 capture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references
 never create learning evidence, and blank exercises need explicit work intent.
 
+Revisioned authored courses, release, archive, enrollment pins and licence use
+[CourseAuthoringService](agents/course-authoring-service.md). Keep history
+append-only, require request keys, and never weaken personal-use-copy rules.
+
+Generation proposals into new draft revisions and revision-bound educational
+review use [CourseGenerationReviewService](agents/course-generation-review.md).
+Keep supplied content unless a decision is recorded; reviews carry no score.
+
+Immutable questions, answer keys/rubrics, stable learning objectives, worksheet
+render ids and exact-revision references use [QuestionAuthoringService](agents/question-records.md).
+Keep keys out of learner bundles; a missing key stays null.
+
 Source import: [host boundary and transaction contract](agents/source-import.md).
 `SourceImportService` requires host opt-in, matching active actor/tenant and
 explicit licensing authorization; never add a system/global write bypass.

package/README.md

@@ -15,6 +15,11 @@ work and revision-bound comments remain retained after leaving a group.
 See the [group sharing contract](agents/group-sharing.md) for the required host
 authorizer, private media delivery, facet semantics and migration/test matrix.
 
+Guardians author courses with `CourseAuthoringService`: append-only course and
+lesson revisions, a reviewed release that materializes immutable lessons,
+reversible archive, and recorded enrollment pins and upgrades. See the
+[course authoring contract](agents/course-authoring-service.md).
+
 ## Install
 
 ```sh

package/agents/course-authoring-service.md

@@ -0,0 +1,179 @@
+# Course authoring contract
+
+`CourseAuthoringService` (SMRT #4514, consumed by Hearth #68) writes revisioned,
+family-owned courses and releases them into the existing Course/Section/Lesson
+shape. Risk is high: tenancy, authorization, new schema and a public contract.
+It is a standalone service (not a `LearnerService` subclass); every write is one
+transaction and every authorizer call receives that transaction's executor.
+
+## Models (closed, required tenant, no REST/CLI/MCP/AI)
+
+`AuthoredCourse` (source key `authored`) stays the stable identity row; it never
+holds content, is never assigned and its licence is never edited. Append-only:
+`CourseRevision`, `LessonRevision` (stable `lessonKey` across versions; an
+unchanged lesson reuses its row), `CourseRelease`, `ReleasedLesson`,
+`CourseArchiveDecision`, `CourseDiscardTombstone`, `EnrollmentReleasePin`,
+`CourseUpgradeChoice`. `CourseDraftHead` is the only mutable row and moves only
+through the service's expected-head compare-and-swap. `save()` on an existing
+append-only row and `delete()` throw; erasure belongs to a retention operation.
+Schema ships via normal manifest migrations (additive: new tables only, no
+change to existing tables, test-pinned); the runtime never creates tables.
+
+## Actions and host mapping
+
+`education.course.read-draft|author|generate|review|release|assign|archive`. The host
+maps roles; the authorizer also receives `operation`, `courseId`,
+`enrollmentId`/`learnerId` and `delegatingGuardianUserId` (agent calls) and must
+re-validate that delegation on the supplied executor. The service checks the
+ambient tenant context, active actor and delegating-guardian membership first.
+`generated` provenance additionally needs `generate`. Releasing and assigning
+are independent grants: `pinEnrollment`, `upgradeEnrollment` and `setAutoUpgrade`
+(operations `pin-enrollment`, `upgrade-enrollment`, `set-auto-upgrade`) use only
+`assign`, never `release`. A host maps `assign` per learner from its assignment
+setting (guardians only, guardians plus agents, learner can ask) using
+`operation`, `enrollmentId`/`learnerId` and `delegatingGuardianUserId`; a
+learner-initiated request is host policy, the service adds no learner authority.
+Archive and discard use `archive`. `generate` and `review` are used by the [generation and review service](course-generation-review.md).
+Foreign or missing courses/enrollments are not-found/denied alike.
+
+Delegated actor: the authenticated actor is the agent; `delegatingGuardianUserId`
+and a host `delegationId` (opaque, 1-200 printable characters) are validated as a
+unit (one without the other is `invalid-request`; the guardian may not be the agent,
+which is denied). Validation grants nothing: the guardian keeps no authority via the
+agent, the host authorizer decides, and both users need active membership. One helper
+(`course-delegation.ts`) builds actor, authorizer and record fields. `delegationId` is
+passed to every authorizer call (all `education.course.*` actions, including the
+per-enrollment `auto-upgrade` call, which gets the opt-in's recorded id) and recorded
+(nullable on views) on revisions, releases, archive/discard, pins, opt-ins, skips
+(`optInDelegationId`; automatic pins also record the opt-in's) and generation, review
+and question records. Request-key replays compare it: another delegation id conflicts.
+Delegation is opt-in and fails closed: `verifyDelegation(executor, { tenantId,
+actorUserId, delegatingGuardianUserId, delegationId, action, operation, courseId?,
+enrollmentId?, learnerId? }) => boolean | { allowed, reason?, code? }` must be set in the
+service options. A delegated request without it, or when it denies or throws, is a
+`CourseAuthoringAuthorizationError` before the host authorizer runs. The per-enrollment
+`auto-upgrade` check re-verifies the opt-in's recorded delegation through the same port
+(on the savepoint executor); a failure skips the move. Plain guardians never need it.
+Assignment (`LearnerService.enroll`) is described in the [learner contract](learner-service.md).
+
+## Writes
+
+Every write requires a `requestKey`. A retried key replays its original result;
+the same key with a different payload throws `CourseRequestKeyConflictError`.
+`saveDraft` takes `expectedHeadRevisionId` and throws `CourseStaleHeadError`
+(with the current head) when stale. Errors extend `CourseAuthoringError` with a
+stable `code`; never match on messages.
+
+## Release
+
+`release` requires an injected `releaseReviewGate(executor, {tenantId, courseId,
+revisionId}) => {current, reviewId?, reason?}`. No gate configured throws
+`ReviewGateRequiredError`; `current !== true` throws `ReviewNotCurrentError`.
+`createReviewBackedReleaseGate()` is the review-backed implementation (the default of
+`CourseGenerationReviewService`; see [generation and review](course-generation-review.md)). The decision records actor,
+delegating guardian and `reviewId`, one release per revision. It materializes a
+release-only `AuthoredCourse` row (source key `authored-release`), sections and
+`Lesson` subclasses whose ids derive deterministically from the revision id and
+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).
+
+## Enrollment pin and upgrades
+
+`Enrollment` is untouched (its `courseId` stays immutable): enroll through
+`LearnerService` on a release's `releaseCourseId`, then `pinEnrollment` records
+the pin. `upgradeEnrollment` appends an explicit move to a newer release.
+`setAutoUpgrade` records an opt-in/out at course or enrollment level (enrollment
+wins) for future releases; each automatic move is a recorded pin without actor. Pin, upgrade and
+`setAutoUpgrade` need a `policyBasis` (the assignment-setting value relied on, e.g.
+`guardians-only`; 1-200 printable chars, else `invalid-request`). The caller's is optional: the
+`assign` authorizer decision may return `policyBasis`, which then wins; both given must be equal
+(`CoursePolicyBasisMismatchError`, `policy-basis-mismatch`) and neither is `invalid-request`; an invalid
+authorizer basis is a validation error, nothing written. The authorizer runs first, also on replays, and
+replays compare the effective basis. Recorded with actor and delegating guardian on the pin or
+choice row and exposed on the views. An automatic move records the per-enrollment `auto-upgrade`
+decision's `policyBasis` (an invalid one denies the move), else the basis of the
+opt-in that governs it (the same for a skip), plus its `optInScope` (`course`|`enrollment`). Each
+automatic move is authorized per enrollment during `release` with action
+`assign`, operation `auto-upgrade`, that `enrollmentId`/`learnerId`, the opt-in's
+recorded actor and delegating guardian (current membership re-checked, the host
+re-evaluates the delegation or relationship) and the transaction executor; hosts
+must map `auto-upgrade` per learner from the assignment setting. A denial or
+authorizer failure (each call runs in a SAVEPOINT, rolled back on a throw, so a failing host statement cannot abort the release transaction) never blocks the release or other enrollments: that
+enrollment stays on its pin and an `EnrollmentAutoUpgradeSkip` row records
+`not-authorized` (or the authorizer's `reason`), the optional `code`, the opt-in scope, actor,
+guardian and `policyBasis`. A replayed
+request key with a different basis is a request-key conflict.
+`EnrollmentPinView` (from `pinEnrollment`, `upgradeEnrollment`, `getEnrollmentRelease`) carries
+`learnerId`, `courseId` (authored identity) and `releaseCourseId` (history rows carry `releaseCourseId`);
+`setAutoUpgrade` returns `learnerId` (null for a course choice). All derive from the enrollment row on the
+server, with no new input: hosts must not read the `enrollments` table: `learnerId` and `courseId` (plus `releaseId`/`releaseCourseId` for pin and upgrade) arrive in the assign authorizer and `verifyDelegation` requests. `getEnrollmentRelease` returns
+`EnrollmentReleaseView` (`learnerId`, `courseId`, `releaseCourseId`, `pin`, `lessons`): after any move
+(automatic or explicit), started lessons stay on the immutable row they were
+started on, unstarted lessons follow the current release. `LearnerService`
+consumes the same rule (see `learner-service.md`).
+
+## Authorizer answers
+
+An authorizer returns `boolean` or `{ allowed, reason?, code? }` (only `allowed: true`
+allows). On an auto-upgrade denial `reason` (at most 200 characters, control characters
+stripped) and `code` (`[a-z0-9._-]`, at most 64; e.g. `assignment-setting`,
+`agent-permission`, `guardian-link`) are stored on the skip; invalid values fall back to
+`not-authorized` and an empty code. A thrown error's message is never recorded. The per-enrollment `verifyDelegation` refusal is recorded the
+same way: an object refusal's `reason`/`code` (same sanitizing); a boolean refusal, a throw or no port
+records the generic `not-authorized` and an empty code.
+
+## Reads
+
+All use `read-draft`, the executor and delegation fields, and are tenant-exact (a foreign
+course is not-found, a foreign enrollment a denial). Lists take `limit` (default 50, capped at
+100) and an opaque `cursor`, and return `{ items, nextCursor }` in a total order.
+- `listCourses({ includeDiscarded? })` (operation `list-courses`): `CourseSummaryView`
+  per course: state, `head` (`revisionId` is the expected-head token), `latestRelease`,
+  `archive`, `licenseKind` (most restrictive of head and every release), `groupShareable`
+  (false for personal-use and until a release exists) and `releaseCount`; hosts need no
+  `getCourse` per row. Oldest first; discarded courses only when requested.
+- `listUpgradeChoices({ courseId, enrollmentId? })` (`list-upgrade-choices`): opt-in/out
+  history in sequence order; with an enrollment, its own rows plus `governing`.
+- `listAutoUpgradeSkips({ courseId?, enrollmentId? })` (`list-auto-upgrade-skips`, one
+  required): `AutoUpgradeSkipView` with `reason`, `code`, opt-in actor/guardian/delegation.
+- `QuestionAuthoringService.readReleasedLesson({ releaseId, lessonKey })`
+  (`read-released-lesson`): lesson revision, layout and the keyed worksheet bundle.
+- `QuestionResponseService.readReleasedLesson({ enrollmentId, lessonId })` (learner
+  authorizer, `education.learner.read`; the learner or an authorized guardian): only the
+  enrollment's effective lessons (else `QuestionResponseScopeError`), keyless bundle,
+  no materials or provenance, personal-use body withheld (`bodyWithheld`).
+
+## Archive and discard
+
+`archive`/`unarchive` append reversible decisions, mirror release `Course.status`
+for catalog listings only and never touch enrollments, progress, submissions,
+grades, workbooks, notes or evidence. Archived courses refuse release, new pins
+and upgrades. `discardDraft` ends an unreferenced draft with a tombstone (history
+stays); it is refused (`CourseDiscardRefusedError.references`) for releases and
+enrollments, and for review/generation/variant rows via the injected `referenceGuard`
+(`createCourseReferenceGuard`).
+
+## Licence and sharing
+
+Most restrictive wins: own-work < open-license < licensed-for-sharing <
+personal-use-copy (`mostRestrictiveLicense`). A lesson's own licence folds every restriction the course ever recorded
+for its `lessonKey` or its normalized content, so rename, omitted keys and
+remove-then-re-add keep it; only dropping that content lifts it, and a
+`lessonKey` once restricted stays restricted. A reused asset keeps the most
+restrictive licence ever recorded for it. Uploaded materials default to
+`personal-use-copy` unless the author states otherwise. Any personal-use part
+makes the course tenant-private: `GroupSharingWorkFacts.courseShareable=false`
+(reason `course-private`) for authored releases, and the policy option list hides
+them. Work is attributed to the course of its own lesson, and any personal-use
+release anywhere in the enrollment's pin lineage also makes it `course-private`
+and hides the course from the options; unpinned enrollments and databases without the pin tables are unchanged. Existing workbook personal-use scaffolds are unchanged.
+
+## Materials
+
+Uploads are copied by the injected `materialCopy` port into education-owned
+assets (tenant-checked afterwards) with source/actor/time provenance, so
+ingestion expiry never removes them; replays never copy twice, and a port must
+not leave side effects outside the transaction it cannot compensate. Releases
+link them with `LessonAsset` under private asset access for personal-use and
+answer-key material.

package/agents/course-generation-review.md

@@ -0,0 +1,79 @@
+# Material generation proposals and educational review
+
+`CourseGenerationReviewService` (SMRT #4516, extends `QuestionAuthoringService`,
+consumed by Hearth #68) adds generation proposals and revision-bound review to the
+course contract. Risk is high: schema and public contract. It uses the same
+authorizer, tenancy checks and compare-and-swap save path. Every call receives
+the transaction executor and `operation` (`request-generation`, `run-generation`,
+`cancel-generation`, `accept-proposal`, `read-generation`, `record-review`,
+`resolve-finding`, `note-context-change`, `read-review`). Foreign ids are not found.
+
+## Models (closed, required tenant, no REST/CLI/MCP/AI, append-only)
+
+`CourseGenerationJob` (request plus retained input snapshot),
+`CourseGenerationEvent` (status log: queued, running, succeeded, failed,
+cancelled; provider, model, response model, nullable token/cost usage, error
+code, outcome), `CourseProposal`, `CourseProposalDecision`, `CourseReview`,
+`CourseReviewFinding`, `CourseReviewOutdatedMarker`, `CourseFindingResolution`.
+`save()` on an existing row and `delete()` throw. Eight additive tables, test-pinned;
+the runtime never creates tables. `CourseReview` has no score, rating or grade.
+
+## Generation
+
+The host injects a `CourseMaterialGenerator` (`createProposalCourseGenerator`
+adapts an ingestion `ProposalGenerator`); the service never selects a provider.
+`requestGeneration` (action `education.course.generate`) records a job against the
+head the caller saw; the request key is idempotent, a retry or duplicate returns
+the existing job and proposal, and the same key with other input throws
+`CourseRequestKeyConflictError`. `runGeneration` calls the generator outside any
+transaction (deadline and output cap), then validates the untrusted output against
+a closed schema. Invalid output, provider error, timeout, cancellation or a moved
+head record `failed`/`cancelled` and leave the head unchanged; the input stays.
+Personal-use lesson bodies and assets are never sent to the provider.
+
+Success appends one new draft revision (`generate` plus `author`, provenance
+`generated`) holding only additions and fills of empty fields. A proposal that
+differs from supplied content is a `conflict` and is held in `CourseProposal`.
+`getProposal` returns the per-field comparison (supplied, proposed, current,
+decision). `decideProposal` accepts or rejects conflict fields: an accept appends
+a revision on `expectedHeadRevisionId` and records the decision; supplied content
+is replaced only that way. Never write generated content to a released revision or
+assign it to a learner.
+
+## Review
+
+`recordReview` (action `education.course.review`) binds to an exact revision and a
+context digest (level target and theme from the revision; learner plus evidence
+snapshot reference when given). Findings point at a course, lesson or question
+revision id plus field/region, with concern, explanation, suggested change,
+`uncertain`, `humanVerificationRequired` and `blocking`. Sections are separate:
+`general-level` and `individual-learner` (needs a learner context). Every review
+stores `COURSE_REVIEW_DISCLAIMER`; it is an aid, never certification.
+
+A review is outdated when a new draft revision is saved (a persisted marker is
+appended inside that save), when `noteContextChange` reports a new evidence
+snapshot, or when the head differs or the digest no longer verifies (derived).
+History, authorship (actor plus delegating guardian) and findings are kept.
+`resolveFinding` records one resolution per finding; a delegated agent cannot
+resolve a `humanVerificationRequired` finding.
+
+## Release gate and discard guard
+
+`createReviewBackedReleaseGate()` (the service default) makes a revision releasable
+only when its latest review is for that revision, is the draft head, has no marker,
+a matching digest, and no unresolved blocking or human-verification finding on
+any review of it or of any ancestor revision (a newer or empty review never hides
+one). Nothing drops a finding automatically: not an edit, rename, copied question
+or removal of its target. Only `resolveFinding` clears one (a guardian can, even
+when the target is gone; a delegated agent cannot resolve human-verification
+findings); otherwise `ReviewNotCurrentError.reason` is `no-review`, `outdated`,
+`context-mismatch` or `unresolved-findings`. A plain `CourseAuthoringService`
+without a gate still fails closed. `createCourseReferenceGuard(extra)` blocks
+discard for review and generation rows; pass variant guards through `extra`.
+
+## Evaluation
+
+`evaluateReviewer(cases, reviewer)` scores a supplied reviewer function against
+seeded flaws and suitable material (precision, recall, false-alarm rate, per
+category). Fixtures live in `src/__tests__/course-review-fixtures.ts`; no live model
+is called by this package.

package/agents/learner-service.md

@@ -47,6 +47,27 @@ Same-tenant membership alone never grants sibling access.
   A learner cannot plan their own curriculum. Title is required.
 - `enroll` requires that guardian authority and a matching tenant curriculum.
   It returns the existing enrollment for the same curriculum/course unchanged.
+  A delegated agent may enroll, only when the host opts in: construct
+  `LearnerService(db, authorize, authorizeCatalog, { verifyDelegation })` where
+  `verifyDelegation(executor, { tenantId, actorUserId, delegatingGuardianUserId,
+  delegationId, learnerId, courseId? }) => boolean | { allowed, reason?, code? }` runs on the
+  current executor. Without the port, or if it denies or throws, `enroll` refuses with
+  `LearnerAuthorizationError` before the learner authorizer and before any write. Supply
+  `delegatingGuardianUserId` and `delegationId` (both or neither, 1-200 printable characters,
+  guardian not the agent). After the port, the service re-checks the DELEGATING guardian's
+  active membership and `guardianRelationshipId` (that guardian's profile to the learner, same
+  tenant) and the agent's active membership. The authorizer gets `education.learner.plan`,
+  `own: false`, `delegated: true`, `relationshipTypeId` undefined (so a legacy
+  `relationshipTypeId === guardian` rule denies), the guardian's type as
+  `delegatingRelationshipTypeId`, `delegatingGuardianUserId` and `delegationId`, and decides.
+  A new delegated enrollment appends one `EnrollmentAssignmentRecord` (`Enrollment` is
+  unchanged). Only `enroll` and `createCurriculum` accept a delegation (on `LearnerService` itself; subclasses without
+  the port refuse); every other operation ignores it, so the agent has no
+  other learner authority. Catalog reads still use the agent as actor.
+  `createCurriculum` accepts the same delegated actor (`operation: 'create-curriculum'`
+  on the verifier request, `enroll` sends `'enroll'`), with identical verification, guardian
+  relationship recheck, authorizer shape and stripping of caller authority keys; each new
+  delegated curriculum appends one `CurriculumCreationRecord` (own table, `Curriculum` unchanged).
 - `startLesson` allows the learner or authorized guardian to create their own
   enrollment's lesson progress in `in_progress`. It derives learner identity
   from the validated enrollment. Repeated starts return existing state without
@@ -54,6 +75,18 @@ Same-tenant membership alone never grants sibling access.
 - `listProgress` reads only the validated learner/enrollment and lessons still
   visible in that enrollment's course. Inconsistent persisted links fail
   closed or are omitted from the list.
+- An enrollment with an `EnrollmentReleasePin` uses its effective lesson set
+  instead of `enrollment.courseId` alone (`resolveEnrollmentLessons`, shared
+  with `CourseAuthoringService.getEnrollmentRelease`, on the current executor):
+  lessons started (non-`not_started` status or attempts) stay on their original
+  immutable rows in any release the enrollment followed; the rest follow the
+  current pin, in that release's order. `nextLessons`, `assignmentLessons`,
+  `listProgress`, plan reads, `startLesson` and submission/workbook lesson
+  assertions all use it, so a lesson outside the set is rejected and progress
+  rows never move. Unpinned enrollments (or hosts without the authoring
+  tables) read their own course as before. Pins recorded for another learner
+  fail closed. `LessonProgress` accepts a lesson on any release course the
+  enrollment is pinned to; no data migration.
 
 Service results are data-only views, with no persistence or database methods.
 Extra request fields are never model patches: a learner cannot set score,

package/agents/question-records.md

@@ -0,0 +1,100 @@
+# Question and learning-objective records
+
+`QuestionAuthoringService` (SMRT #4515, extends `CourseAuthoringService`, consumed
+by Hearth #68) keeps authored questions and learning objectives. Risk is high:
+schema and public contract. It reuses the course authorizer: writes need
+`education.course.author` (plus `generate` for generated provenance), reads that
+return answer keys need `education.course.read-draft`; every call receives the
+transaction executor and the operation (`create-question`, `save-question`,
+`link-objectives`, `create-objective`, `save-objective`, `read-question`,
+`read-worksheet`, `resolve-question-revisions`). Tenant is required; foreign ids are not-found.
+
+## Models (closed, required tenant, no REST/CLI/MCP/AI, append-only)
+
+`Question` (identity, optional authored `courseId`), `QuestionRevision`,
+`LearningObjective` (identity with tenant-unique stable `externalKey`, for
+coordination with hearthed.org#35), `LearningObjectiveRevision`,
+`QuestionResponse`. `save()` on an existing row and `delete()` throw. There is no
+head row: the head is the highest `sequence`, and writes take an expected-head
+token under a row lock and a unique `(identity, sequence)` index.
+
+A revision holds prompt, response type, choices, subparts, media (tenant assets),
+objective identity ids, concept ids, answer key, rubric and points. A missing key
+or rubric is stored NULL and read back `null`; an empty key is invalid and is never
+inferred. Provenance (`supplied|inferred|generated|edited|extracted`) is recorded
+for each present field, defaulting to the revision's; provenance for an absent
+field is refused. Objectives are linked by identity id, so wording changes, variants
+and themes keep the same objective.
+
+## Writes
+
+`createQuestion`, `saveQuestionRevision`, `linkObjectives`,
+`createLearningObjective`, `saveLearningObjectiveRevision`. Every write needs a
+request key; a retry replays its original result and the same key with another
+payload throws `CourseRequestKeyConflictError`. A stale head throws
+`CourseStaleHeadError`; a reused objective key throws
+`LearningObjectiveKeyConflictError`. Errors keep stable `code`s.
+
+`resolveQuestionRevisions({ revisionIds })` (`read-draft`, no course; the executor and delegation fields
+are passed) returns `{ items, missing }`: per found id `revisionId`, `questionId`, `sequence`,
+`responseType`, `promptSummary` (plain text, whitespace collapsed, at most 200 characters) and, when
+linked, `learningObjectiveKeys`. Never keys, rubrics, choices, media or provenance. 1-200 ids (else
+validation error), de-duplicated, request order. An id with no revision in this tenant, foreign or
+unknown alike, appears only in `missing`.
+
+## Lessons, attempts, grades
+
+A lesson input may carry ordered `questions` (revision id, section, column, source
+page/rect anchor) and flat `layoutParams`; they are part of the lesson revision
+digest, and saving requires each id to be an existing question revision of the
+tenant (`QuestionReferenceError`). Newer question revisions never move a pin.
+
+`WorkbookQuestion.questionRevisionId`/`lessonRevisionId` and the nullable
+`Grade.questionRevisionId` are additive. A referenced revision must exist in the
+tenant; `Grade.rubricResults` must then fit its rubric (criterion id, number or
+`{points}` up to `maxPoints`; empty stays unscored; results need a rubric).
+Unreferenced legacy records are unchanged. `QuestionResponse` is an append-only
+learner response to one exact revision with completion mode
+(`printable|online|interactive`), assistance, a correction chain, `episodeId` and
+the `worksheetVersionId` seen, a numbered `attemptNumber` and the writing request's
+`payloadDigest`. Writes go through `QuestionResponseService` below.
+
+## Responses (`QuestionResponseService`)
+
+Extends `LearnerService`, so it uses the learner authorizer, active-actor/tenant
+checks and executor-bound policy reads. New authorizer actions:
+`education.learner.respond` (the learner's own enrollment; a guardian never starts
+an attempt) and `education.learner.review-response` (guardian only; a learner
+claiming it is refused before the host is asked).
+
+- `recordResponse`: online attempt (new episode, next `attemptNumber`) or, with
+  `correctsResponseId`, the learner's correction in the same episode.
+- `recordGuardianCorrection`: names the response it corrects; `response` omitted
+  records assistance only and keeps the answer. Both append; nothing is rewritten.
+- `readLessonResponses`: the audience follows the actor. The learner gets the
+  keyless bundle (keys never leave the database call), the guardian the keyed one.
+
+The question revision must be in the enrollment's effective lesson set
+(`resolveEnrollmentLessons`, then the lesson revision's `questions`); otherwise
+`QuestionResponseScopeError`. Unpinned enrollments have no authored questions.
+The response is a closed shape (`text`, `numeric`, `choiceIds`, `parts`) checked
+against the revision's choices and subparts (`QuestionResponseValidationError`).
+Every write needs a request key (unique per learner); a replay returns the stored
+row, another payload throws `CourseRequestKeyConflictError`. Other errors:
+`QuestionResponseNotFoundError`, `LearnerAuthorizationError`.
+
+## Rendering
+
+`getWorksheet` (or the pure `buildLearnerWorksheet`/`buildGuardianWorksheet`)
+builds one bundle from a release lesson's pinned revisions. `worksheetVersionId` is
+a digest of ordered revision ids, placement and layout params, so printable and
+online renders of the same revision match and a scan can be matched later. The
+learner bundle is built from an allowlist and has no key, rubric or provenance
+type members; only the guardian bundle carries them. Both service audiences need
+`read-draft`; learner delivery belongs to the host.
+
+## Migration
+
+Schema ships through normal manifest migrations: five new tables (`question_responses` included) plus nullable
+columns on `grades` (`question_revision_id`) and `lesson_revisions` (`questions_json`,
+`layout_params_json`); test-pinned as additive. The runtime never creates tables.