@happyvertical/smrt-education 0.57.51 → 0.58.0

package/AGENTS.md

@@ -8,10 +8,12 @@ executor; live session/permission checks must use that executor. That read scope
 collection's `list` to self, ancestors, and globals; it never authorizes a get,
 write, raw query, sibling, or descendant read.
 
-`personal-use-copy` courses and all `answer-key` lesson assets are private
-family material. Do not publish them, promote them, or expose them through a
-learner-facing result. `LessonAsset` is the sole owner join for lesson files;
-do not add asset-id fields to lesson subclasses.
+`personal-use-copy` courses and all `answer-key`/`assessment-guidance` material
+are private family material. Do not publish them, promote them, or expose them
+through a learner-facing result. `LessonAsset` (lesson) and `CourseAsset` (course)
+are the sole owner joins for material files; do not add asset-id fields to lesson
+subclasses. Material audience rules and external videos: [lesson materials](agents/lesson-materials.md);
+a learner never sees guardian-audience material.
 
 Learner objects require exact tenant ownership and close generated surfaces.
 `LearnerService` owns actor/resource authorization and transactional planning and
@@ -28,9 +30,12 @@ files after rollback; never expose source URIs or accept learner grade patches.
 Validation: `pnpm --filter @happyvertical/smrt-education test`,
 `test:postgres`, `typecheck`, and `build`.
 
-Physical workbook capture, immutable assessment/feedback history and descriptive
-evidence use [WorkbookService](agents/workbook-service.md). Keep provisional
-sharing separate from guardian Grade authority. Photo-first receipt/context
+Every lesson hand-in is lesson work (activity, attempt, revisions, release,
+completion decision); books are courses with `bookKey`, pages are `LessonPage`s,
+and loose work is placed by filing. Use [LessonWorkService](agents/lesson-work-service.md)
+and the [design record](agents/course-work-design.md); `migrateWorkbooksToCourses`
+is the one-time host migration. Keep provisional sharing separate from guardian
+Grade authority; never move filed work's IDs. Photo-first receipt/context
 capture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references
 never create learning evidence, and blank exercises need explicit work intent.
 
@@ -52,7 +57,7 @@ Structured questions from scans and imported course files use
 ingestion handler. Anchors come from provider region catalogs only; match by worksheet
 id and layout, never text; ambiguous matches stay unattached; source-keyed replays.
 
-Course bundles (zip with a closed manifest, or a file set) use
+Course bundles (zip with a closed manifest, or a file set; Word/PowerPoint members render through an injected `DocumentConverter`, fail closed) use
 [CourseBundleImportService](agents/course-bundle-import.md). Parse only with the
 bounded reader; refuse, never trim, hostile input; unsupported members stay
 visible; proposals only, nothing auto-published.

package/README.md

@@ -36,13 +36,17 @@ Runtime catalog operations do not create application schema.
 | Model | Purpose |
 | --- | --- |
 | `CourseSource` | Host-managed adapter policy and sharing ceiling |
-| `Course` | Course metadata, license, status, and optional owning tenant |
+| `Course` | Course metadata, license, status, optional owning tenant, optional book identity (`bookKey`, `bookEdition`) and work policy |
 | `ExternalCourse` | External course subtype sharing the Course table |
 | `AuthoredCourse` | Authored course subtype sharing the Course table |
 | `CourseSection` | Ordered section belonging to a course |
 | `Lesson` | Ordered lesson belonging to a section |
 | `Reading`, `Video`, `Worksheet`, `Exercise` | Lesson subtypes |
