@happyvertical/smrt-education 0.57.51 → 0.58.0

package/agents/{workbook-service.md → lesson-work-service.md}

@@ -1,47 +1,90 @@
-# Physical workbook contract
-
-`WorkbookService` extends `SubmissionService` with the same actor-bound authorization,
-private asset runtime, transaction executor and guardian Grade boundary. Both
-LearnerAuthorizer and CatalogAuthorizer receive the active executor. Host session
-heartbeats and current permission checks must use that supplied executor, including
-nested guardian review; a captured outer pool can wait on its own transaction.
-CatalogService obtains the executor through the public collection.db getter and
-fails closed when its four catalog collections do not share the same handle. It is an
-additive API; existing Submission/Grade consumers retain their contracts. The six
-closed `Workbook*` models are package-manifest models. Apply normal application
-schema migrations before using them; the service never creates runtime schema.
-
-A guardian calls `resolveWorkbookActivity` with an explicit learner, workbook key,
-title, edition (empty means unknown), page key and printed page label. Keys identify
-the physical copy/edition and page occurrence, including section/side where needed.
-Names and photo hashes do not establish identity. A conflicting reuse fails. One
-private personal-use-copy course/enrollment per learner/workbook supplies internal
-submission scaffolding. The public page API needs no course-building workflow.
-
-`captureWorkbookWork` owns original files through SubmissionAsset and creates an
+# Lesson work contract
+
+`LessonWorkService` (formerly `WorkbookService`) extends `SubmissionService` with
+the same actor-bound authorization, private asset runtime, transaction executor and
+guardian Grade boundary. Both LearnerAuthorizer and CatalogAuthorizer receive the
+active executor. Host session heartbeats and current permission checks must use that
+supplied executor, including nested guardian review; a captured outer pool can wait
+on its own transaction. CatalogService obtains the executor through the public
+collection.db getter and fails closed when its four catalog collections do not
+share the same handle. The closed models (`LessonActivity`, `WorkAttempt`,
+`WorkAssessmentRevision`, `WorkFeedbackRelease`, `WorkFeedbackDelivery`,
+`WorkCompletionDecision`, `LessonWorkFiling`, `LessonPage`) are package-manifest
+models; their storage tables keep the historical `workbook_*` names. Apply normal
+application schema migrations before using them; the service never creates runtime
+schema. The design record is [course work](course-work-design.md).
+
+## One pipeline
+
+Every completed-work hand-in on every lesson is lesson work. `SubmissionService`
+capture and correction record the learner's `LessonActivity` (one per enrollment
+and lesson, created on first capture) and an immutable `WorkAttempt` bound to the
+submission in the same transaction; a correction continues its predecessor's
+episode. Blank references create no attempt. Timeline, analysis, guardian review,
+release, delivery, concept evidence and completion work for every lesson.
+
+Two completion rules apply. **Ordinary lessons** (a course without book identity):
+a guardian grade (`reviewSubmission`, `attestLesson`, or guardian review of the
+current capture) records the `WorkCompletionDecision` on the graded current attempt
+and the learner sees the grade. **Book and loose-page work** (a course with
+`bookKey`, or unfiled photo work): marks reach the learner only through an explicit
+release, grading does not complete, and only `completeLessonActivity` does.
+Generic `captureSubmission`/`resubmitSubmission` refuse such work with
+`LessonWorkWorkflowRequiredError`, judged by the enrollment's course (book key or
+unfiled routing) as well as an existing activity, so an untouched book page is
+refused too; hosts call `assertOrdinarySubmissionScope` (enrollment, lesson,
+predecessor) before creating a generic intake receipt.
+
+## Books and pages
+
+A physical book is a course: `Course.bookKey` (one course per family per key,
+immutable once set), `bookEdition`, and the course work policy
+`workReviewRequired`/`workPolicyVersion`. A guardian calls `resolveBookPageActivity`
+with an explicit learner, book key, title, edition (empty means unknown), page key
+and printed label. Keys identify the physical copy/edition and page occurrence,
+including section/side. The family's book course is found or created
+(deterministic id, so concurrent first use collides), the learner is enrolled on
+first use, and the page key matches a `LessonPage` in the course; a new page gets a
+one-page Worksheet lesson. A learner keeps the page lesson their earlier work used
+(merged books may hold two lessons for one key). A conflicting title/edition for a
+key, or a page key naming another label, fails. Names and photo hashes never
+establish identity.
+
+`captureLessonWork` owns original files through SubmissionAsset and creates an
 immutable attempt with source SHA-256 hashes, actual page bounds, actor, capture
 time, assistance, correction predecessor/episode, policy version and effective
