@happyvertical/smrt-education 0.57.39 → 0.57.41

package/AGENTS.md

@@ -45,3 +45,7 @@ assignment alone never creates learning history or grants learner inbox access.
 Publisher catalog previews use [the preview contract](agents/catalog-previews.md).
 Keep independent image rights and source revisions; serve via `CatalogPreviewService`
 with live actor/tenant authorization, never direct provider image URLs.
+
+Enrollment Plan projections and guardian-only parent notes use
+[the Plan contract](agents/learner-plan.md). Keep awaiting review separate from
+Continue; note authority/provenance never grants learner access or learning evidence.

package/agents/enrollment-notes.md

@@ -0,0 +1,42 @@
+# Enrollment parent notes
+
+`LearnerPlanService` provides `listEnrollmentNotes` and `addEnrollmentNote` on
+its existing actor-bound learner transaction boundary. Both require an exact
+owning tenant, learner and enrollment plus a verified directed guardian
+relationship. Own learners are always denied, even with a permissive host grant.
+The host must authorize `education.learner.notes.read` and
+`education.learner.notes.add`, verifying the current relationship type, terms,
+session and permission using the supplied exact `executor`. Membership alone
+never grants note access. Catalog access does not grant note authority.
+
+Add accepts `{ ...LearnerRequest, enrollmentId, text, requestKey }`. Text is
+nonblank, at most `ENROLLMENT_NOTE_MAX_LENGTH` (4000 UTF-16 code units), and
+retained verbatim as plain text; render with text escaping, never as HTML or
+markdown. Control characters other than tab/newline/carriage return are rejected.
+The request key is nonblank, at most 200 code units, without control characters.
+Author, author label and creation time are server-derived; extra request properties are ignored.
+The data-only result is `{ id, enrollmentId, learnerId, text, authorUserId, authorLabel,
+createdAt: Date }`. List order is creation time then id.
+
+Notes are append-only. Retrying the same tenant/enrollment/requestKey and text
+returns the original row, author, label and time; changing text rejects. PostgreSQL
+serializes writes on the enrollment row and uses a natural-key unique index;
+embedded databases use the owning service transaction queue. Notes share
+`withTransaction` / `withExecutor`, including rollback and poisoned mutations.
+No progress, submission, assessment, feedback or learning history changes occur.
+
+`EnrollmentParentNote` and its collection are trusted persistence APIs, never
+request handlers. Generated REST, CLI, MCP and AI surfaces are closed. Persisted
+model saves and deletes reject; creation uses strict insert so natural-key
+collisions cannot rewrite provenance. The internal persisted `recordedAt` maps
+to DTO `createdAt`. Hosts must use the service to derive provenance and authority.
+Normal additive manifest migration creates `enrollment_parent_notes`.
+
+`src/__tests__/enrollment-note-workflows.ts` contains shared SQLite/PostgreSQL
+assertions for authority, provenance, validation, concurrency and transactions.
+No full DuckDB workflow support is claimed.
+
+`authorLabel` snapshots only the validated actor User's linked Profile name on
+creation, using the same executor. Trim it and cap it at 200 code units; absent
+or blank names use `Parent`. List and retry return the persisted label without
+looking up previous authors, so later profile renames never rewrite history.

package/agents/learner-plan.md

@@ -0,0 +1,66 @@
+# Enrollment Plan reads
+
+`LearnerPlanService(db, authorizeLearner, authorizeCatalog)` extends the existing
+LearnerService transaction/active actor boundary and adds private parent notes
+([notes contract](enrollment-notes.md)). Its `withTransaction` and `withExecutor`
+services retain the Plan methods. Root exports `EnrollmentPlanView` and
+`PlanLessonView`; all results are data only.
+
+`listPlan(request)` returns exact learner enrollments ordered by sortOrder/id.
+`getEnrollmentPlan({...request,enrollmentId})` verifies that exact tenant,
+learner, enrollment and curriculum before reading its course. Missing or denied
+course visibility returns `availability: 'unavailable'`, `course: null`, and
+empty lessons/evidence; it does not interrupt other authorized enrollments.
+Actor/enrollment denial still rejects the request. Operational database errors
+are not disguised as missing material.
+
+The course DTO contains only id, title, subject, summary, modality and sourceKey.
+Technical unfiled capture scaffolding has sourceKey exactly `unfiled-work`;
+consumers exclude it by identity, never by title. The DTO does not invent a cover
+or claim any source/asset preview binding. It returns no teacher or answer-key
+assets. Lessons preserve catalog section/lesson order and existing role-filtered
+progress, including private workbook feedback rules. Optional workbookActivityId
+is resolved for the exact tenant/learner/enrollment/lesson; consumers route that
+work to their workbook interface, not generic scan capture.
+
+Workbook progress uses the same explicit parent completion projection as Work.
+Old grade-derived complete/skipped rows without a current decision project in
+progress with completedAt null; they cannot contribute a completion timestamp to
+progressEvidence. Later analysis of the same attempt retains a parent's decision;
+a new correction or practice attempt reopens it. Ordinary lesson progress is
+unchanged. See [the workbook contract](workbook-service.md).
+
+For required-online lessons, optional sourceUrl comes only from the same
+catalog-authorized Lesson.externalUrl and must be HTTPS without credentials.
+Answer URLs and asset locations are never projected. A missing or unsafe online
+URL is unavailable to Continue and cannot block a later usable lesson. Consumers
+revalidate links at their own browser boundary and display honest unavailable
+material states.
+
+`nextActionableLessonId` considers planned/active enrollments and only unstarted
+or in-progress lessons with usable material. Planned is usable because normal
+`enroll` creates planned enrollments and the base workflow has no activation API.
+Paused/completed/dropped enrollments have no next action. Complete/skipped lessons
+and submitted/needs_review work never instruct rework. `awaitingReviewLessonIds`
+is separate from Continue. Reads never change progress or create learning history.
+
+`progressEvidence` is nullable `{kind: 'started'|'completed',at,lessonId}` from
+visible durable progress start/completion timestamps. It is the newest such
+recorded timestamp, **not** latest actual work. Repeated starts preserve the
+original startedAt. Display it as “Last recorded start/completion”, never infer
+activity from updatedAt, enrollment ordering, notes, or missing timestamps.
+
+```ts
+import { LearnerPlanService, ENROLLMENT_NOTE_MAX_LENGTH, validateEnrollmentNote }
+  from '@happyvertical/smrt-education';
+const service = new LearnerPlanService(db, authorizeLearner, authorizeCatalog);
+const plan = await service.listPlan(serverLearnerRequest);
+validateEnrollmentNote(text, requestKey); // input validation, not authorization
+const note = await service.addEnrollmentNote({
+  ...serverGuardianRequest, enrollmentId, text, requestKey,
+});
+```
+
+Build before consuming the public package; deploy its ordinary additive manifest
+migration before using notes. No runtime handler creates application schema.
+Shared Plan and note workflows run against SQLite and PostgreSQL.