-| `LessonAsset` | Lesson-owned file join with a relationship such as printable or answer-key |
+| `LessonAsset` | Lesson-owned file join with a role (teacher-guide, slides, learner-pages, assessment, assessment-guidance, handout, printable, answer-key, video, attachment) and an audience |
+| `CourseAsset` | Course-level material (supply list, posters) with the same roles and audience |
+| `LessonExternalVideo` | Allowlisted YouTube reference with title and step order; never downloaded |
+| `LessonPage` | A lesson's printed page: key, label, order, optional source file and page |
+| `LessonActivity`, `WorkAttempt`, `WorkAssessmentRevision`, `WorkFeedbackRelease`, `WorkFeedbackDelivery`, `WorkCompletionDecision`, `LessonWorkFiling` | The one lesson work pipeline (see below) |
 | `Learner` | A required User/Person identity and guarded settings in one family tenant |
 | `Curriculum` | A learner plan for a distinct period |
 | `Enrollment` | One course in a curriculum |
@@ -162,6 +166,36 @@ guardian then confirms. It reuses learner ownership and transaction checks.
 See the [submission integration contract](agents/submission-service.md) for
 inputs, retry rules, signing requirements and external-storage compensation.
 
+## Lesson work, books and materials
+
+Every hand-in on every lesson is lesson work: `SubmissionService` capture and
+correction record the learner's `LessonActivity` and an immutable
+`WorkAttempt`, and `LessonWorkService` (formerly `WorkbookService`) owns the
+timeline, revisioned AI and guardian marking, feedback release, delivery and
+the parent completion decision. A guardian grade on an ordinary lesson
+records its completion decision; book and loose-page work complete only by
+`completeLessonActivity`. Submission pages carry a `pageKey`, so a correction
+may replace individual pages (`WorkAttemptView.pages` folds the versions).
+
+A physical book is a course: `Course.bookKey`/`bookEdition` (one course per
+family per key) with the course work policy (`setCourseWorkPolicy`).
+`Workbook` is retired; run `migrateWorkbooksToCourses(db)` once after the
+schema migration. `resolveBookPageActivity` matches book key and page key to a
+`LessonPage`; `fileLessonWork` places loose photographed work in a course.
+
+Materials carry an audience defaulted by role; learners see only learner
+material (`listLessonMaterials`, `listCourseMaterials`, `signLessonMaterial`,
+`signCourseMaterial`, `setMaterialAudience`, `addLessonVideo`).
+
+Renames: `WorkbookService` → `LessonWorkService`, `WorkbookActivity` →
+`LessonActivity`, `Workbook{Attempt,AssessmentRevision,FeedbackRelease,FeedbackDelivery,CompletionDecision}`
+→ `Work…`, `Workbook…` contracts → `Work…` (`WORK_MATH_VOCABULARY`), and the
+methods listed in the [design record](agents/course-work-design.md#renames-public-api).
+Removed: `Workbook`, `WorkbookWorkFiling`, `WorkbookWorkflowRequiredError`
+(now `LessonWorkWorkflowRequiredError`) and `assertNonWorkbookSubmissionScope`
+(now `assertOrdinarySubmissionScope`). See [lesson work](agents/lesson-work-service.md)
+and [lesson materials](agents/lesson-materials.md).
+
 ## Source imports
 
 `SourceImportService` imports Easy Peasy pages as private family pointers after

package/agents/course-bundle-import.md

@@ -38,7 +38,8 @@ authorizer: `importBundle` needs `education.course.author`, `readImport`
 4. `readImport({ ...actor, importId })` returns the recorded evidence.
 
 Progress is an observer callback (`onProgress({ stage, completed, total })`,
-stages `unpack`, `classify`, `extract`, `propose`; each starts at `completed: 0`).
+stages `unpack`, `classify`, `render`, `extract`, `propose`; each starts at `completed: 0`;
+`render` is emitted only when the bundle has Word/PowerPoint members).
 Ingestion has no public job-progress seam, so none is invented. A throwing
 listener never affects the import.
 