-review-required flag. Assistance defaults to `unknown`. Capture retries reuse the
-same Submission/attempt and reject changed bytes or help claims. A correction
-requires the same learner/activity/current predecessor and stays in the same
-practice episode. Analysis/reanalysis adds revisions, never practice attempts.
-Existing LessonProgress.attempts remains a compatibility capture counter.
-
-The workbook review-required policy defaults on and is shared by its pages.
-`setWorkbookFeedbackPolicy` uses expected policy version; existing capture snapshots
-remain unchanged. Policy changes cannot erase prior disclosure. Guarded capture,
-policy and decision writes serialize on the learner within the active transaction.
-Ingestion target resolution acquires that learner lock before the enrollment lock,
-matching capture/review order. Guardian apply follows authorized timeline cursors
-when locating a preserved assessment on an older attempt.
-Composite mutations also use the education transaction's serialized composite
-queue, allowing inherited queued capture/review writes without queue recursion.
-Any swallowed mutation error still aborts the complete transaction and file rollback
-uses the inherited fresh-file compensation ledger.
+review-required flag. Each page may carry a `pageKey`; a correction may carry only
+the pages it replaces, and `WorkAttemptView.pages` folds the versions over the
+correction chain (`current` plus every version oldest first, through the same
+submission privacy projection). Assistance defaults to `unknown`. Capture retries
+reuse the same Submission/attempt and reject changed bytes or help claims. A
+correction requires the same learner/activity/current predecessor and stays in the
+same practice episode. Analysis/reanalysis adds revisions, never practice attempts.
+
+`setBookCourseSubject({courseId, subject})` sets or clears (`null`) a family book
+course's subject (text up to 200 characters) with the same plan authority; shared
+catalog and plain courses are refused. `fileLessonWork({newBook:{subject?}})` sets it
+on a new book; the workbook migration leaves it unset.
+
+`setCourseWorkPolicy({courseId, expectedPolicyVersion, reviewRequired})` needs plan
+authority over every learner enrolled in the course; capture snapshots never change.
+Filed work snapshots the policy of the course it is placed in. Policy changes cannot
+erase prior disclosure. Guarded capture, policy and decision writes serialize on the
+learner within the active transaction. Ingestion target resolution acquires that
+learner lock before the enrollment lock, matching capture/review order. Composite
+mutations use the education transaction's serialized composite queue; any swallowed
+mutation error still aborts the transaction and file rollback uses the inherited
+fresh-file compensation ledger.
+
+`getLessonActivity`/`listLessonActivities({courseId?, filing?})` return the routing
+(`enrollmentId`, `lessonId`: captures and submission reads use these and they never
+move) and the effective placement: `courseId`, `courseTitle`, `bookKey`,
+`bookEdition`, `lessonTitle`, `pageKey`/`pageLabel`, the lesson's `pages` and the
+course policy.
 
 ## Structured assessment and real ingestion
 
-`WorkbookAssessment` version 1 has stable question IDs, original/corrected prompt
+`WorkAssessment` version 1 has stable question IDs, original/corrected prompt
 and answer text, explicit result/reason, nullable points, feedback, retained source
 anchors and curated concept mappings. An anchor names an owned asset plus SHA-256,
 one-based verified page (or null for a whole-file PDF source) and normalized
@@ -58,14 +101,14 @@ is explicitly persisted as unknown. Reviewed overrides append new bodies and kee
 original AI text inspectable.
 
 The configurable vocabulary is trusted server configuration, not AI-created labels.
-The default `WORKBOOK_MATH_VOCABULARY` has addition, subtraction and place value.
-Other subjects may use an explicit curated `workbookVocabulary` on WorkbookService,
+The default `WORK_MATH_VOCABULARY` has addition, subtraction and place value.
+Other subjects may use an explicit curated `workVocabulary` on LessonWorkService,
 the ingestion handler factory and preservation helper. Unknown concept IDs fail;
 zero mapped concepts is valid. AI mappings are proposed, guardian mappings reviewed.
 Known question IDs are pinned across captures; exact prompts are pinned within a
 capture's reanalysis only. Correction transcriptions come from the new capture,
 so earlier answer-bearing prompts cannot override corrected work. Immutable
