@happyvertical/smrt-education 0.57.33 → 0.57.34

package/AGENTS.md

@@ -3,7 +3,8 @@
 Catalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,
 or AI surface. Applications use `CatalogService`, supplying their actor-bound
 authorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`
-adapter from smrt-users. That read scope may widen only an allowlisted catalog
+adapter from smrt-users. Catalog authorization receives the exact shared collection
+executor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog
 collection's `list` to self, ancestors, and globals; it never authorizes a get,
 write, raw query, sibling, or descendant read.
 
@@ -27,6 +28,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
+capture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references
+never create learning evidence, and blank exercises need explicit work intent.
+
 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

@@ -146,20 +146,41 @@ regressions, dialect coverage, and the existing DuckDB setup limitations.
 `CatalogSyncAdapter` and `CatalogAcquireAdapter`; `fetch` is optional and defaults
 to the standard global Fetch API. Use the same factory for discovery and explicit
 private acquisition through `CatalogAcquisitionService`. No credential, mounted
-provider module, schema extension, or PDF fetch is needed for discovery.
-
-The declared scope is public PDFs with explicit student/family labels on the
-first-edition Kendall Hunt K–5, 6–8, and high-school teacher/family hierarchy,
-including Algebra 1 Supports and linked Spanish counterparts. Traversal starts
-at the official homepage and fixed curriculum roots; it follows direct course,
-unit, resources, family-materials, and lesson-preparation links. Teacher guides,
-answers, assessments, presentations, login-only links, unknown labels, HTML-only
-student lessons, non-PDF formats, and AccessIM/v.360 are excluded. Completion
-means this declared scope only. Policy omissions appear in the bounded, invocation-local
-`CatalogSyncReport.exclusionSummary`, rather than the durable failure ledger.
+provider module or PDF fetch is needed for discovery. Apply the additive catalog
+representation column migration before using this version.
+
+The declared metadata scope is public artifact links on the fixed official CMS
+host, with explicit student/family labels in the first-edition Kendall Hunt
+K–5, 6–8, and high-school teacher/family hierarchy, including Algebra 1 Supports
+and linked Spanish counterparts. Traversal starts at the official homepage and
+fixed curriculum roots; it follows direct course, unit, resources,
+family-materials, and lesson-preparation links. An icon or file-name label never
+establishes the observed format or grants role/rights. Teacher guides, answers,
+assessments, teacher presentations, login-only links, unknown roles, HTML-only
+student lessons, external-host artifacts and AccessIM/v.360 remain outside this
+metadata scope. External links are not followed or HEADed. Known PDF, ZIP and
+DOCX MIME types are retained. Otherwise eligible artifacts with an absent or
+unrecognized Content-Type remain explicit unknown metadata with acquisition
+denied; malformed MIME or invalid validators pause enumeration rather than
+silently omitting an artifact. Only PDF bytes can be acquired.
+Completion means this declared scope only. Policy omissions appear in the
+bounded, invocation-local `CatalogSyncReport.exclusionSummary`, rather than the
+durable failure ledger.
 
 Each `enumerate` reads one HTML page (2 MB maximum) and at most four asset HEADs.
-It never GETs PDF content. Version-1 JSON cursors contain the remaining validated
+It never GETs asset content. Known PDF/ZIP/DOCX HEAD metadata is retained even when
+the file exceeds the PDF acquisition cap. Missing/weak validators, malformed MIME
+or access/transport failures pause the page without advancing. Each observed record has
+optional `representation` metadata with actual `format`, `mediaType`, positive safe
+`byteLength`, strong ETag/Last-Modified `validators`, and `acquisition` capability.
+A PDF is `supported` or `size-limit` with its observed `maxBytes`; ZIP and DOCX are always
+`unsupported-format`. An unknown representation has `format: 'unknown'`,
+`mediaType: null` for an absent header or the actual unrecognized canonical MIME,
+`availableFormats: []`, and `acquisition.status: 'unknown-format'` with a
+`missing-content-type` or `unrecognized-content-type` reason. Its observed size,
+validators and legal evidence remain intact; the evaluator denies new acquisition.
+Unknown v2 revisions encode MIME absence or the observed token explicitly.
+The source icon does not override the actual MIME. Version-1 JSON cursors contain the remaining validated
 hierarchy paths and an artifact offset plus source fingerprint when needed;
 persist the returned cursor unchanged. A fresh adapter can resume it. The cursor
 is capped at 64 KB and 384 pending paths; source pages are capped at 128 children
@@ -181,7 +202,8 @@ the adapter hashes the bytes with SHA-256. The generic service retains attributi
 and image/trademark notices and provides tenant, selection and idempotence checks.
 
 `timeoutMs` bounds the entire call, including streaming (default 20 seconds,
-maximum 60 seconds). `maxPdfBytes` defaults to 32 MiB (maximum 64 MiB). Requests
+maximum 60 seconds). `maxPdfBytes` bounds acquisition only and defaults to 32 MiB
+(maximum 64 MiB). Changing it does not change an existing PDF content revision. Requests
 use fixed official hosts and strict paths, reject redirects, and carry no source
 credentials. Rate limiting returns a resumable pause with Retry-After information;
 hosts must honor that delay before resuming rather than loop immediately.
@@ -225,3 +247,85 @@ history without guessed reclassification. An old coarse six-grade checkpoint
 with no cursor starts the new adapter at its root, preserves its imported count
 and history, and may complete/withdraw only at the new traversal's actual terminal
 page. History alone does not create an active pause.
+
+
+Before creating a new selection or writing files, hosts call
+`evaluateCatalogAcquisitionCapability(resource, format, { maxBytes })` on the
+fresh authoritative record inside their transaction, separately from legal
+`CatalogPolicy` authorization. The optional current limit can tighten the
+persisted limit, never loosen it. Denials distinguish unknown format, unsupported
+format, size limit, unavailable format and invalid representation metadata. It does not
+control printing already pinned bytes. `CatalogAcquisitionService` repeats the
+capability guard for new fetches after its existing pinned-acquisition return;
+current actor, selection, revision, available-format and legal checks still precede that return.
+The adapter independently revalidates format, size, validators and content bytes.
+
+`normalizeCatalogRepresentation(unknown)` parses persisted JSON and returns a
+validated defensive copy. Missing, null and serialized JSON null mean legacy
+absence; the evaluator reports `verification: 'legacy'` without inventing measured
+support, and adapters still enforce their strict acquisition checks. Malformed
+present metadata throws `CatalogRepresentationError`; the evaluator explicitly
+denies `invalid-representation-metadata`. Never catch this error and replace it
+with absence in a read projection. `CatalogResource.getRepresentation()` and
+`setRepresentation()` use the same guard. `CatalogDatabaseSyncStore` persists the
+field and `CatalogReadService` preserves it in its metadata DTO. The nullable TEXT column migration leaves existing rows SQL NULL; new model/store
+values use serialized JSON null. Both mean legacy absence; runtime code
+does not create or alter schema.
+
+
+### Recovering an old partial inventory after a semantic scope change
+
+Including previously omitted non-PDF links changes the canonical page semantics.
+This causes a one-time catalog revision change even when the publisher's HTML
+and PDF validators did not change. PDF v1 encoding remains unchanged, but its
+page fingerprint can change. An old chunk cursor must pause on a fingerprint
+mismatch; never reinterpret its artifact offset against the expanded inventory,
+remove its fingerprint, or mark it complete. An old coarse checkpoint with no
+cursor already starts root discovery naturally and needs no reset.
+
+There is no ordinary UI or cross-process restart operation. The following is an
+**operator-only procedure requiring proven quiescence**. Fence new catalog
+requests, disable/drain or terminate every catalog producer, job and automated
+continuation across **every pod/process**, and await all in-flight provider
+operations/writers, including successful and failing callbacks. Keep new writers
+fenced until the reset finishes. Browser Stop or a paused status alone is not
+quiescence: a late success or failure can overwrite a reset or withdraw old-run
+rows. The fresh run-ID check below does not provide concurrent CAS protection.
+
+With trusted `db`, `providerId` and the operator's `expectedRunId` (explicit
+`undefined` only for a legacy generation without one), use the existing public
+store API after establishing that precondition:
+
+```ts
+const store = new CatalogDatabaseSyncStore(db);
+const current = await store.getCheckpoint(providerId);
+if (!current || current.complete || !current.paused ||
+    current.runId !== expectedRunId) {
+  throw new Error('Expected paused catalog generation is no longer current.');
+}
+await store.saveCheckpoint({
+  ...current,
+  runId: globalThis.crypto.randomUUID(),
+  cursor: undefined,
+  importedCount: 0,
+  complete: false,
+  paused: false,
+  pauseReason: undefined,
+  failures: structuredClone(current.failures),
+});
+```
+
+Record the quiescence and reset in the operator's audit. This changes traversal
+state only: retain all source rows, bounded failure history/counts,
+`lastSuccessfulAt`, selections, acquisitions and private files. Do not delete
+rows/bytes or claim completion. After writers are re-enabled, ordinary sync
+starts at the current adapter's root under the fresh run ID; rows remain until
+an actual successful terminal generation permits withdrawal. A subsequent real
+source failure still pauses and cannot authorize withdrawal.
+
+Old catalog selection/acquisition retries may be stale after the one-time
+semantic revision change and still require current revision/rights checks.
+Previously assigned/materialized private bytes are not changed or deleted by
+catalog discovery; their private printing path is independent of later catalog
+revisions. A new selection through the current adapter keeps its revision and
+cached acquisition across a same-adapter refresh with unchanged source semantics.

package/agents/catalog-sync.md

@@ -55,3 +55,49 @@ pauses for unconfirmed coverage, without inventing an operational failure or
 withdrawing unseen rows. In Drive's catalog adapter, definite unsupported or
 out-of-boundary shortcut omissions are policy; missing revisions and inaccessible
 targets remain operational failures. The direct Drive discovery API is unchanged.
+
+
+Observed representation metadata and legal permissions are separate. Use the
+public `evaluateCatalogAcquisitionCapability` on a fresh record before creating
+new selection/file state, then apply `CatalogPolicy` independently. The
+`representation` serialized JSON field uses a nullable TEXT column (existing rows
+remain SQL NULL; new model/store values use JSON null); apply its
+additive manifest migration before runtime use. Missing/null remains legacy,
+but malformed present metadata must never be erased into legacy absence:
+`normalizeCatalogRepresentation` and the model getter throw a typed error and
+the evaluator returns an explicit denial. Known ZIP/DOCX and over-cap PDF metadata
+are retained; technical acquisition restrictions never remove legal evidence.
+Current configured limits may tighten a recorded limit. Existing pinned-byte
+retries retain their actor/selection/revision/legal checks and do not become
+unavailable merely because future acquisition limits tightened.
+
+
+The public IM adapter enumerates strictly hosted artifact links independent of
+icons; only actual PDF/ZIP/DOCX MIME is recognized and only PDF is acquirable.
+An eligible public HEAD with valid size and strong validators retains an explicit
+`format: 'unknown'` representation when Content-Type is absent (`mediaType: null`,
+`missing-content-type`) or syntactically valid but unrecognized (the bounded
+canonical MIME token, `unrecognized-content-type`). Its acquisition status is
+`unknown-format`, `availableFormats` is empty, and the public evaluator denies
+before new selections, files or asset GETs. Legal evidence, size and validators
+remain intact and metadata enumeration advances. Unknown MIME does not establish
+technical support or change legal permission. Malformed present MIME and invalid
+validators still pause without advancing. Unknown revisions encode MIME absence
+or the observed token, so later recognition changes identity; ordinary PDF v1
+revision encoding remains stable. Role/local ownership/malformed
+markup checks apply to every format; external hosts remain outside coverage.
+Expanded parsed inventory changes page fingerprints once: old offset cursors
+must pause, never be reinterpreted against a different artifact list.
+
+Recovery is quiescent **operator-only**, using existing public
+`CatalogDatabaseSyncStore.getCheckpoint/saveCheckpoint`; see the concrete
+[procedure](../README.md#recovering-an-old-partial-inventory-after-a-semantic-scope-change).
+Fence/disable/drain every catalog producer, automatic continuation and job across
+every pod/process and await all in-flight successes/failures before the fresh
+paused/expected-run check and reset; browser Stop/paused status is insufficient.
+Keep writers fenced through reset. Preserve rows, bounded ledger/counts,
+last-success time and private bytes; use a fresh run UUID/no cursor/imported0,
+incomplete/unpaused state. Only actual terminal success may later withdraw.
+This is not an ordinary UI restart or multi-writer CAS guarantee. Old catalog
+retries can be stale while already assigned private files remain unchanged;
+new current-adapter pins remain stable on a same-adapter semantic refresh.

package/agents/photo-intake.md

@@ -0,0 +1,249 @@
+# Photo-first workbook intake
+
+`WorkbookPhotoService` extends `WorkbookService` 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
+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.
+
+## Receipt before assignment
+
+Construct the service and `IngestionService` from one authenticated server session.
+Use `scope.confidentialScopeId = request.learnerId`, not an enrollment or model
+inference. `authorizePhotoIntake(request)` authorizes a learner's own upload or a
+currently authorized guardian before `receiveWorkbookPhotoIntake({ingestion,
+scope,workbooks,request,receive})` calls ingestion. Its result is `{receipt,intake}`;
+`intake:null` means no successful durable receipt. `retainWorkbookPhotoReceipt`
+repairs an interrupted education copy from an existing authorized receipt.
+
+The immutable education receipt retains the original bytes as private Assets
+through the sole `WorkbookPhotoAsset` owner join, preserving ordered SHA-256
+hashes. Copy retries reject changed bytes, filenames, media types or learner
+ownership. Storage uses the inherited fresh-file compensation ledger; borrowed
+host executors cannot perform file writes. Provider failure does not delete the
+receipt or originals. `getWorkbookPhotoIntake`, `listWorkbookPhotoIntakes` and
+`readWorkbookPhotoOriginal` reauthorize exact ownership independently of scratch
+retention. A learner cannot list/read guardian-uploaded pending or context-only
+material. Guardian-origin lesson source remains private until an explicit
+feedback release on its exact captured attempt, regardless of automatic material
+classification or the workbook provisional-feedback setting. Guardian reads remain
+subject to the current relationship and grants. Child-owned uploads retain the
+normal learner boundary.
+
+## Provider identification and human decisions
+
+Configure `workbookPhotoIntakeHandlers({workbooks,request})` and
+`workbookPhotoIntakeTargetResolver({workbooks,request})` on ingestion's execution
+catalog, and the normal proposal generator/read configuration. Handler
+`@happyvertical/smrt-education:identify-workbook-photo` uses
+`@happyvertical/smrt-education:WorkbookPhotoIntake:get@1` and
+`workbookphotointakes.read`. This operation classifies only; applying it never
+creates a Grade. Keep `requireReview:true`. Candidate freshness checks use the
+supplied executor and the exact authorized workbook/context digest.
+
+The initial immutable captured ceiling must include all intended later stages
+and a provisioned stable execution principal; for marking, include the existing
+review-submission/Grade operation as well. Current guardian authorization still
+controls every Grade. Never widen the receipt ceiling after upload or create a
+second receipt to evade that boundary.
+
+Queue with `queueEducationExtraction`, process extraction/interpretation with
+`processEducationAnalysis`, then call `preserveWorkbookPhotoIdentification`.
+Alternatively `processWorkbookPhotoAnalysis` combines processing, preservation
+and capture of a confidently resolved **completed** lesson. It returns
+`{processing,intake,capture,assessmentRequired}`. The provider runs outside the
+education transaction. Preservation reads the current public immutable ingestion
+snapshot, exact offered schema and original hashes; it retains analysis IDs,
+revision, digests and provider/configuration provenance in append-only decisions.
+Unavailable, failed, stale, malformed and ambiguous results leave durable intake
+pending. A provider needs-review outcome, alternatives or splits never authorize
+automatic resolution; its original proposal remains inspectable. Literal page
+numbers cannot establish lesson identity. Authorization/integrity/database failures still throw.
+
+Provider output distinguishes lesson, cover, reference (including contents and
+answer keys), and uncertain material, plus blank/completed/unknown work state.
+Automatic book identity requires a printed ISBN or complete printed
+publisher/title/edition quotations. Title alone never merges. An existing book may instead match exact current printed title/edition to one
+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;
+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
+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
+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
+replacement; provider classification cannot silently turn a new photo into a
+correction.
+
+After capture, configure the existing `educationIntakeHandlers` with the returned
+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
+ownership and source binding independently of the receipt's confidential scope.
+Guardian Grade/release policy and immutable assessment history are unchanged.
+
+## Verification matrix
+
+`src/__tests__/photo-intake-workflows.ts` runs on SQLite and available PostgreSQL
+(`photo-intake.test.ts` / `photo-intake.optional.test.ts`).
+`photo-intake-manifest.test.ts` separately pins all concrete ownership/provenance
+columns and UUID/FK definitions in the generated structured manifest. It covers actor/resource
+ownership and active context, private originals, sibling/foreign asset denial,
+retry conflicts, concurrent deduplication, rollback and borrowed executor denial,
+cover-only context and immutable identity, ambiguous titles, source integrity,
+blank work intent, multi-page capture, real ingestion generation for cover then
+lesson, provider failure, and guardian-only pending/reference originals. The same
+transaction executor is used for authorization and mutations. Real provider
+handwriting accuracy and deployment worker isolation remain host acceptance.
+
+Run package test/typecheck/build; integration owns PostgreSQL provisioning and
+full-suite validation. Workers never start containers. This is additive feature
+work; a base regression run is N/A because no pre-activity capture API existed.
+
+## Guardian-origin source privacy
+
+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
+its source. Another attempt or context-only page cannot borrow that release.
+
+The base `SubmissionService` applies this policy too: own learners receive no
+pages, notes, Grade/feedback or grade-derived status before release, and signing
+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
+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,
+even when the general workbook policy permits provisional AI feedback.
+
+Existing hosts without photo schema retain ordinary submission behavior through
+optional table-existence checks; no application schema is created at runtime.
+The shared SQLite/PostgreSQL privacy case covers guardian-origin mistaken lesson
+capture, policy off, automatic AI and guardian assessment before release, direct
+base submission reads/signing, exact release, later unreleased reanalysis and a
+different attempt that stays private. Existing own-learner capture cases remain
+readable, and legacy submission/workbook suites protect consumers without photo
+tables.
+
+## Existing candidate identification
+
+`workbookId` selects an exact authorized candidate; 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.
+`identityEvidence` quotes only current visible material. A unique current
+title/edition may match retained publisher provenance without publisher/ISBN
+being reprinted. Conflicting identity, duplicate candidates and title-only
+matching remain pending; malformed model output is never repaired automatically.
+
+## Exact receipt authorization
+
+Processing and retries resolve `context.itemId` through the service-owned
+`getWorkbookPhotoIntakeByItem` lookup, scoped to the current tenant and learner
+on the supplied executor. It delegates to the same current actor and private
+source/release checks as the intake-ID getter. The inbox list remains capped at
+1,000 rows for display; that pagination window is never an authorization or
+lifetime receipt limit.
+
+Hosts may opt into `listWorkbookPhotoIntakes(request, { newestFirst: true })`
+for a current inbox. Default ordering remains unchanged and both orders keep the
+1,000-row display bound and the same per-receipt visibility checks. Exact selected
+receipt reads remain independent of either display window.
+
+## Marking before filing
+
+Completed learner work does not require a printed lesson number or workbook
+identity. Identification `kind:'work', workState:'completed'` deliberately omits
+`workbook`, `activity` and `workbookId`. Its confidence concerns observable learner
+completion/material kind, independently of bibliographic identity. Printed worked
+examples, answer keys, blank pages and uncertain material are not completed learner
+work. `kind:'lesson'` retains the existing strict printed identity contract.
+
+Confident work preservation creates one receipt-bound **unfiled** work unit.
+`processWorkbookPhotoAnalysis` captures it and returns the existing
+`capture/assessmentRequired` result. Queue the normal assessment stage on that
+same receipt, submission and returned activity/enrollment IDs; do not re-upload or
+create another receipt. Visible responses can be assessed while illegible or
+ambiguous responses remain unassessed. The extraction observation contract keeps
+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
+`getWorkbookPhotoTimeline({...request,intakeId,limit?,cursor?,revisionId?})`
+returns existing authorized feedback/history; the normal activity timeline also
+works. `getWorkbookActivity` 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.
+
+## 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
+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,...})`.
+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.