@happyvertical/smrt-education 0.57.52 → 0.59.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,11 +57,16 @@ 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; Word/PowerPoint members render through an injected `DocumentConverter`, fail closed) use
+Course bundles (zip with a closed manifest v1 or v2, or a file set; Word/PowerPoint members render through an injected `DocumentConverter`, fail closed; v2 carries material roles, audience, lesson pages, course members and YouTube references) 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.
 
+Class CrunchLabs (a download read into a manifest v2 bundle; an operator-only
+global catalog provider until the operator's single public switch):
+[source contract](agents/class-crunchlabs.md). Never host its files; `operator`
+visibility needs the host's `operatorTenantIds`.
+
 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

@@ -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/class-crunchlabs.md

@@ -0,0 +1,83 @@
+# Class CrunchLabs source (SMRT #4616)
+
+Class CrunchLabs is a global catalog provider (`class-crunchlabs`) whose units are
+listed under Science, with the @ClassCrunchLabs YouTube course playlists as
+previews. "Add to a course" reads the family's own download of the unit and runs
+the [bundle import](course-bundle-import.md) with a manifest version 2 built from
+it. Files come from CrunchLabs' own downloads and YouTube; **nothing is hosted
+here** and the listing has no acquirable formats.
+
+## Operator-only until permission, one public switch
+
+`CatalogVisibility` gains `operator`. A `CatalogPolicy` built with
+`operatorTenantIds` lets only those families (host configuration, never a
+request) see `operator` records; the default policy shows them to nobody, and
+`authorize` answers `operator-only`. Materialization refuses them.
+
+`createClassCrunchLabsCatalogAdapter({ playlists, publicListing? })` is a snapshot
+`CatalogSyncAdapter` (one terminal page, no cursor). By default
+(`CLASS_CRUNCHLABS_PUBLIC_LISTING_DEFAULT = false`) every record is `operator`
+visibility with licence state `unknown`, no permitted operations and the text
+"free curriculum, permission pending". Only the literal `publicListing: true`,
+set by the operator in host configuration, makes records `catalog` visibility
+with `verified` evidence permitting `link` only. The switch is part of each
+record's revision, so the next sync rewrites the rows when it is flipped.
+`classCrunchLabsPreviewEmbedUrl(record)` returns the youtube-nocookie playlist
+embed for a listed unit (null for anything else). The playlist data is an
+injected `ClassCrunchLabsPlaylistSource`; the adapter never touches the network.
+
+`addClassCrunchLabsUnit({ service, actor, catalogActor, record, listing, policy,
+files, playlists, pageCounter?, receiveMember? })` re-checks
+`canAddClassCrunchLabsUnit(actor, policy, listing)`: visibility is derived from the
+host's own `listing.publicListing` (operator unless the literal `true`), never from
+the record or any caller-supplied visibility or licence; an operator-only listing
+is refused to every other family, and the course actor must be the catalog actor, builds the bundle and imports each part. Then propose
+structure and `applyMaterials` per part as for any bundle. Courses are
+`personal-use-copy` (`build.licenseKind`).
+
+## Reading a download
+
+`buildClassCrunchLabsBundle({ files, playlists?, unit?, pageCounter?,
+includeUnitWideAggregates?, maxPartBytes? })` takes a `ClassCrunchLabsFileSource`:
+`folderClassCrunchLabsSource(dir)` (Node only, from `@happyvertical/smrt-education/node`, never the root: a folder, the Drive zip parts, or both;
+zips are read lazily from their central directory, zip64/encrypted/symlinks are
+skipped) or `memoryClassCrunchLabsSource(files)`. It never reads video files.
+
+- Layout: `<Unit>_All Unit Wide Materials` and `<Unit>_Lesson <n>`; letters A
+  teacher manual, B slides, C student mission log, D status check assessment
+  (plus guidance and the editable master), E handouts, F extras, G videos. A
+  lettered directory wins over a file's own letter. Several units need `unit`.
+- Mapping to manifest v2: A `teacher-guide`, B `slides`, C `learner-pages`, D
+  `assessment` / `assessment-guidance`, E `handout`, F `printable`, the unit-wide
+  Supply List `attachment`. Audiences are the role defaults (teacher manual and
+  guidance guardian, slides guardian, mission log learner); the editable
+  assessment master is guardian. Unit-wide files become course members.
+- The unit-wide "(all lessons)" combined files repeat the per-lesson files and
+  are large, so they are left out unless `includeUnitWideAggregates` (reported as
+  `aggregate-of-lessons`); the supply list, posters and other extras are kept.
+- Lesson pages: the first mission log of a lesson gets a `Mission log` range
+  from `pageCounter` (`createClassCrunchLabsPageCounter({ converter? })` counts
+  PDFs with pdf-lib and Word files by rendering them through the converter).
+  Without a count the lesson gets no pages and the report says so.
+- Videos: names `Lnn.step_Video_Kind_Title` are matched, by unit (playlist
+  title), lesson and step (`L03.6` or `Lesson 3 ... Step 6` in the item title),
+  to the unit playlist; two videos sharing a step are told apart by the item
+  title naming their title or kind, else both stay unmatched (`ambiguous`).
+  Matches become `videos` references with a title and a step order (materials
+  prep videos are guardian audience); unit-level videos (a teaser) and unmatched
+  ones are only reported.
+- De-duplication: repeated exports of one logical path collapse (CRC and size
+  when known; the newer export wins, a changed file is `superseded`); the same
+  bytes under another name or place keep one copy (the lesson-named file in its
+  lesson, posters unit wide, never a `copy`).
+- A unit larger than one archive (bundle cap 100 MiB) is split by lesson into
+  `build.parts` (default 90 MiB each; the first part carries the course members and
+  any lesson that fits beside them, others go to the first part with room; if no
+  lesson fits beside the course members the build refuses with `too_large`); `build.bundle`
+  and `build.manifest` are the first part.
+
+The `report` lists lessons, members, parts, pages, matched and unmatched videos,
+duplicates, ignored files and warnings. Fixtures in tests are synthetic files
+with the same naming; no real download is ever copied into the repository.
+
+Tests: `src/__tests__/class-crunchlabs.test.ts`.

package/agents/course-bundle-import.md

@@ -84,7 +84,7 @@ too long or deep). An **honestly** oversize member (declared over
 
 ## Members and statuses
 
-By content (never by extension alone): `docx`/`pptx` (see below), `pdf` (`%PDF-` in the first 1 KiB),
+By content (never by extension alone): `docx`/`pptx`/`xlsx` (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
@@ -97,9 +97,11 @@ 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
+A `.docx`/`.pptx`/`.xlsx` 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), `ppt/presentation.xml` (pptx) or `xl/workbook.xml`
+(xlsx). A workbook (a supply list) is rendered and kept like the others but has
+no text reader. 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`.
@@ -158,10 +160,15 @@ 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.
+`OfficeTextReader` reads Office text through the SDK without this package
+depending on `@happyvertical/documents`: the host imports `extractOffice`
+(released in `@happyvertical/documents` 0.111.4, sdk#1486, Kreuzberg) and passes
+it to `createOfficeTextReader(extractOffice)`, which returns whole-document
+text for Word and text plus speaker notes per slide for PowerPoint (images are
+never requested). An absent engine reads as `null`; a corrupt file rejects and
+the importer treats that as "no text". The repository's current `catalog:`
+pin is 0.111.3, which predates the Office processors, so the host bumps the SDK
+set (and its minimum release age) before it can import `extractOffice`.
 
 ## Manifest (`manifest.json`, version 1, closed)
 
@@ -186,10 +193,96 @@ are never inlined. Members whose declared role is `answer_key` or `mixed` never
 contribute text to a lesson body (they remain recorded evidence members); the
 proposal rationale only counts how many were withheld.
 
+## Manifest version 2 (SMRT #4615)
+
+A root `manifest.json` with `"version": 2` is laid out by the `manifest-v2`
+reader; version 1 keeps its own reader and page roles. The schema is closed in
+the same way: an unknown key anywhere is `manifest_unknown_key` (with its path in
+`entry`), another version is `manifest_version`.
+
+```json
+{ "version": 2, "course": { "subject": "Science" },
+  "courseMembers": [ { "path": "unit/supplies.pdf", "role": "attachment", "title": "Supply list" } ],
+  "sections": [ { "key": "unit", "title": "Unit", "lessons": [ {
+    "key": "l1", "title": "Lesson 1",
+    "members": [ { "path": "l1/log.docx", "role": "learner-pages" },
+                 { "path": "l1/deck.pptx", "role": "slides" },
+                 { "path": "l1/guidance.pdf", "role": "assessment-guidance" } ],
+    "pages":  [ { "member": "l1/log.docx", "from": 1, "to": 4, "label": "Mission log" } ],
+    "videos": [ { "reference": "dQw4w9WgXcQ", "title": "Recap", "step": 1 } ] } ] } ] }
+```
+
+- **Members** (lesson `members` and root `courseMembers`): `path` (must exist, listed
+  once), `role` (required) one of `teacher-guide`, `slides`, `learner-pages`,
+  `assessment`, `assessment-guidance`, `handout`, `printable`, `answer-key`,
+  `attachment` (`manifest_role` otherwise; a video is a reference, never a file),
+  optional `audience` and `title`. The audience is the role default
+  (`LESSON_ASSET_DEFAULT_AUDIENCE`) unless stated; `answer-key` and
+  `assessment-guidance` are always guardian (a learner audience is
+  `manifest_audience`). Members not listed stay recorded evidence with no role.
+- **Pages**: `{ member, from, to, label? }` ranges over a member of the same lesson
+  (PDF, Word or PowerPoint; the rendered PDF for Office). Each page becomes a
+  `LessonPage` keyed `p<n>`, labelled `<label> <n>` (default `Page <n>`), ordered by
+  declaration. Bad, overlapping or unpageable ranges are `manifest_pages`; at most
+  500 pages per lesson.
+- **Videos**: `{ reference, title, step, audience? }` where `reference` is a bare id
+  or an allowlisted https YouTube URL (`parseYouTubeReference`; anything else is
+  `manifest_video`), `step` an integer 0-9999. They become `LessonExternalVideo`
+  rows; nothing is downloaded.
+- **Course members** become `CourseAsset` rows, not tied to any lesson.
+
+Guardian-audience text (teacher guides, guidance, keys) never enters a proposed
+lesson body; only learner-audience text members do. Under v2 `role` on the member
+evidence row is the material role and `audience` the effective audience (NULL on
+rows recorded before v2). The plan carries `materials` (also on
+`CourseBundleImportResult.materials`): the resolved materials, pages and videos,
+plus `skipped` for declared members that were unsupported, refused or failed
+rendering. A duplicate member resolves to the earlier identical member's bytes
+(`assetPath`) and one material per (place, role, content).
+
+`receiveMember` also gets `audience` and `courseLevel`. **Slides** keep the original
+deck (hand `bytes` to the host as a private asset: "Open in PowerPoint") and its
+rendered pages (`rendered`: "Present").
+
+### Applying materials
+
+`applyMaterials({ ...actor, importId, bundle, courseId, lessons, assets })`
+(`education.course.author`, operation `apply-course-bundle-materials`) writes the
+rows in one transaction. The host has stored each accepted member as a private
+asset and created the course's lessons: `lessons` maps manifest lesson key to the
+`Lesson` id, `assets` maps member path to `{ original, rendered }` asset ids.
+Slides join both the original deck and the rendered PDF; the original join is always
+guardian-only whatever the deck's declared audience (the audience applies to the
+rendered PDF), and a join written earlier with a wider audience is repaired on
+re-apply (`repaired`); any other Word/PowerPoint
+member joins only its rendered PDF, so a learner is never handed an editable
+original. `LessonAsset`/`CourseAsset` saves keep their private-asset rule (guardian-
+only roles and personal-use-copy courses need private assets). It targets
+family-owned courses; an authored course is `authored-course` because authored
+material changes through course authoring. Idempotent: an identical row is
+`unchanged`, a row with other details is `CourseBundleMaterialsError('conflict')`,
+a missing asset or lesson is `asset-missing`/`lesson-missing`; any error writes
+nothing.
+
+### Retrying a failed rendering
+
+`retryRendering({ ...actor, importId, bundle, paths?, receiveMember? })`
+(`education.course.author`, operation `retry-course-bundle-rendering`, needs a
+converter) renders the Word/PowerPoint members whose first import recorded a
+*transient* failure (`converter_unavailable`, `converter_failed`,
+`converter_timeout`; `COURSE_BUNDLE_RETRYABLE_REASONS`). The first import's member
+rows are never rewritten. A success appends one `course_bundle_renderings` row
+per (import, content hash); every reader (`readImport`, replayed imports,
+proposals) overlays it, so the member reads `accepted` (identical copies as
+duplicates) with its rendered hash. A failure records nothing, so asking again is
+always allowed; a second retry of a repaired member is `unchanged` and renders
+nothing. Converter rejections, size limits and the Office member cap are not
+retryable: change the bundle. The bundle must be the imported one.
+
 ## Readers
 
 `BundleReader { formatId, detect, prepare }` in a `BundleReaderRegistry`;
-built-ins are `manifest-v1` and `plain-files`. SCORM and Common Cartridge are
+built-ins are `manifest-v2`, `manifest-v1` and `plain-files`. SCORM and Common Cartridge are
 **not implemented** (their manifests describe launch resources and activity
 trees that do not map to sections/lessons without design); a host can register
 a reader ahead of the built-ins (`register(reader, { first: true })`).
@@ -203,20 +296,17 @@ re-zipping, reordering and timestamps replay. One `CourseBundleImport` per
 ## Models (closed, required tenant, no REST/CLI/MCP/AI, append-only)
 
 `CourseBundleImport` (`course_bundle_imports`: identity, format, reader,
-manifest version, counts, actor) and `CourseBundleMember` (`course_bundle_members`:
+manifest version, counts, actor), `CourseBundleMember` (`course_bundle_members`:
 unique tenant/import/path; ordinal, sha256, size, media type, kind, status,
-reason, duplicate-of, role, section and lesson key). Hashes and placements only:
+reason, duplicate-of, role, audience, section and lesson key) and
+`CourseBundleRendering` (`course_bundle_renderings`: a deliberate retry's success). Hashes and placements only:
 bytes stay with the host's ingestion receipts. Rewrites and deletes throw.
-Normal manifest migrations create both tables.
+Normal manifest migrations create the tables and add `audience` (NULL on older rows).
 
 ## 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).
+- Material rows for authored courses: a proposal still carries lesson text only;
+  authored course material goes through `CourseMaterialInput` and release.
 - 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`.