-historical prompts remain unchanged. The public `getWorkbookQuestionIdentity`
+historical prompts remain unchanged. The public `getWorkQuestionIdentity`
 returns IDs only: historical prompt text can itself include a learner response.
 Handlers use printed number/occurrence/subpart when present; unnumbered tasks use
 answer-free printed-task slugs with visible-task occurrence/subpart, never output
@@ -79,10 +122,10 @@ semantic equivalence of printed tasks; uncertain correspondence requires human
 review rather than an invented match.
 A different page/question requires explicit new activity identity, never AI retargeting.
 
-`captureEducationIntake` accepts optional `workbookActivityId`/`assistance` when its
-service is WorkbookService. It preserves the existing return SubmissionView and
-binds the workbook attempt/policy before the host queues processing.
-`educationIntakeHandlers({workbookActivityId,...})` advertises a bounded JSON question
+`captureEducationIntake` accepts optional `lessonActivityId`/`assistance` when its
+service is LessonWorkService. It preserves the existing return SubmissionView and
+binds the lesson work attempt/policy before the host queues processing.
+`educationIntakeHandlers({lessonActivityId,...})` advertises a bounded JSON question
 schema to real ingestion generation. Assessed results require reason none;
 unassessed reasons require null points. Per-question outcomes must agree with
 points. Correctness is independent of scoring: readable objectively solvable
@@ -94,8 +137,8 @@ Incorrect earns zero only when the possible-point allocation is known.
 Model aggregate scores/narratives are not requested or trusted: exact
 count summaries and points scores are computed from validated questions without
 rounding or invented partial credit. Default legacy handlers remain compatible.
-`preserveWorkbookIntakeAnalysis` reads the public immutable completed generation,
-checks its exact submission and offered workbook schema, maps cited original
+`preserveWorkIntakeAnalysis` reads the public immutable completed generation,
+checks its exact submission and offered marking schema, maps cited original
 ingestion evidence by hash/order to retained education-owned files and imports one
 validated proposal. Provider/model/version, configuration/rubric, source analysis
 pin and proposal digest are durable provenance. Pending/failed processing produces
@@ -112,8 +155,8 @@ configuration digest; question anchors always use honest source-only grounding.
 
 ## Authority, visibility and history
 
-`recordWorkbookAnalysis` accepts authorized submit context and writes provisional
-AI revisions only. `reviewWorkbookAssessment` requires guardian authority, exact
+`recordWorkAnalysis` accepts authorized submit context and writes provisional
+AI revisions only. `reviewWorkAssessment` requires guardian authority, exact
 source revision, expected current guardian head and stable request key. It appends
 an immutable guardian revision recording sourceRevisionId, superseded head, actor,
 time and decision reason. Changed retries conflict. Review of the current capture
@@ -122,22 +165,22 @@ its evidence authority only and cannot grade or reopen its successor. Reanalysis
 after a guardian decision remains provisional. A guardian can invalidate an outcome
 with an unassessed replacement and a stated reason; old AI does not regain authority.
 
-`releaseWorkbookFeedback` separately releases an exact revision using expected
+`releaseWorkFeedback` separately releases an exact revision using expected
 current guardian head. New stale releases fail; accepted retry requests replay their
 original result after later decisions. Release creates no Grade. With the gate off,
 AI feedback is visible as provisional while authoritative grading still requires a
 guardian. Gate-on learners receive no unreleased assessment payloads, scores or
-hints. WorkbookService's ordinary getSubmission also redacts Grade for own learners;
-hosts must route workbook reads through this service and prevent legacy routes from
-serving workbook grades. Guardian history is complete; learners see only their own
+hints. LessonWorkService's ordinary getSubmission also redacts Grade for own learners;
+hosts must route lesson work reads through this service and prevent legacy routes from
+serving gated grades. Guardian history is complete; learners see only their own
 work and visible revisions. Answer keys/source storage URIs never enter these DTOs.
 
-`acknowledgeWorkbookFeedbackDelivery` is an authenticated own-learner acknowledgment
+`acknowledgeWorkFeedbackDelivery` is an authenticated own-learner acknowledgment
 for an exact currently visible feedback revision. It deduplicates per actor/revision
 and rejects withheld, foreign, sibling and guardian acknowledgments. Immutable
 delivery events record actor/time and mean rendered/delivered, never read or understood.
 