package/agents/submission-service.md

@@ -45,7 +45,12 @@ non-authoritative Grade until guardian review.
 `reviewSubmission` accepts an existing authorized submission and optional score
 and feedback. `attestLesson` creates/reuses an Attestation for a matching progress
 item without requiring uploads. Both require a verified guardian and create a
-new guardian Grade, set submission to `graded` and progress to `complete`.
+new guardian Grade and set submission to `graded`. Ordinary non-workbook progress
+becomes `complete`. Workbook-backed progress instead uses its explicit parent
+completion decision; grading alone leaves it in progress, including through a
+plain SubmissionService instance. Existing explicit completion on the current
+attempt is retained. The owning workbook join determines this policy, never a
+caller flag.
 Omitted/null score is unscored; zero is a real score. The latest guardian grade
 wins over auto/AI/instructor proposals, and its score replaces progress's score.
 Review history is retained. ExternalCompletion is available for trusted server

package/agents/workbook-service.md

@@ -187,12 +187,48 @@ the authorized education timeline independently of optional scratch processing.
 Workbook feedback is projected only from the revision/release workflow. The base
 `SubmissionService` recognizes authoritative `WorkbookActivity` lesson ownership,
 including calls through a plain service instance. Own-learner compatibility views
-withhold Grade and grade-derived status; learner progress projections withhold
-bestScore/completedAt and do not let completion alter next-lesson selection.
-Guardian and ordinary non-workbook projections retain their existing behavior.
+withhold Grade and bestScore. Every workbook progress projection uses the explicit
+parent decision for status and completedAt; historical grade-derived completion
+alone is Doing with no completion date. Ordinary non-workbook projections retain
+their existing behavior.
 This applies in both feedback policy modes; direct feedback remains provisional
 and does not authorize compatibility Grade disclosure.
 
+## Explicit parent completion
+
+`completeWorkbookActivity` requires the current verified guardian, exact activity,
+submissionId, expectedAttemptId, explicit expectedHeadId (including null), and a
+bounded requestKey. The SDK independently denies own learners for
+`education.learner.complete`, even when a host callback grants it. The head token
+is the latest guardian revision, otherwise latest AI revision, otherwise null;
+null permits a parent's judgment without any assessment. The decision and progress
+update share the authorized transaction and learner serialization lock. No grade,
+assessment, feedback release, or learner visibility is created by completion.
+Generic guardian grading of workbook submissions also cannot complete work.
+
+`WorkbookCompletionDecision` retains immutable server actor/time, attempt,
+submission, head provenance, and retry key. Exact retries return that historical
+decision even after a correction; changed retries and stale selectors reject with
+`WorkbookCompletionConflictError` (changed_retry, stale_attempt, stale_head, or
+already_complete). Hosts should acknowledge recording and reread current state,
+never interpret a historical retry as completing a newer attempt.
+
+Completion persists across later assessment or guardian review on the same
+attempt. A newly captured correction or independent practice attempt makes the
+previous decision historical and returns the current work to Doing. Corrections
+retain their episode and must name the current predecessor; fresh practice keeps
+its existing separate episode path. No legacy Grade is converted into a decision.
+
+Activity lists and timelines expose own-safe `completion` (status and nullable
+completedAt), currentAttemptId, and latestSubmissionId. These current pointers
+are independent of history pagination. Timeline completionContext is guardian-only
+and carries the selectors to display and later submit verbatim; own learners
+receive null. Per-attempt completionDecision provenance is also guardian-only.
+The existing attempt headId continues to mean guardian review head.
+
+Deploy the ordinary additive manifest migration before recording decisions. Reads
+of an unmigrated decision table report Doing; runtime handlers never create it.
+
 Generic capture/resubmission rejects workbook enrollment or lesson scaffolding,
 including idempotent retries. Only the protected exact-activity owning workflow
 can capture workbook work. Hosts must call public