@@ -55,6 +56,9 @@ listener never affects the import.
 | `maxManifestBytes` | 256 KiB |
 | `maxLessons` (the proposal schema's cap) | 50 |
 | `maxLessonBodyChars` | 100 000 |
+| `maxOfficeMembers` (Word/PowerPoint members rendered per bundle) | 50 |
+| `maxRenderedBytes` (PDF accepted back from the converter) | 50 MiB |
+| `conversionTimeoutMs` (one Office member) | 60 000 |
 | archive nesting | 1: a zip inside a zip is never expanded |
 
 A lesson whose combined text members exceed `maxLessonBodyChars` refuses the
@@ -80,7 +84,7 @@ too long or deep). An **honestly** oversize member (declared over
 
 ## Members and statuses
 
-By content (never by extension alone): `pdf` (`%PDF-` in the first 1 KiB),
+By content (never by extension alone): `docx`/`pptx` (see below), `pdf` (`%PDF-` in the first 1 KiB),
 `image` (PNG, JPEG, WebP), `text` (`.txt`/`.md`, strict UTF-8, no control
 characters, body-sized), `manifest` (root `manifest.json`), else `unsupported`.
 Status: `accepted` (handed to extraction), `duplicate` (same sha256 as an earlier
@@ -91,6 +95,74 @@ extracted again), `unsupported` (`unsupported_type`, `nested_archive`,
 `/Encrypt` token anywhere in its bytes (trailer, xref stream): a false positive
 on literal text inside an uncompressed stream is refused, never read.
 
+## Word and PowerPoint members (SMRT #4615)
+
+A `.docx`/`.pptx` member is an OOXML package only when the name and the content
+agree: a zip whose entries include `[Content_Types].xml` and `word/document.xml`
+(docx) or `ppt/presentation.xml` (pptx). Before the bytes go anywhere, the
+package itself passes the same bounded zip reader (ratio, overlap, paths, CRC,
+100 MiB inflated); a failure is `refused / unsafe_office`, never a refusal of the
+whole bundle. Other zips stay `unsupported / nested_archive`.
+
+Two separate things happen to an accepted Office member, both after
+authorization and before the evidence is written:
+
+- **Pages**: a `DocumentConverter` (`document-converter.ts`) renders the original
+  to PDF. The importer enforces the byte and time limits itself (input
+  `maxEntryBytes`, output `maxRenderedBytes`, `conversionTimeoutMs` with an abort
+  signal and a hard race, so an adapter that ignores the signal still times out),
+  and rejects output that is not a PDF or is encrypted. The converter is told a
+  neutral file name (`document.docx`), never the bundle path. Identical documents
+  are rendered once.
+- **Text**: an injectable `OfficeTextReader` (best effort; a failure or a `null`
+  costs the member nothing) returns whole-document text and, for decks, text and
+  speaker notes per slide. Office text is handed to the host on the accepted
+  member (`officeText`) and is **never** inlined into a proposed lesson body:
+  teacher guides and notes carry answers, and audience belongs to manifest v2.
+
+`receiveMember` gets the original `bytes` (store them as the private original
+asset: "Open in PowerPoint" for decks) and `rendered` (`{ bytes, sha256, mediaType:
+'application/pdf', converterId }`, store as a private asset beside the original:
+the pages for "Present"/reading). The member row records `renderedSha256` and
+`renderedSizeBytes`; bytes are still not retained here.
+
+**Fail closed.** Any converter problem records that member `unsupported` with a
+reason and writes the rest of the bundle normally: `converter_unavailable` (none
+configured), `converter_failed` (unreachable or 5xx), `converter_timeout`,
+`converter_too_large`, `converter_rejected` (HTTP 4xx, not a PDF, encrypted),
+`office_limit` (beyond `maxOfficeMembers`, in natural path order). A member that
+failed is not a lesson in the proposal, and identical copies of a failed document
+fail the same way rather than becoming duplicates of nothing. Outcomes are part
+of the append-only evidence, so a replay does not retry a recorded failure (to
+retry, change the bundle). A replay does re-render recorded-accepted members so the
+host receives the bytes again; if it can no longer render one it throws
+`DocumentConversionError` rather than silently dropping an accepted member.
+
+### Host configuration
+
+```ts
+const service = new CourseBundleImportService(db, authorizer, {
+  converter: new GotenbergDocumentConverter({
+    baseUrl: process.env.GOTENBERG_URL, // for example http://gotenberg:3000
+    timeoutMs: 60_000,
+    maxBytes: 50 * 1024 * 1024,
+  }),
+  officeTextReader, // optional, see below
+});
+```
+
+`GotenbergDocumentConverter` posts to `<baseUrl>/forms/libreoffice/convert`, talks
+to nothing else, refuses redirects and URLs with credentials, and caps the response
+as it streams. Run Gotenberg as an internal-only service with **no outbound
+network**, its own size/time limits and no shared volume with the app; this
+package assumes untrusted files never run next to the application. Tests use
+`FakeDocumentConverter` (records calls; `failWith`, `failWhen`, `delayMs`, `output`).
+
+`OfficeTextReader` is deliberately not wired to the SDK here, so this package
+does not depend on an unreleased `@happyvertical/documents`. Once the Office
+processors ship (sdk#1485, `extractOffice(bytes, 'docx' | 'pptx')`), implement
+`read` with it; the snippet is in the `OfficeTextReader` doc comment.
+
 ## Manifest (`manifest.json`, version 1, closed)
 
 ```json
@@ -139,6 +211,12 @@ Normal manifest migrations create both tables.
 
 ## Not in this release
 
+- Manifest version 2 (material roles with audience, lesson pages, course-level
+  members, external video references) waits for the phase 1 role vocabulary
+  (smrt#4614). The page-role vocabulary and the closed v1 schema are unchanged;
+  see the hand-off note on smrt#4615.
+- Re-rendering a member whose first import recorded a converter failure (outcomes
+  are append-only per bundle identity).
 - Ingestion's receipt contract is unchanged: there is no `application/zip` part
   type or `parentEvidenceId` in ingestion. The education side unpacks and the
   host receives members one by one, so archive-to-member lineage lives in

package/agents/course-work-design.md

@@ -0,0 +1,144 @@
+# Course work design (SMRT #4614, folds in #4613)
+
+Phase 1 of hearthed.org#125. Breaking changes are allowed: Hearth is the only
+consumer. This note is the design record; the current contracts live in
+[lesson work](lesson-work-service.md), [photo intake](photo-intake.md),
+[submission](submission-service.md) and [lesson materials](lesson-materials.md).
+
+## Model
+
+- **Course absorbs Workbook.** `Course` gains optional book identity: `bookKey`
+  (`''` = not a book), `bookEdition`, and the course work policy
+  `workReviewRequired` (default true) / `workPolicyVersion` (default 1). A
+  book key requires an owning tenant and is unique per family (one course per
+  tenant per book key, enforced at save). `Workbook` and its learner-scoped
+  rows are retired; the model is deleted.
+- **Lessons have pages.** `LessonPage` (tenant, lesson, `pageKey`, `label`,
+  `sortOrder`, nullable `sourceAssetId` + `sourcePageNumber`) is family-scoped
+  course structure, unique per (tenant, lesson, page key). Photo identification
+  resolves book key → course, page key → lesson page; a book page without a
+  lesson gets a one-page Worksheet lesson in the book course.
+- **One work pipeline.** Every hand-in on every lesson is a `LessonActivity`
+  (one per learner enrollment and lesson) with immutable `WorkAttempt`s,
+  revisioned `WorkAssessmentRevision`s, `WorkFeedbackRelease`s,
+  `WorkFeedbackDelivery`s and `WorkCompletionDecision`s. `SubmissionService`
+  capture and correction write the activity and attempt in the same
+  transaction, so ordinary lessons, book pages and loose photos share one
+  timeline, review, release and completion contract. Completion differs by
+  kind: on an ordinary lesson the guardian grade records the completion
+  decision on the graded attempt (and the learner sees the grade); book and
+  loose-page work is release-gated and completes only by the parent decision,
+  so it stays on `LessonWorkService` (generic capture refuses it with
+  `LessonWorkWorkflowRequiredError`).
+- **Per-page versions (#4613).** `SubmissionAsset.pageKey` names the lesson page
+  a file belongs to (default `p<n>` by position). A correction may carry only
+  the pages it replaces; earlier pages stay at their version. Attempt views
+  expose `pages: [{pageKey, versions:[{submissionId, attemptId, assetId}]}]`
+  folded over the correction chain. Grades stay bound to their submission.
+- **Filing places work.** `LessonWorkFiling` (new table) appends a placement for
+  unfiled work: target course, the learner's enrollment, lesson and lesson page.
+  A book course appends a Worksheet lesson when no lesson has the page key; an
+  authored course needs the lesson to exist (the host appends it first with
+  `CourseAuthoringService.appendLesson`, which owns revisions and releases).
+  Placement is the activity's effective location: lists by course include it,
+  the unfiled list drops it, and the target lesson's progress follows the
+  activity's completion. Activity, attempt, submission and assessment IDs never
+  move. Replays are no-ops; a changed replay or stale head conflicts.
+- **Material roles and audience.** `LessonAssetRelationship` is `teacher-guide`,
+  `slides`, `learner-pages`, `assessment`, `assessment-guidance`, `handout`,
+  `printable`, `answer-key`, `video`, `attachment`. Each `LessonAsset` carries
+  `audience: 'learner' | 'guardian'` with a per-role default
+  (`LESSON_ASSET_DEFAULT_AUDIENCE`): guardian for teacher-guide, slides,
+  assessment-guidance, answer-key; learner otherwise. `answer-key` and
+  `assessment-guidance` are always guardian. `CourseAsset` holds course-level
+  materials with the same roles and audience.
+- **External videos.** A `video` material may be an external reference instead
+  of a stored asset: `externalProvider: 'youtube'`, an 11-character video id
+  (from an id or an allowlisted youtube.com / youtu.be URL), a title and a step
+  order. It is never downloaded; no Asset row exists for it.
+
+## Audience rule
+
+Learner-facing reads (`listLessonMaterials`/`listCourseMaterials` for the learner
+themself, `signLessonMaterial`/`signCourseMaterial`, and every catalog projection
+without answer keys) return only rows whose effective audience is `learner`.
+Guardian-only material, keys, rubrics, notes and storage URIs never reach a
+learner. A guardian may change a family-owned row's audience within the role's
+bounds through `setMaterialAudience`; authored courses change it through course
+authoring (`CourseMaterialInput.audience`) and the next release.
+
+## Renames (public API)
+
+Storage names that are persisted identifiers keep their value: tables
+`workbook_activities`, `workbook_attempts`, `workbook_assessment_revisions`,
+`workbook_feedback_releases`, `workbook_feedback_deliveries`,
+`workbook_completion_decisions`, `workbook_photo_*`, and the ingestion
+handler/operation IDs captured in receipt ceilings. Renaming them would copy
+append-only history and re-point group-sharing foreign keys for no behaviour
+change. The photo-intake models (`WorkbookPhoto*`) keep their class names for
+the same reason (their names derive persisted operation IDs and grants).
+
+| Before | After |
+| --- | --- |
+| `WorkbookService` | `LessonWorkService` |
+| `WorkbookActivity` / `WorkbookActivityView` | `LessonActivity` / `LessonActivityView` |
+| `WorkbookAttempt`, `WorkbookAssessmentRevision`, `WorkbookFeedbackRelease`, `WorkbookFeedbackDelivery`, `WorkbookCompletionDecision` | `WorkAttempt`, `WorkAssessmentRevision`, `WorkFeedbackRelease`, `WorkFeedbackDelivery`, `WorkCompletionDecision` |
+| `WorkbookAssessment`, `WorkbookQuestion`, … contracts, `WORKBOOK_MATH_VOCABULARY` | `WorkAssessment`, `WorkQuestion`, …, `WORK_MATH_VOCABULARY` |
+| `resolveWorkbookActivity({workbookKey,title,edition,pageKey,pageLabel})` | `resolveBookPageActivity({bookKey,title,edition,pageKey,pageLabel})` |
+| `getWorkbookActivity`, `listWorkbookActivities` | `getLessonActivity`, `listLessonActivities({courseId?, filing?})` |
+| `setWorkbookFeedbackPolicy({activityId,…})` | `setCourseWorkPolicy({courseId,expectedPolicyVersion,reviewRequired})` |
+| `captureWorkbookWork` | `captureLessonWork` (pages may carry `pageKey`) |
+| `recordWorkbookAnalysis`, `reviewWorkbookAssessment`, `releaseWorkbookFeedback`, `acknowledgeWorkbookFeedbackDelivery`, `completeWorkbookActivity`, `getWorkbookTimeline` | `recordWorkAnalysis`, `reviewWorkAssessment`, `releaseWorkFeedback`, `acknowledgeWorkFeedbackDelivery`, `completeLessonActivity`, `getWorkTimeline` |
+| `getWorkbook{AttemptBySubmission,PreservationState,SourceAnchors,QuestionIdentity,QuestionContext}` | `getWork…` |
+| `fileWorkbookWork({workbookId \| newWorkbook, canonicalActivityId})` | `fileLessonWork({courseId \| newBook, lessonId?, pageKey?, pageLabel?})` |
+| `listWorkbookPhotoWorkbooks` | `listPhotoBookCourses` |
+| `WorkbookContextRevision` (`workbookId`) | `BookContextRevision` (`courseId`), table `book_context_revisions` |
+| `WorkbookWorkflowRequiredError`, `assertNonWorkbookSubmissionScope` | `LessonWorkWorkflowRequiredError`, `assertOrdinarySubmissionScope` (book and loose-page work only) |
+| `WorkbookPhotoIntakeView.workbookId` | `bookCourseId` |
+| `Workbook`, `WorkbookWorkFiling` | removed (`Course` book identity, `LessonWorkFiling`) |
+
+DTO fields: `workbookKey`/`edition`/`title` on activity views become
+`courseId`, `courseTitle`, `bookKey`, `bookEdition`, `lessonTitle` and `pages`
+(the effective placement; `enrollmentId`/`lessonId` stay the capture routing);
+`filing.workbookId`/`canonicalActivityId` become `filing.placement`. Submission
+pages and `WorkAttemptView` gain `pageKey`/`pages`.
+
+## Migration
+
+`migrateWorkbooksToCourses(db)` (exported, host-run after the schema migration,
+idempotent, transactional). It reads the retired `workbooks`,
+`workbook_work_filings` and `workbook_context_revisions` tables when they exist
+and is a no-op otherwise. It first drops the retired unique index
+`workbook_activities_tenant_id_workbook_id_idx` (tenant, workbook, page key): new
+activities carry no book link and PostgreSQL's NULLS NOT DISTINCT would make them
+collide. The schema diff leaves the retired `workbook_id`/`page_key`/`page_label`
+columns as reported orphans; drop them later with `--drop-columns`.
+The comparer's "rename data pending" note for `workbook_activities.context`
+(it guesses the orphan `page_key`/`page_label` data was renamed) is report-only
+and must not be acted on. `LessonActivity` declares `onDelete: 'NO ACTION'` on
+`enrollmentId`/`lessonId`: as its new natural key they would otherwise default to
+CASCADE and differ from the deployed foreign keys, which SQLite can only change
+by a table rebuild (`lesson-work-schema-contract.test.ts`). The opt-in
+`course-work-real-data.optional.test.ts` (`HEARTH_LEGACY_DB=<copy>`) runs the
+schema step, the data step and new hand-ins on a copy of a real database.
+
+1. Group workbooks by (tenant, workbook key). The canonical course is the
+   earliest (created_at, id) learner's `physical-workbook` scaffold course; it
+   receives `bookKey`, `bookEdition`, title and the strictest policy (review
+   required if any duplicate required it; policy version = max).
+2. Each other learner's scaffold course is merged: its sections and its
+   enrollment are re-pointed to the canonical course, and the emptied course is
+   archived with `sourceKey: 'merged-book'`, `sourceRef: <canonical id>`.
+   Learner history rows (progress, submissions, attempts, grades) are not
+   rewritten; their lessons move with their section.
+3. Every legacy activity's page key/label becomes a `LessonPage` on its lesson.
+4. Legacy filings become `LessonWorkFiling` rows with the same IDs, predecessors
+   first, placing the work in the canonical course: on the named canonical
+   activity's lesson and page, else on a new `Captured work` lesson. The target
+   lesson's progress row is created from the work's completion.
+5. Context revisions are copied into `book_context_revisions` with the same IDs
+   and `courseId` = canonical course.
+
+Each step skips rows already migrated (same IDs or existing book key), so a
+re-run changes nothing. Retired tables are left in place for audit; dropping
+them is a later deliberate operation.

package/agents/group-sharing.md

@@ -104,7 +104,7 @@ The authorization callback is `GroupSharingAuthorizer(request)` where request ca
 
 ## Owning workbook/media seams
 
-Current `WorkbookService` activity/timeline APIs require learner/guardian authority; replacing the authorizer with unconditional true would create a broad guardian backdoor. Add an explicit read-only owning projection seam with a required exact-resource authorization callback, invoked on its active executor before loading private data and again at final projection/delivery where appropriate. It must not expose mutation methods or accept an externally cached authorization boolean. This seam can live in a dedicated education sharing reader that uses owned collections with exact predicates; private workbook algorithms should be shared through an owning helper rather than copied or private-state access.
+Current `LessonWorkService` activity/timeline APIs require learner/guardian authority; replacing the authorizer with unconditional true would create a broad guardian backdoor. Add an explicit read-only owning projection seam with a required exact-resource authorization callback, invoked on its active executor before loading private data and again at final projection/delivery where appropriate. It must not expose mutation methods or accept an externally cached authorization boolean. This seam can live in a dedicated education sharing reader that uses owned collections with exact predicates; private workbook algorithms should be shared through an owning helper rather than copied or private-state access.
 
 The selected attempt must belong to exact family/learner/activity/submission; selected revision must belong to that attempt. Original bytes must be owned through `SubmissionAsset`, match the retained source ID/hash and belong to the learner's private asset owner. Photo covers/reference-only receipts are not work. The ordinary `signSubmissionAsset` returns a signed URL after learner authorization; it is insufficient for this sharing contract. `readSharedMedia` must run current policy/role/session/edge checks for every HTTP delivery and open the exact `withPrivateAssetAccess` scope only within that request. Return bytes or execute a scoped streaming callback; never return public/presigned storage URLs or a long-lived capability. The host route must invoke it even for a replayed/direct URL and configure private storage/cache headers. No framework can revoke bytes already delivered; successful reads linearize at their final authority check. A revocation completed before a new request must always deny that request.
 
@@ -296,3 +296,7 @@ label only; no reviewed cross-tenant read path exists for it, so it grants nothi
 Non-authored courses, answer keys and personal-use rules are untouched, and a
 database without the visibility column or release tables reads as never recorded.
 The gate is `authoredVisibilityPermitsGroups(db, tenantId, releaseCourseId)`.
+
+Filed loose work is attributed to its current filing placement (target lesson,
+enrollment and course, hence subject) under the same consent, offered-metadata and
+pin-lineage rules as routed work; unplaced loose work stays unknown metadata.

package/agents/learner-plan.md

@@ -19,16 +19,16 @@ 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
+progress, including private workbook feedback rules. Optional lessonActivityId
 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.
+Book and loose-page 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).
+unchanged. See [the workbook contract](lesson-work-service.md).
 
 For required-online lessons, optional sourceUrl comes only from the same
 catalog-authorized Lesson.externalUrl and must be HTTPS without credentials.

package/agents/learner-service.md

@@ -115,7 +115,7 @@ Same-tenant membership alone never grants sibling access.
   returns `{ changed: false }`; one complete any other way (guardian
   `attestLesson`/grade, workbook completion) throws `LessonAlreadyCompleteError`.
   Also `EnrollmentNotActiveError` (`.status`; only `active` enrollments),
-  `LessonSkippedError`, `WorkbookOwnedLessonError` (a workbook lesson completes
+  `LessonSkippedError`, `LessonWorkOwnedError` (a workbook lesson completes
   through its workbook decision), and `LearnerHistoryUnavailableError` without
   `lesson_completion_records`. Guardian `attestLesson` is unchanged.
 - `setEnrollmentPace({ enrollmentId, pace: { lessonsPerWeek } | null, policyBasis })`

package/agents/lesson-materials.md

@@ -0,0 +1,52 @@
+# Lesson materials and audience
+
+Design record: [course work](course-work-design.md). Models are closed (no REST,
+CLI, MCP or AI surface); reads and writes go through `SubmissionService` (and its
+`LessonWorkService` subclass) with the usual actor, learner and enrollment checks.
+
+## Roles and audience
+
+`LessonAssetRelationship` (`LESSON_ASSET_RELATIONSHIPS`): `teacher-guide`, `slides`,
+`learner-pages`, `assessment`, `assessment-guidance`, `handout`, `printable`,
+`answer-key`, `video`, `attachment`. Each `LessonAsset`, `CourseAsset` and
+`LessonExternalVideo` row has `audience: 'learner' | 'guardian'`; `''` means the role
+default (`LESSON_ASSET_DEFAULT_AUDIENCE`): guardian for teacher-guide, slides,
+assessment-guidance and answer-key, learner otherwise. `materialAudience(role,
+audience?)` resolves and validates it. `answer-key` and `assessment-guidance`
+(`GUARDIAN_ONLY_RELATIONSHIPS`) can never be learner-audience and, like any join in
+a personal-use-copy course, require a private asset under the host's exact
+actor/owner/asset capability.
+
+`CourseAsset` holds course-level material (supply list, posters) with the same
+roles, audience and private-asset rule, plus an optional title.
+
+## Learner never sees guardian material
+
+`listLessonMaterials({enrollmentId, lessonId})` and `listCourseMaterials({enrollmentId})`
+return `LessonMaterialView`s (`id`, `kind` file or external-video, `scope`, role,
+audience, title, order, `assetId` or provider/videoId/`embedUrl`). The learner
+themself sees only learner-audience rows; an authorized guardian sees all. The
+catalog projection without answer keys (every learner-facing catalog read) applies
+the same rule. `signLessonMaterial`/`signCourseMaterial` sign only a file in the
+actor's own list (claim scope `lesson:<id>` / `course:<id>`); a guessed id of
+guardian material is denied. `signLessonPrintable` applies the same audience
+rule to the learner. Storage URIs never appear.
+
+`setMaterialAudience({enrollmentId, scope, kind, materialId, audience})` lets a
+guardian with plan authority change a family-owned row within the role's bounds.
+Authored courses change audience through course authoring (`CourseMaterialInput.audience`,
+carried to the released join); shared or other families' rows are denied.
+
+## External videos
+
+`LessonExternalVideo` references a video at an allowlisted provider (YouTube only):
+`videoId` (11 characters), title, `stepOrder` and audience. It is never downloaded
+and has no Asset row. `parseYouTubeReference` accepts a bare id or an https
+youtube.com / m. / music. / youtu.be / youtube-nocookie.com URL (watch, embed,
+shorts, live) and nothing else; `externalVideoEmbedUrl` returns the
+youtube-nocookie embed URL. `addLessonVideo({enrollmentId, lessonId, reference,
+title, stepOrder, audience?})` adds one to a family-owned lesson (plan authority);
+the same video with the same details replays, other details conflict, and a
+non-allowlisted reference throws `ExternalVideoReferenceError`.
+
+Tests: `src/__tests__/lesson-materials.test.ts`.