-`getWorkbookTimeline` uses education rows/assets without reading ingestion. It lists
+`getWorkTimeline` uses education rows/assets without reading ingestion. It lists
 newest captures/revisions first, includes all releases/delivery events and provides
 cursor pagination (1–100, default 25). A guardian revisionId selector locates its
 containing capture for evidence links. Guardian source IDs/actors/reasons remain
@@ -154,13 +197,13 @@ percentage, generic score comparison, hidden threshold or predictive label is us
 
 ## Preserved processing status and retention
 
-`getWorkbookPreservationState` authorizes exact actor/learner/activity/submission
+`getWorkPreservationState` authorizes exact actor/learner/activity/submission
 and returns only the intake ID plus retained assessment/analysis IDs and the
 interpretation revision. It contains no questions, scores, feedback or hidden
 assessment payloads. New AI provenance records `analysisRevision` from the
 completed interpretation snapshot, separately from its extraction-source pin.
 
-`preserveWorkbookIntakeAnalysis` checks this education-owned state and the public
+`preserveWorkIntakeAnalysis` checks this education-owned state and the public
 content-free ingestion item revision before requesting raw completed analysis.
 An exact already-preserved revision returns `retained` immediately. Guardian
 review, release, corrections and receipt expiry therefore do not force a stale
@@ -184,19 +227,19 @@ the authorized education timeline independently of optional scratch processing.
 
 ## Compatibility API privacy boundary
 
-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 bestScore. Every workbook progress projection uses the explicit
+Book and loose-page feedback is projected only from the revision/release workflow.
+The base `SubmissionService` recognizes it from the authoritative activity and its
+course, including calls through a plain service instance. Own-learner compatibility
+views withhold Grade and bestScore. Their 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.
+alone is Doing with no completion date. Ordinary lessons keep grade-visible,
+grade-completes behaviour, recorded as the completion decision.
 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,
+`completeLessonActivity` 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
@@ -204,12 +247,12 @@ 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.
+Generic guardian grading of book or loose-page submissions cannot complete work.
 
-`WorkbookCompletionDecision` retains immutable server actor/time, attempt,
+`WorkCompletionDecision` 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
+`WorkCompletionConflictError` (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.
 
@@ -229,36 +272,62 @@ 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
-`assertNonWorkbookSubmissionScope` before legacy intake receipt creation and when
-reading an old legacy binding, using authoritative enrollment, lesson and
-predecessor selectors. `WorkbookWorkflowRequiredError` is a controlled denial.
-The browser's optional workbook flag is never authority. Authenticated original
-asset delivery remains a separate read authorization path.
+Generic capture/resubmission rejects book and loose-page work, including
+idempotent retries; only the protected exact-activity workflow captures it. Hosts
+call `assertOrdinarySubmissionScope` before generic intake receipt creation and
+when reading an old binding, using authoritative enrollment, lesson and predecessor
+selectors. `LessonWorkWorkflowRequiredError` is a controlled denial. A browser flag
+is never authority. Authenticated original asset delivery remains a separate read
+authorization path.
 
 ## Validation and limits
 
-`src/__tests__/workbook-workflows.ts` is the shared SQLite/PostgreSQL contract suite;
-`workbook-service.test.ts` runs SQLite, and `workbook.optional.test.ts` runs against
-an available isolated PostgreSQL database. Workers never provision service stacks.
+`src/__tests__/lesson-work-workflows.ts` is the shared SQLite/PostgreSQL contract
+suite; `lesson-work-service.test.ts` runs SQLite, and `lesson-work.optional.test.ts`
+runs against an available isolated PostgreSQL database. `lesson-work-pipeline.test.ts`
+covers ordinary lessons and per-page corrections, `lesson-work-filing.test.ts`
+placement filing, and `course-work-migration.test.ts` (with its optional PostgreSQL
+twin) the workbook migration. Workers never provision service stacks.
 Run package test/typecheck/build; the integration owner runs test:postgres and the
 integrated review. Synthetic provider DTO tests establish transfer integrity, not
 real handwriting accuracy. Actual provider/sample and app restart/retention
 acceptance remain separate integration evidence. Family deletion/export/backup
 policy and automatic lesson generation are not implemented by this milestone.
 
-## Identity-independent work
+## Identity-independent work and filing
 
 [Photo intake](photo-intake.md#marking-before-filing) may own an explicit unfiled
-work unit. Its nullable workbook FK is constrained to an exact retained receipt;
-private enrollment/worksheet routing is technical rather than bibliographic.
-The same attempt/assessment/review/release and concept-evidence contracts apply.
-`filing` is optional on legacy-shaped DTOs and explicit on current projections.
-Append-only filing changes display association only; it never moves immutable
-learning evidence or changes captured review policy. Ordinary identified workbook
-identity and generated-surface restrictions remain unchanged.
+work unit bound to an exact retained receipt; its private enrollment/worksheet
+routing is technical rather than bibliographic. The same attempt, assessment,
+review, release and concept-evidence contracts apply.
+
+`fileLessonWork({activityId, courseId | newBook:{title, edition?, bookKey?},
+lessonId?, pageKey?, pageLabel?, expectedRevisionId, requestKey, reason})` (`newBook`
+may carry `subject`) is the
+guardian's placement (plan authority). Exactly one of `courseId`/`newBook`. The
+target lesson is the given lesson (which must be in the learner's enrollment of that
+course; a page key matches or adds a `LessonPage` on it, adding only on a
+family-owned lesson, else `shared-lesson-page`), else the course's page with
+`pageKey`, else a new one-page Worksheet lesson in a family book or plain course.
+An authored course needs the lesson first: append it with
+`CourseAuthoringService.appendLesson` and file with its `lessonId`
+(`LessonWorkPlacementError` `lesson-required`). A course the learner is not enrolled
+in fails `not-enrolled` unless it is the family's own book course (enrolled on first
+use); another family's course is denied. An omitted new-book key is an opaque manual
+key for this work/request, never a title match.
+
+A filing appends a `LessonWorkFiling` naming the course, enrollment, lesson and
+page; the head is the work's placement. Lists by course include it, `filing:
+'unfiled'` no longer does, and the target lesson's progress becomes Doing (Done once
+the work's current attempt is complete). Completion decisions, new captures and
+corrections keep it in step in the same transaction: a filing never lowers it, and
+a correction reopens only a completion this placed work produced (its completedAt
+is one of the work's own decisions); attested, legacy and other completions stay.
+A new destination row starts at the work's first capture. Progress reads
+(`listProgress`, plans) count completed work filed onto the lesson. Activity, attempt, submission, assessment,
+release and correction-episode IDs never move, and captured policy snapshots never
+change. Stable request-key retries replay; changed retries and stale heads conflict;
+book creation and filing share one transaction. Re-filing names the current head.
 
 ### Unnumbered visible questions
 
@@ -312,7 +381,7 @@ other clearly visible questions are assessed in the same valid proposal.
 
 ### Observed assessment layout
 
-Optional `WorkbookAssessment.layout` version 1 describes observed sections in source
+Optional `WorkAssessment.layout` version 1 describes observed sections in source
 order and zero-based row/column question placements. It is advisory, with fixed
 `provenance: 'observed'`; it never establishes identity or verified geometry.
 Sections reference a retained source asset and a physical one-based observed page,
@@ -324,7 +393,7 @@ original question array index for ties. If any placement in that cell omits
 `part`, the whole cell follows original question array order. Partial placement is valid. Missing `readingOrder` preserves original
 question order for a flattened display.
 
-The browser-safe `normalizeWorkbookObservedLayout` copies only bounded known
+The browser-safe `normalizeWorkObservedLayout` copies only bounded known
 fields: at most 32 sections and 200 placements, 1–8 columns, rows 0–199, parts
 0–31, section IDs up to 64 characters and labels up to 200. Duplicate section IDs
 or question placements, invalid source/page/placement references and malformed
@@ -337,10 +406,10 @@ inside existing revision privacy and exact release boundaries; no migration or
 additional learner visibility is introduced.
 
 Focused shared SQLite/PostgreSQL cases live in
-`src/__tests__/workbook-layout-workflows.ts`, with SQLite in
-`workbook-layout-service.test.ts` and isolated PostgreSQL in
-`workbook-layout.optional.test.ts`. Pure bounds/reference cases are in
-`workbook-layout.test.ts`. Integration runs the PostgreSQL wrapper under its
+`src/__tests__/lesson-work-layout-workflows.ts`, with SQLite in
+`lesson-work-layout-service.test.ts` and isolated PostgreSQL in
+`lesson-work-layout.optional.test.ts`. Pure bounds/reference cases are in
+`lesson-work-layout.test.ts`. Integration runs the PostgreSQL wrapper under its
 existing isolated database lifecycle.
 
 Generation carries optional `layout` as advisory JSON so malformed presentation
@@ -354,7 +423,7 @@ never establishes a question ID, a source authorization or a verified region.
 
 ### Same-capture reread context
 
-`getWorkbookQuestionContext` returns authorized canonical `{id,prompt}` only
+`getWorkQuestionContext` returns authorized canonical `{id,prompt}` only
 from the exact current attempt's identity revision. Generation preserves those
 strings verbatim for the existing strict same-capture prompt invariant, while
 rereading learner responses and any observed layout from current evidence. This
@@ -362,7 +431,7 @@ context is not an answer key or authority for answers. A correction without its
 own revision receives predecessor IDs only; predecessor prompts are never copied.
 Exact source/revision and full correction-ancestry visibility apply to both paths,
 including own-learner reads. No historical rows are rewritten and absent layout
-remains valid. `getWorkbookQuestionIdentity` remains the IDs-only public API.
+remains valid. `getWorkQuestionIdentity` remains the IDs-only public API.
 
 Canonical prompts follow ordinary assessment payload visibility, including
 captured review policy and exact guardian revision release even for learner-owned

package/agents/{workbook-test-matrix.md → lesson-work-test-matrix.md}

@@ -1,4 +1,4 @@
-# Workbook behavior/test matrix
+# Lesson work behavior/test matrix
 
 Design derived from the approved Hearth workbook plan (2026-10-22), learning-record
 contract and WB-001–WB-019 preparation packet (2026-10-23). Feature-class additive
@@ -54,7 +54,7 @@ SessionService heartbeat regression belongs to the host integration lane; synthe
 SQLite affinity alone is not proof that a pooled session lock can never deadlock.
 
 Preservation regression uses actual public IngestionService generation with an
-injected synthetic generator and actual WorkbookService persistence. It proves
+injected synthetic generator and actual LessonWorkService persistence. It proves
 the raw stale-snapshot guard still rejects after grading while preservation skips
 the imported revision, allows a genuinely new provisional reanalysis, and keeps
 review/release/correction history and child feedback gates intact after public
@@ -63,7 +63,7 @@ is not imported; unexpected database errors propagate. This is service-integrity
 evidence, not live-provider accuracy evidence.
 
 Independent-review privacy regression (WB-PRIVACY-1/2): the shared suite exercises
-plain LearnerService/SubmissionService and WorkbookService after guardian review
+plain LearnerService/SubmissionService and LessonWorkService after guardian review
 before release, in both policy modes. getSubmission, capture retry, listProgress,
 assignmentLessons, startLesson and nextLessons do not disclose Grade, score or
 grade-derived completion to the own learner. Generic capture/resubmission and

package/agents/photo-intake.md

@@ -1,10 +1,13 @@
-# Photo-first workbook intake
+# Photo-first book page intake
 
-`WorkbookPhotoService` extends `WorkbookService` with the same constructor,
+`WorkbookPhotoService` extends `LessonWorkService` with the same constructor,
 transaction executor, actor/tenant checks, private storage and rollback ledger.
 Import server integration from `@happyvertical/smrt-education/ingestion`.
 Apply manifest migrations for `WorkbookPhotoIntake`, `WorkbookPhotoAsset`,
-`WorkbookPhotoDecision` and `WorkbookContextRevision` before deploying. There is
+`WorkbookPhotoDecision` and `BookContextRevision` before deploying. The photo
+models keep their `Workbook*` names: they derive the persisted ingestion operation
+IDs and grants captured in receipt ceilings. The book they identify is a course
+with book identity ([course work](course-work-design.md)). There is
 no runtime schema creation and these models expose no generated operations. Each
 concrete table declares its own tenant/learner fields; a custom abstract model
 base does not supply persisted columns to independent manifest tables.
@@ -71,24 +74,26 @@ authorized contextual record with retained publisher provenance; that publisher
 is context, never a fabricated current quotation. Conflicting or ambiguous
 matches stay pending. Provider
 candidates contain book metadata only, never reference text or answer keys.
-`listWorkbookPhotoWorkbooks(request)` includes cover-only books for the provider
-and guardian picker. A printed lesson identity supplies one stable activity key;
+`listPhotoBookCourses(request)` returns the family's book courses (including
+cover-only books) for the provider and guardian picker, with publisher/ISBN context
+from this learner's own decisions. Provider candidates are `Course` targets; the
+wire candidate id (`workbookId`) is the course id and its `workbookKey` the book key. A printed lesson identity supplies one stable activity key;
 multiple page files may belong to that same lesson. Page number alone cannot
 automatically establish lesson identity.
 
 A guardian may call `resolveWorkbookPhotoIntake({...request,intakeId,requestKey,
 identification})` after upload. It requires planning authority and appends a new
 decision. Stable request-key retries replay; changed retries conflict. Covers and
-references create/reuse the Workbook and append contextual metadata only: no
-Course, Lesson, progress, attempt, Grade or concept observations. Existing
-Workbook title/edition identity never changes; context versions retain original
+references create/reuse the family's book course and append contextual metadata
+(`BookContextRevision`) only: no Lesson, enrollment, progress, attempt, Grade or
+concept observations. Existing book title/edition identity never changes; context versions retain original
 metadata and source receipt identity. A captured intake cannot be retargeted.
 
 ## Existing marking pipeline
 
 `captureWorkbookPhotoIntake({...request,intakeId,requestKey,assistance?,
 previousSubmissionId?,completedWork?})` copies the retained originals through
-`captureWorkbookWork` and returns its immutable attempt. Blank or unknown work
+`captureLessonWork` and returns its immutable attempt. Blank or unknown work
 requires explicit `completedWork:true`; no blank exercise is automatically marked
 as unanswered learner work. Corrections require the explicit current predecessor
 and preserve the existing practice episode. Existing attempts reject automatic
@@ -99,7 +104,7 @@ After capture, configure the existing `educationIntakeHandlers` with the returne
 submission ID, `view.activity.id`, and authoritative activity enrollment ID.
 Queue `queueEducationExtraction(ingestion,view.itemId,configuration,submissionId)`
 on the **same learner-scoped receipt**, process normally, then use
-`preserveWorkbookIntakeAnalysis`. That bridge already verifies exact education
+`preserveWorkIntakeAnalysis`. That bridge already verifies exact education
 ownership and source binding independently of the receipt's confidential scope.
 Guardian Grade/release policy and immutable assessment history are unchanged.
 
@@ -126,7 +131,7 @@ work; a base regression run is N/A because no pre-activity capture API existed.
 The immutable photo receipt actor, compared with the persisted learner user,
 determines source origin. Classification as a lesson does not grant learner
 access. `Submission.intakeItemId` joins the exact tenant/learner receipt; only a
-`WorkbookFeedbackRelease` on that submission's exact `WorkbookAttempt` releases
+`WorkFeedbackRelease` on that submission's exact `WorkAttempt` releases
 its source. Another attempt or context-only page cannot borrow that release.
 
 The base `SubmissionService` applies this policy too: own learners receive no
@@ -135,7 +140,7 @@ a guessed source asset is denied. The DTO exposes `awaitingParentRelease:true`
 for an own learner awaiting release, and `sourceRequiresParentRelease:true` to
 all authorized actors for guardian-origin material. The latter remains true
 after release: every new derived revision still needs its own explicit release.
-`WorkbookAttemptView.reviewRequired` and persisted capture policy snapshots
+`WorkAttemptView.reviewRequired` and persisted capture policy snapshots
 retain their historical workbook setting; combine that setting with
 `submission.sourceRequiresParentRelease` when describing effective visibility. Workbook timeline and
 feedback delivery acknowledgment require exact revision release for this source,
@@ -152,7 +157,7 @@ tables.
 
 ## Existing candidate identification
 
-`workbookId` selects an exact authorized candidate; it does not replace the
+The provider's `workbookId` selects an exact authorized candidate (a book course id); it does not replace the
 required `identification.workbook` contract. Copy that candidate's `workbookKey`,
 `title` and `edition` into the required object. Those are catalog identity fields,
 not invented IDs or claims about what is printed on the new photograph.
@@ -194,56 +199,38 @@ printed examples separate from learner marks and reports matching endpoints only
 when observed. Adopt it with a new extraction configuration revision.
 
 The internal private Course/Enrollment/Worksheet are routing records, not a claim
-about a canonical book or lesson. `WorkbookActivity.workbookId` is null only for
-explicit `captureKind:'unfiled'` with an exact owned `photoIntakeId`; all ordinary
-identified activity invariants remain. No Workbook is invented. Activity DTO
-`filing.state` is `unfiled`, `filed` or `identified`; empty workbook title/key/edition
-on unfiled work are intentional. Use the work label as the primary display.
-`listWorkbookActivities` includes these work units. Exact
+about a canonical book or lesson. Only `captureKind:'unfiled'` carries an exact owned
+`photoIntakeId`; all identified activity invariants remain. No book is invented.
+Activity DTO `filing.state` is `unfiled`, `filed` or `identified`; unfiled work has
+`filing.placement: null`, empty course/book fields and the `Captured work` label.
+`listLessonActivities` includes these work units. Exact
 `getWorkbookPhotoTimeline({...request,intakeId,limit?,cursor?,revisionId?})`
 returns existing authorized feedback/history; the normal activity timeline also
-works. `getWorkbookActivity` refreshes exact filing presentation without loading
+works. `getLessonActivity` refreshes exact filing presentation without loading
 history. The receipt view refreshes filing rather than replaying its old label.
 
-Optional guardian `fileWorkbookWork({...request,activityId,workbookId,
-canonicalActivityId?,expectedRevisionId,requestKey,reason})` appends an association
-to a real authorized workbook and optionally a real identified activity. Initial
-expected revision is null. Stable retries replay their original accepted result;
-changed retries/stale heads conflict. Filing does not move or recreate activity,
-submission, attempt, assessment, release, source or correction episode IDs. It
-cannot change captured review policy, create a Grade, duplicate concept evidence,
-or release guardian-origin material. Future corrections continue against the
-original work-unit ID and explicit current predecessor. Existing identified
-captures cannot be retargeted through filing.
-
-Apply normal manifest migrations before using this contract. Existing activities
-receive `capture_kind='identified'` through the declared database default; the
-workbook FK becomes nullable and photo-intake FK plus filing table are added.
-Old populated SQLite requires the explicit supported nullability-relaxation
-migration described by #4413; no runtime DDL or manual SQL workaround is allowed.
-
-When no book record exists, the same optional filing operation accepts
-`newWorkbook:{title,edition?,workbookKey?}` instead of `workbookId`. Exactly one is
-required. Parents need only title/edition; an omitted key becomes an opaque stable
-manual identity for this work/request, never an automatic title-based match.
-An explicit existing key must retain its exact title/edition. New metadata cannot
-also claim `canonicalActivityId`. Book creation and filing share the guardian's
-serialized transaction: stale/unauthorized/conflicting requests create nothing,
-and a later failure rolls both back. No cover re-upload, canonical lesson,
-submission replacement or second assessment is needed. New books keep the default
-review policy; filing never changes the source attempt's captured policy.
+Guardian `fileLessonWork` places unfiled work in a course (an existing book course,
+a new book, or another enrolled course), matching or appending the lesson page; see
+[lesson work filing](lesson-work-service.md#identity-independent-work-and-filing).
+The work leaves the unfiled list at once and its target lesson follows its
+completion. Filing does not move or recreate activity, submission, attempt,
+assessment, release, source or correction episode IDs, cannot change captured
+review policy, create a Grade, duplicate concept evidence, or release
+guardian-origin material. Future corrections continue against the original
+work-unit ID and explicit current predecessor and snapshot the placed course's
+policy. Identified captures cannot be refiled.
 
 ## Exact cover context for header selection
 
-`getWorkbookPhotoIntake` adds optional nullable `workbookId`, loaded from the latest
-retained resolution's exact WorkbookContextRevision under the same tenant/learner
+`getWorkbookPhotoIntake` adds nullable `bookCourseId`, loaded from the latest
+retained resolution's exact BookContextRevision under the same tenant/learner
 and decision ID. Pending/uncertain or unfiled-work resolution returns null; this is
 independent of a later activity filing. It never guesses from title or an inbox
 list. Existing guardian-origin receipt privacy still applies before lookup.
 
 Header cover camera/upload uses the normal receive/process photo flow. A confident
 cover resolves book/context only, with no attempt, lesson or Grade. Read that exact
-intake, then let the guardian explicitly choose `fileWorkbookWork({workbookId,...})`.
+intake, then let the guardian explicitly choose `fileLessonWork({courseId: bookCourseId,...})`.
 An uncertain cover can use the existing guardian `resolveWorkbookPhotoIntake` with
 manual cover metadata, followed by the same exact getter and explicit filing.
 Neither cover identification nor context alone publishes learner source/feedback.

package/agents/question-records.md

@@ -49,7 +49,7 @@ 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
+`WorkQuestion.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).