@happyvertical/smrt-education 0.57.33 → 0.57.34

package/dist/smrt-knowledge.json

@@ -3,15 +3,17 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-education",
-  "packageVersion": "0.57.33",
+  "packageVersion": "0.57.34",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "1b9221c058a8a5ec5118f3186c6d982c5ae79ea80e28864f067b6bf1db79a791",
-    "packageJson": "4751e67156b9b8e98c19ea9cdbb7dcb506f68f68915fd36187f0a1aea0616239",
-    "agents": "bad10d5dcf79f6a2afbe9b81eb945397c9e7b7c2ca2385304e15a30939bc8f3a",
+    "manifest": "fab474c85273e7d0af8fe3160f1145e753b8a7a38ade60a3d79da8b6bc5886ca",
+    "packageJson": "721869383199a708785024d36689b876f97148e902395644bf5192cceb3a6f82",
+    "agents": "bf8b00b31d2dfc9394ab1766421bbeb2dcc5326db3ea60ecc9922b6800f21f48",
     "moduleDoc:agents/learner-service.md": "7da70d214547eb78fbf058e997599cc80ab86f5bb55748bd158a9a4b30070d3b",
     "moduleDoc:agents/submission-service.md": "8e63b83ac84628d5e5ddacbb6a47077c0e65eee3da87518d9bf6e30fb8348336",
+    "moduleDoc:agents/workbook-service.md": "3ca3fb60d39daf76b94ec668fc19dc67aa7e090b7f44412bed5c9d92e8efaf5a",
+    "moduleDoc:agents/photo-intake.md": "3b7057201ee30b2361aad23ea52e8a55c8ed5354e7a7e4a8193b7de17ca2f0db",
     "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc"
   },
   "exports": [
@@ -57,7 +59,7 @@
     "smrt"
   ],
   "risks": [
-    "cross-package-refs:5",
+    "cross-package-refs:6",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -274,6 +276,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "representation",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "licenseEvidence",
           "type": "text",
@@ -308,8 +316,40 @@
         }
       ],
       "relationships": [],
-      "methods": [],
+      "methods": [
+        "getRepresentation",
+        "setRepresentation"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getRepresentation",
+          "returns": "CatalogResourceRepresentation | undefined"
+        },
+        {
+          "name": "setRepresentation",
+          "params": [
+            "value: CatalogResourceRepresentation | undefined"
+          ],
+          "returns": "void"
+        }
+      ],
       "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getRepresentation",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:CatalogResource"
+        },
+        {
+          "kind": "api",
+          "operation": "setRepresentation",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:CatalogResource"
+        }
+      ],
       "relationshipFeatures": [
         "uuidColumns"
       ],
@@ -4156,29 +4196,1723 @@
       ],
       "tags": [],
       "risks": []
-    }
-  ],
-  "surfaces": [],
-  "prompts": [],
-  "relationshipsV2": {
-    "foreignKeyFields": 36,
-    "crossPackageRefFields": 5,
-    "junctionCollections": 2,
-    "hierarchicalObjects": 0,
-    "polymorphicAssociations": 0,
-    "uuidColumns": 184
-  },
-  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n",
-  "moduleDocs": [
+    },
     {
-      "path": "agents/learner-service.md",
-      "module": "learner-service",
-      "content": "# Learner service boundary\n\n`Learner`, `Curriculum`, `Enrollment`, and `LessonProgress` require an exact\nowning tenant. Their generated API, CLI, MCP, and AI operations are closed.\nThe corresponding collections and model saves are trusted server persistence\nAPIs, not request handlers. Hosts must not wrap them in generic learner CRUD.\n\n## Identity and authority\n\nProvision a Person Profile, a linked User, and an active Membership before\ncreating a Learner with explicit `tenantId`, `userId`, and `profileId`. User\nemail is optional. Learner identity cannot be reassigned after creation.\nGuardianship is a directed `ProfileRelationship`, not a Learner `parentId`.\nThe shared Tenant has no family discriminator: “family” means a tenant that\nthe host has provisioned and authorized for this purpose.\n\nConstruct `LearnerService(db, authorizeLearner, authorizeCatalog)` with one\nroot database executor and trusted server-side authorizers. Enable tenancy\nand establish `withTenant({ tenantId, userId }, callback)` from authenticated\ncredentials. Every request must match that active actor and tenant exactly;\nmissing context, spoofed identifiers, and super-admin bypass contexts fail.\nBoth the actor and learner must hold active memberships in that exact tenant.\nA learner's User must still link to the learner's Person Profile.\n\nFor a different actor, supply `guardianRelationshipId`. The service checks\nthat this relationship is owned by the active tenant and directed from the\nactor's User Profile to the learner's Profile. `authorizeLearner` receives\n`own`, `action`, and the verified `relationshipTypeId`; the host must check\nthat the type represents guardianship, its terms are effective, and that\nits permission policy allows the action. An arbitrary relationship is not a\nguardian grant. Missing relationships and host denials/exceptions fail closed.\nThe authorizer also receives `executor`, the service's active database\nexecutor. Host policy reads, including relationship and revocation checks, must\nuse that executor so they share a `withTransaction` or `withExecutor` boundary.\nSame-tenant membership alone never grants sibling access.\n\n## Supported workflow\n\n- `getLearnerSetupStatus({ tenantId, actorUserId, learnerUserId })` is a\n  host-authorized onboarding probe for an active tenant member. It returns only\n  `{ needsSetup }`; it neither returns learner or relationship data nor grants\n  relationships. The host authorizer receives `education.learner.setup`, the\n  target user id, and the active executor. `provisionLearner` remains the write\n  path and still requires a directed guardian relationship.\n- `getLearner` returns authorized learner metadata and parsed settings.\n- `createCurriculum` creates a **planned** curriculum for an authorized guardian.\n  A learner cannot plan their own curriculum. Title is required.\n- `enroll` requires that guardian authority and a matching tenant curriculum.\n  It returns the existing enrollment for the same curriculum/course unchanged.\n- `startLesson` allows the learner or authorized guardian to create their own\n  enrollment's lesson progress in `in_progress`. It derives learner identity\n  from the validated enrollment. Repeated starts return existing state without\n  resetting counters, scores, completion, or timestamps.\n- `listProgress` reads only the validated learner/enrollment and lessons still\n  visible in that enrollment's course. Inconsistent persisted links fail\n  closed or are omitted from the list.\n\nService results are data-only views, with no persistence or database methods.\nExtra request fields are never model patches: a learner cannot set score,\nattempt count, or completion status through this API. Curriculum activation,\ncompletion transitions and dashboard aggregation are not supported by this\nbase service. SubmissionService extends its owning transaction/auth boundary for\ncapture and guardian grading; see [submission contract](submission-service.md).\nDirect model writes require trusted authority.\n\nCatalog visibility and child ownership reuse `CatalogService` on the same\nexecutor. Learner operations request private-inclusive catalog access, so the\nhost catalog authorizer must permit both `education.catalog.read` and\n`education.catalog.read-private` for the supported enrollment workflow.\nPrivate copies remain restricted to the exact owner. The service constructs a\nwhitelisted catalog request; caller options and answer-key flags are discarded.\nAnswer keys are never requested or returned. A catalog grant does not grant learner authorization.\n\n## Transactions and history\n\n`withTransaction(async transaction => ...)` composes service operations on the\ncallback's transaction-bound service. Use that service for every operation in\nthe unit. Throwing rolls back its curriculum, enrollment, and progress writes.\nThe callback's service closes when the transaction ends and rejects later calls.\nA failed mutation poisons the unit even if the callback catches its rejection;\nqueued mutations are cancelled. Callback failure stops pending work and waits for\nalready-running mutations to settle before rollback releases the executor. On\nsuccess, already-enqueued mutations finish before commit. Do not retain the\ncallback's service beyond the callback. The constructor\naccepts a root database; callers composing work use this method instead of\npassing an unmanaged transaction handle.\n\nPostgreSQL locks the parent curriculum/enrollment row before find-or-create.\nEmbedded writes use the core transaction queue. Concurrent mutations inside\none callback transaction are ordered on that connection, so duplicate starts\nwithin a `Promise.all` also return the same row. Database natural-key constraints\narbitrate enrollment `(tenant_id, curriculum_id, course_id)` and progress\n`(tenant_id, enrollment_id, lesson_id)` identities. Explicit storage conflict\nkeys include the tenant prefix because core does not add it to explicit keys.\nThe logical keys required by #3968 remain curriculum/course and enrollment/lesson:\nimmutable parent ownership and parent-tenant checks reject any second tenant\nfor the same parent. The storage prefix cannot create a second valid logical row. Ordinary repeated and concurrent calls\nreturn one row; an aborted workflow can be retried. No in-memory process lock\nis used for PostgreSQL concurrency.\n\nA new year is a new curriculum and enrollment, producing independent progress.\nUnscored `bestScore` persists as null; score zero is a real score. Scores are\nnullable decimals in [0,1]; counters are nonnegative safe integers. Settings\nare stored as JSON text and accessed through guarded `getSettings`/`setSettings`.\n\nThe shared executable workflows in `src/__tests__/learner-workflows.ts` run\nagainst SQLite and PostgreSQL, including actor/resource/context denial,\nconcurrent creation, rollback, history preservation, and zero/null scores.\nFull DuckDB schemas remain blocked by existing upstream DDL restrictions;\nno full learner workflow support on DuckDB is claimed.\n"
+      "name": "Workbook",
+      "qualifiedName": "@happyvertical/smrt-education:Workbook",
+      "displayLabelField": "title",
+      "collection": "workbooks",
+      "description": "Education-owned private workbook record. Mutations go through WorkbookService.",
+      "tableName": "workbooks",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "title",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "edition",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewRequired",
+          "type": "boolean",
+          "required": true,
+          "columnType": "BOOLEAN",
+          "default": true
+        },
+        {
+          "name": "policyVersion",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 1
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "learner_id",
+        "workbook_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:Workbook"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
     },
     {
-      "path": "agents/submission-service.md",
-      "module": "submission-service",
-      "content": "# Submission and paper workflow\n\nConstruct `SubmissionService(db, authorizeLearner, authorizeCatalog, {storage,\nstoreOptions?, signAsset?})` from trusted server configuration. It extends\n`LearnerService`: the same active actor/tenant, memberships, linked person,\ndirected guardian relationship and host permission checks apply. The host must\nallow `education.learner.submit`, `education.learner.grade` or\n`education.learner.packet` as appropriate. Grade and packet actions always reject\nthe learner's own identity, even if the host authorizer returns true.\n\nThe protected transaction/auth hooks are internal owning-service extension\npoints. They are not handler APIs. All public service results remain data-only.\nUse the callback's service in `withTransaction`; escaped services are closed.\nSubmission operations share its serial queue, poison-on-failure behavior and\nPostgreSQL enrollment lock. No runtime schema creation occurs.\n\n## Capture and grading\n\n`captureSubmission` takes the learner request, `enrollmentId`, `lessonId`, a\nnonempty stable `requestKey`, and `pages` containing `name`, `mimeType` and Buffer\n`data`. Each upload becomes a fresh Asset owned by the learner's profile and\nexact tenant, joined solely through `SubmissionAsset`. Up to 100 uploads of\n25 MiB each are accepted (JPEG, PNG, WebP, or PDF). It atomically creates the\nsubmission/asset metadata and moves only that enrollment's progress to\n`submitted`, incrementing attempts once. Caller status, score, grader, asset ID,\nand answer-key flags are never patches. Equal request-key/content retries return\nthe existing submission; altered retries fail. Submitted/review/complete/skipped\nprogress rejects new captures. Content includes ordered filenames, MIME types,\nbytes and notes. Hosts should impose tighter request/body limits as needed.\n\n`captureBlankReference` records a workbook-page scan as immutable\n`blank_reference` evidence without advancing completion or creating a grade.\nTrusted ingestion scopes each receipt to the exact `enrollmentId` and calls\n`assertLessonAssignment` before reading retained evidence; it proves the active\ntenant, actor, learner, enrollment, and lesson without creating progress. A\nstable `intakeItemId` is claimed once in the durable tenant/item binding table,\nthen bound to the tenant, learner, lesson, progress, kind and predecessor; an\naltered retry fails. The binding is database-unique across enrollments while\nordinary uploads remain unbound. `resubmitSubmission` requires the current completed-work predecessor and\ncreates a new immutable `completed_work` attempt. Old pages, grades and feedback\nremain history; stale predecessors cannot be graded or replaced. A correction may\nreopen submitted, review or complete progress, while an AI proposal remains a\nnon-authoritative Grade until guardian review.\n\n`reviewSubmission` accepts an existing authorized submission and optional score\nand feedback. `attestLesson` creates/reuses an Attestation for a matching progress\nitem without requiring uploads. Both require a verified guardian and create a\nnew guardian Grade, set submission to `graded` and progress to `complete`.\nOmitted/null score is unscored; zero is a real score. The latest guardian grade\nwins over auto/AI/instructor proposals, and its score replaces progress's score.\nReview history is retained. ExternalCompletion is available for trusted server\npersistence; phase-zero learner handlers cannot forge reported scores. Online\nsubmissions and automatic grading are not implemented.\n\n`getSubmission` returns only submission metadata, page asset IDs and the selected\ngrade. It does not include catalog answers, extracted answers, storage paths,\nmodel objects, or database handles.\n\n## Storage and signed routes\n\nThe service creates an AssetRuntime bound to the operation's transaction. It\nrequires a resolved URI whose filename retains the fresh asset UUID and MIME\nextension; custom resolvers may choose its provider/directory but must route\nthat URI to the corresponding unique file. Shared existing locators are\nrejected before preservation or cleanup registration. It plans and persists\nthat unique asset URI before writing, registering that new\nasset for cleanup before the provider can partially write. After rollback,\nfiles are removed through the runtime store. Before deletion, the root database\nmust confirm that no asset owner committed: uncertain commit/read failures never\ncause committed bytes to be removed. Only this operation's newly created assets\nare candidates; pre-existing files are never adopted into its cleanup ledger.\n\nDatabase metadata is atomic; external storage uses compensation, not a database\ntransaction. If cleanup cannot complete, `SubmissionStorageCleanupError` contains\nfresh asset IDs and the original cause. Operators must reconcile those IDs in\nthe configured `education-page/<id>.<extension>` storage namespace (custom\nresolvers must retain their routing audit). A successful retry uses fresh IDs\nand cannot delete or reuse orphaned bytes. Process termination may also leave\nunreferenced files; hosts need storage orphan reconciliation. Do not suppress\ncleanup failures or claim crash-safe distributed atomicity.\n\n`signSubmissionAsset` verifies the submission/enrollment/learner ownership and\nits noun join, then verifies the Asset's tenant and learner profile before\ncalling the configured trusted signer. Claims contain actor, tenant, learner,\nenrollment, submission, asset and a five-minute expiry; no static source URI is\nreturned. The host signs every claim and its serving endpoint must verify the\nsignature, expiry, current actor/tenant and object authorization before serving.\nA bearer URL must never become a cross-family or sibling access bypass.\n\n`signLessonPrintable` signs only the exact authorized `printable` LessonAsset\njoin for an enrolled lesson. It never accepts an answer-key join and carries the\nsame tenant, actor, learner and enrollment scope as a submission claim.\n\n## Personal worksheet packets\n\n`splitWorksheetPacket` takes the guardian learner request, exact-owned\n`personal-use-copy` `courseId`, PDF bytes and ranges `{lessonId, firstPage,\nlastPage}`. Page bounds are inclusive and one-based. Ranges must be in bounds,\ndisjoint and target distinct Worksheet lessons in that private course. The\n50 MiB / 100-range limits are enforced before PDF parsing. `pdf-lib` extracts\nactual pages into independent PDFs and records private printable LessonAssets.\nAll resulting metadata commits together; storage failure compensates new PDFs.\nThe source packet is not retained. No shared/global course is accepted and no\nanswer-key join is created. A successful repeated packet upload intentionally\nadds another printable version; a failed upload can be retried safely.\n\nShared integration workflows run on SQLite and real PostgreSQL. Full DuckDB\nworkflow support remains outside the existing supported schema boundary.\n\n## Private asset boundary\n\nCaptured pages and split packet pages use `Asset.accessMode: 'private'` from their\ninitial insert. Ordinary generated Asset REST/MCP operations cannot list, hydrate,\nupdate or delete them, including through the parent STI model. The service opens\nan exact tenant/actor/learner-owner/asset-ID capability only after its normal learner\nrelationship checks. A host's signed serving route must repeat authorization and\nopen that exact capability before loading the asset. See the owning\n[private asset contract](../../assets/agents/private-assets.md).\n\nStorage must be private (including provider ACLs). Public HTTP(S) source locators\nare rejected; a hidden URL alone cannot protect publicly accessible bytes. Apply\nthe manifest migration adding `assets.access_mode` before deploying this runtime;\nlegacy ordinary assets retain the public default. Runtime creates no schema.\n\nPrivate lesson files must already be private Assets in the same tenant. Saving\nan answer-key join, or any join under a personal-use-copy course, requires the\nhost's exact actor/owner/asset capability; a public asset is never automatically\npromoted. Packet splitting retains this capability while creating each join.\nPersisted course tenant/license and section/lesson parent identity cannot change;\ncreate new structure and explicitly re-author its joins instead. Mandatory\nwrite predicates enforce this even for natural-key adoption and concurrent writes.\nOrdinary content and metadata refresh remains supported. This\nprevents existing public material being reclassified by moving its parent.\n\nFor pre-existing invalid joins, an authorized host must inventory private-material\njoins and remove invalid associations, recreate the bytes in private storage as a\nnew privately classified Asset, then re-author the join under its exact capability.\nDo not merely hide the URI, mutate access_mode with raw SQL, or delete shared\npublic bytes. This repair requires explicit storage/ownership authorization;\nnormal runtime does not migrate existing records.\n"
+      "name": "WorkbookCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookCollection",
+      "collection": "workbooks",
+      "tableName": "workbooks",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookActivity",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookActivity",
+      "collection": "workbookactivities",
+      "description": "Education-owned private workbook record. Mutations go through WorkbookService.",
+      "tableName": "workbook_activities",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "captureKind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "identified"
+        },
+        {
+          "name": "photoIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "enrollmentId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Enrollment",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        },
+        {
+          "name": "pageKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "pageLabel",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "photoIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "enrollmentId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Enrollment",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "workbook_id",
+        "page_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookActivity"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookActivity"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookActivityCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookActivityCollection",
+      "collection": "workbookactivities",
+      "tableName": "workbook_activities",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookWorkFiling",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookWorkFiling",
+      "collection": "workbookworkfilings",
+      "description": "Append-only association; the source work unit and its routing never move.",
+      "tableName": "workbook_work_filings",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceActivityId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "canonicalActivityId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "previousRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookWorkFiling",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "digest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceActivityId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "canonicalActivityId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "previousRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookWorkFiling",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "source_activity_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookWorkFiling"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookWorkFiling"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookWorkFilingCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookWorkFilingCollection",
+      "collection": "workbookworkfilings",
+      "tableName": "workbook_work_filings",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookAttempt",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookAttempt",
+      "collection": "workbookattempts",
+      "description": "Education-owned private workbook record. Mutations go through WorkbookService.",
+      "tableName": "workbook_attempts",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "activityId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "submissionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Submission",
+          "columnType": "UUID"
+        },
+        {
+          "name": "previousAttemptId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "capturedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "episodeId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewRequired",
+          "type": "boolean",
+          "required": true,
+          "columnType": "BOOLEAN",
+          "default": true
+        },
+        {
+          "name": "policyVersion",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 1
+        },
+        {
+          "name": "assistance",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceHashes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "activityId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookActivity",
+          "columnType": "UUID"
+        },
+        {
+          "name": "submissionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Submission",
+          "columnType": "UUID"
+        },
+        {
+          "name": "previousAttemptId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "submission_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookAttempt"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookAttempt"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookAttemptCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookAttemptCollection",
+      "collection": "workbookattempts",
+      "tableName": "workbook_attempts",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookAssessmentRevision",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookAssessmentRevision",
+      "collection": "workbookassessmentrevisions",
+      "description": "Education-owned private workbook record. Mutations go through WorkbookService.",
+      "tableName": "workbook_assessment_revisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "decisionReason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "supersedesId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assessmentJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "supersedesId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "attempt_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookAssessmentRevision"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookAssessmentRevision"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookAssessmentRevisionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookAssessmentRevisionCollection",
+      "collection": "workbookassessmentrevisions",
+      "tableName": "workbook_assessment_revisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookFeedbackRelease",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookFeedbackRelease",
+      "collection": "workbookfeedbackreleases",
+      "description": "Education-owned private workbook record. Mutations go through WorkbookService.",
+      "tableName": "workbook_feedback_releases",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "revisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "expectedHeadId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "revisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "expectedHeadId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "attempt_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookFeedbackRelease"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookFeedbackRelease"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookFeedbackReleaseCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookFeedbackReleaseCollection",
+      "collection": "workbookfeedbackreleases",
+      "tableName": "workbook_feedback_releases",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookFeedbackDelivery",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookFeedbackDelivery",
+      "collection": "workbookfeedbackdeliveries",
+      "description": "Authenticated delivery acknowledgment; this does not assert comprehension.",
+      "tableName": "workbook_feedback_deliveries",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "revisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attemptId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAttempt",
+          "columnType": "UUID"
+        },
+        {
+          "name": "revisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookAssessmentRevision",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "attempt_id",
+        "actor_user_id",
+        "revision_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookFeedbackDelivery"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookFeedbackDelivery"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookFeedbackDeliveryCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookFeedbackDeliveryCollection",
+      "collection": "workbookfeedbackdeliveries",
+      "tableName": "workbook_feedback_deliveries",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoIntake",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoIntake",
+      "collection": "workbookphotointakes",
+      "description": "Durable receipt before any course, enrollment or activity exists.",
+      "tableName": "workbook_photo_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "itemId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "contentDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "item_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoIntake"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoIntake"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoIntakeCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoIntakeCollection",
+      "collection": "workbookphotointakes",
+      "tableName": "workbook_photo_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoAsset",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoAsset",
+      "displayLabelField": "name",
+      "collection": "workbookphotoassets",
+      "description": "Sole owner join for original photo intake files.",
+      "tableName": "workbook_photo_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "mimeType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "position",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "intake_id",
+        "asset_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoAsset"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoAsset"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoAssetCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoAssetCollection",
+      "collection": "workbookphotoassets",
+      "tableName": "workbook_photo_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoDecision",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoDecision",
+      "collection": "workbookphotodecisions",
+      "description": "Immutable provider/guardian/capture decision, retaining provenance and retry key.",
+      "tableName": "workbook_photo_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sequence",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "bodyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoIntake",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "intake_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoDecision"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookPhotoDecision"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookPhotoDecisionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookPhotoDecisionCollection",
+      "collection": "workbookphotodecisions",
+      "tableName": "workbook_photo_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookContextRevision",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookContextRevision",
+      "collection": "workbookcontextrevisions",
+      "description": "Versioned contextual metadata; never edits Workbook identity or learning evidence.",
+      "tableName": "workbook_context_revisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "decisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoDecision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "metadataJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "workbookId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Workbook",
+          "columnType": "UUID"
+        },
+        {
+          "name": "decisionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "WorkbookPhotoDecision",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "decision_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookContextRevision"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:WorkbookContextRevision"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "WorkbookContextRevisionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:WorkbookContextRevisionCollection",
+      "collection": "workbookcontextrevisions",
+      "tableName": "workbook_context_revisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 70,
+    "crossPackageRefFields": 6,
+    "junctionCollections": 2,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 298
+  },
+  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. Catalog authorization receives the exact shared collection\nexecutor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nPhysical workbook capture, immutable assessment/feedback history and descriptive\nevidence use [WorkbookService](agents/workbook-service.md). Keep provisional\nsharing separate from guardian Grade authority. Photo-first receipt/context\ncapture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references\nnever create learning evidence, and blank exercises need explicit work intent.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n",
+  "moduleDocs": [
+    {
+      "path": "agents/learner-service.md",
+      "module": "learner-service",
+      "content": "# Learner service boundary\n\n`Learner`, `Curriculum`, `Enrollment`, and `LessonProgress` require an exact\nowning tenant. Their generated API, CLI, MCP, and AI operations are closed.\nThe corresponding collections and model saves are trusted server persistence\nAPIs, not request handlers. Hosts must not wrap them in generic learner CRUD.\n\n## Identity and authority\n\nProvision a Person Profile, a linked User, and an active Membership before\ncreating a Learner with explicit `tenantId`, `userId`, and `profileId`. User\nemail is optional. Learner identity cannot be reassigned after creation.\nGuardianship is a directed `ProfileRelationship`, not a Learner `parentId`.\nThe shared Tenant has no family discriminator: “family” means a tenant that\nthe host has provisioned and authorized for this purpose.\n\nConstruct `LearnerService(db, authorizeLearner, authorizeCatalog)` with one\nroot database executor and trusted server-side authorizers. Enable tenancy\nand establish `withTenant({ tenantId, userId }, callback)` from authenticated\ncredentials. Every request must match that active actor and tenant exactly;\nmissing context, spoofed identifiers, and super-admin bypass contexts fail.\nBoth the actor and learner must hold active memberships in that exact tenant.\nA learner's User must still link to the learner's Person Profile.\n\nFor a different actor, supply `guardianRelationshipId`. The service checks\nthat this relationship is owned by the active tenant and directed from the\nactor's User Profile to the learner's Profile. `authorizeLearner` receives\n`own`, `action`, and the verified `relationshipTypeId`; the host must check\nthat the type represents guardianship, its terms are effective, and that\nits permission policy allows the action. An arbitrary relationship is not a\nguardian grant. Missing relationships and host denials/exceptions fail closed.\nThe authorizer also receives `executor`, the service's active database\nexecutor. Host policy reads, including relationship and revocation checks, must\nuse that executor so they share a `withTransaction` or `withExecutor` boundary.\nSame-tenant membership alone never grants sibling access.\n\n## Supported workflow\n\n- `getLearnerSetupStatus({ tenantId, actorUserId, learnerUserId })` is a\n  host-authorized onboarding probe for an active tenant member. It returns only\n  `{ needsSetup }`; it neither returns learner or relationship data nor grants\n  relationships. The host authorizer receives `education.learner.setup`, the\n  target user id, and the active executor. `provisionLearner` remains the write\n  path and still requires a directed guardian relationship.\n- `getLearner` returns authorized learner metadata and parsed settings.\n- `createCurriculum` creates a **planned** curriculum for an authorized guardian.\n  A learner cannot plan their own curriculum. Title is required.\n- `enroll` requires that guardian authority and a matching tenant curriculum.\n  It returns the existing enrollment for the same curriculum/course unchanged.\n- `startLesson` allows the learner or authorized guardian to create their own\n  enrollment's lesson progress in `in_progress`. It derives learner identity\n  from the validated enrollment. Repeated starts return existing state without\n  resetting counters, scores, completion, or timestamps.\n- `listProgress` reads only the validated learner/enrollment and lessons still\n  visible in that enrollment's course. Inconsistent persisted links fail\n  closed or are omitted from the list.\n\nService results are data-only views, with no persistence or database methods.\nExtra request fields are never model patches: a learner cannot set score,\nattempt count, or completion status through this API. Curriculum activation,\ncompletion transitions and dashboard aggregation are not supported by this\nbase service. SubmissionService extends its owning transaction/auth boundary for\ncapture and guardian grading; see [submission contract](submission-service.md).\nDirect model writes require trusted authority.\n\nCatalog visibility and child ownership reuse `CatalogService` on the same\nexecutor. Learner operations request private-inclusive catalog access, so the\nhost catalog authorizer must permit both `education.catalog.read` and\n`education.catalog.read-private` for the supported enrollment workflow.\nPrivate copies remain restricted to the exact owner. The service constructs a\nwhitelisted catalog request; caller options and answer-key flags are discarded.\nAnswer keys are never requested or returned. A catalog grant does not grant learner authorization.\n\n## Transactions and history\n\n`withTransaction(async transaction => ...)` composes service operations on the\ncallback's transaction-bound service. Use that service for every operation in\nthe unit. Throwing rolls back its curriculum, enrollment, and progress writes.\nThe callback's service closes when the transaction ends and rejects later calls.\nA failed mutation poisons the unit even if the callback catches its rejection;\nqueued mutations are cancelled. Callback failure stops pending work and waits for\nalready-running mutations to settle before rollback releases the executor. On\nsuccess, already-enqueued mutations finish before commit. Do not retain the\ncallback's service beyond the callback. The constructor\naccepts a root database; callers composing work use this method instead of\npassing an unmanaged transaction handle.\n\nPostgreSQL locks the parent curriculum/enrollment row before find-or-create.\nEmbedded writes use the core transaction queue. Concurrent mutations inside\none callback transaction are ordered on that connection, so duplicate starts\nwithin a `Promise.all` also return the same row. Database natural-key constraints\narbitrate enrollment `(tenant_id, curriculum_id, course_id)` and progress\n`(tenant_id, enrollment_id, lesson_id)` identities. Explicit storage conflict\nkeys include the tenant prefix because core does not add it to explicit keys.\nThe logical keys required by #3968 remain curriculum/course and enrollment/lesson:\nimmutable parent ownership and parent-tenant checks reject any second tenant\nfor the same parent. The storage prefix cannot create a second valid logical row. Ordinary repeated and concurrent calls\nreturn one row; an aborted workflow can be retried. No in-memory process lock\nis used for PostgreSQL concurrency.\n\nA new year is a new curriculum and enrollment, producing independent progress.\nUnscored `bestScore` persists as null; score zero is a real score. Scores are\nnullable decimals in [0,1]; counters are nonnegative safe integers. Settings\nare stored as JSON text and accessed through guarded `getSettings`/`setSettings`.\n\nThe shared executable workflows in `src/__tests__/learner-workflows.ts` run\nagainst SQLite and PostgreSQL, including actor/resource/context denial,\nconcurrent creation, rollback, history preservation, and zero/null scores.\nFull DuckDB schemas remain blocked by existing upstream DDL restrictions;\nno full learner workflow support on DuckDB is claimed.\n"
+    },
+    {
+      "path": "agents/submission-service.md",
+      "module": "submission-service",
+      "content": "# Submission and paper workflow\n\nConstruct `SubmissionService(db, authorizeLearner, authorizeCatalog, {storage,\nstoreOptions?, signAsset?})` from trusted server configuration. It extends\n`LearnerService`: the same active actor/tenant, memberships, linked person,\ndirected guardian relationship and host permission checks apply. The host must\nallow `education.learner.submit`, `education.learner.grade` or\n`education.learner.packet` as appropriate. Grade and packet actions always reject\nthe learner's own identity, even if the host authorizer returns true.\n\nThe protected transaction/auth hooks are internal owning-service extension\npoints. They are not handler APIs. All public service results remain data-only.\nUse the callback's service in `withTransaction`; escaped services are closed.\nSubmission operations share its serial queue, poison-on-failure behavior and\nPostgreSQL enrollment lock. No runtime schema creation occurs.\n\n## Capture and grading\n\n`captureSubmission` takes the learner request, `enrollmentId`, `lessonId`, a\nnonempty stable `requestKey`, and `pages` containing `name`, `mimeType` and Buffer\n`data`. Each upload becomes a fresh Asset owned by the learner's profile and\nexact tenant, joined solely through `SubmissionAsset`. Up to 100 uploads of\n25 MiB each are accepted (JPEG, PNG, WebP, or PDF). It atomically creates the\nsubmission/asset metadata and moves only that enrollment's progress to\n`submitted`, incrementing attempts once. Caller status, score, grader, asset ID,\nand answer-key flags are never patches. Equal request-key/content retries return\nthe existing submission; altered retries fail. Submitted/review/complete/skipped\nprogress rejects new captures. Content includes ordered filenames, MIME types,\nbytes and notes. Hosts should impose tighter request/body limits as needed.\n\n`captureBlankReference` records a workbook-page scan as immutable\n`blank_reference` evidence without advancing completion or creating a grade.\nTrusted ingestion scopes each receipt to the exact `enrollmentId` and calls\n`assertLessonAssignment` before reading retained evidence; it proves the active\ntenant, actor, learner, enrollment, and lesson without creating progress. A\nstable `intakeItemId` is claimed once in the durable tenant/item binding table,\nthen bound to the tenant, learner, lesson, progress, kind and predecessor; an\naltered retry fails. The binding is database-unique across enrollments while\nordinary uploads remain unbound. `resubmitSubmission` requires the current completed-work predecessor and\ncreates a new immutable `completed_work` attempt. Old pages, grades and feedback\nremain history; stale predecessors cannot be graded or replaced. A correction may\nreopen submitted, review or complete progress, while an AI proposal remains a\nnon-authoritative Grade until guardian review.\n\n`reviewSubmission` accepts an existing authorized submission and optional score\nand feedback. `attestLesson` creates/reuses an Attestation for a matching progress\nitem without requiring uploads. Both require a verified guardian and create a\nnew guardian Grade, set submission to `graded` and progress to `complete`.\nOmitted/null score is unscored; zero is a real score. The latest guardian grade\nwins over auto/AI/instructor proposals, and its score replaces progress's score.\nReview history is retained. ExternalCompletion is available for trusted server\npersistence; phase-zero learner handlers cannot forge reported scores. Online\nsubmissions and automatic grading are not implemented.\n\n`getSubmission` returns only submission metadata, page asset IDs and the selected\ngrade. It does not include catalog answers, extracted answers, storage paths,\nmodel objects, or database handles.\n\n## Storage and signed routes\n\nThe service creates an AssetRuntime bound to the operation's transaction. It\nrequires a resolved URI whose filename retains the fresh asset UUID and MIME\nextension; custom resolvers may choose its provider/directory but must route\nthat URI to the corresponding unique file. Shared existing locators are\nrejected before preservation or cleanup registration. It plans and persists\nthat unique asset URI before writing, registering that new\nasset for cleanup before the provider can partially write. After rollback,\nfiles are removed through the runtime store. Before deletion, the root database\nmust confirm that no asset owner committed: uncertain commit/read failures never\ncause committed bytes to be removed. Only this operation's newly created assets\nare candidates; pre-existing files are never adopted into its cleanup ledger.\n\nDatabase metadata is atomic; external storage uses compensation, not a database\ntransaction. If cleanup cannot complete, `SubmissionStorageCleanupError` contains\nfresh asset IDs and the original cause. Operators must reconcile those IDs in\nthe configured `education-page/<id>.<extension>` storage namespace (custom\nresolvers must retain their routing audit). A successful retry uses fresh IDs\nand cannot delete or reuse orphaned bytes. Process termination may also leave\nunreferenced files; hosts need storage orphan reconciliation. Do not suppress\ncleanup failures or claim crash-safe distributed atomicity.\n\n`signSubmissionAsset` verifies the submission/enrollment/learner ownership and\nits noun join, then verifies the Asset's tenant and learner profile before\ncalling the configured trusted signer. Claims contain actor, tenant, learner,\nenrollment, submission, asset and a five-minute expiry; no static source URI is\nreturned. The host signs every claim and its serving endpoint must verify the\nsignature, expiry, current actor/tenant and object authorization before serving.\nA bearer URL must never become a cross-family or sibling access bypass.\n\n`signLessonPrintable` signs only the exact authorized `printable` LessonAsset\njoin for an enrolled lesson. It never accepts an answer-key join and carries the\nsame tenant, actor, learner and enrollment scope as a submission claim.\n\n## Personal worksheet packets\n\n`splitWorksheetPacket` takes the guardian learner request, exact-owned\n`personal-use-copy` `courseId`, PDF bytes and ranges `{lessonId, firstPage,\nlastPage}`. Page bounds are inclusive and one-based. Ranges must be in bounds,\ndisjoint and target distinct Worksheet lessons in that private course. The\n50 MiB / 100-range limits are enforced before PDF parsing. `pdf-lib` extracts\nactual pages into independent PDFs and records private printable LessonAssets.\nAll resulting metadata commits together; storage failure compensates new PDFs.\nThe source packet is not retained. No shared/global course is accepted and no\nanswer-key join is created. A successful repeated packet upload intentionally\nadds another printable version; a failed upload can be retried safely.\n\nShared integration workflows run on SQLite and real PostgreSQL. Full DuckDB\nworkflow support remains outside the existing supported schema boundary.\n\n## Private asset boundary\n\nCaptured pages and split packet pages use `Asset.accessMode: 'private'` from their\ninitial insert. Ordinary generated Asset REST/MCP operations cannot list, hydrate,\nupdate or delete them, including through the parent STI model. The service opens\nan exact tenant/actor/learner-owner/asset-ID capability only after its normal learner\nrelationship checks. A host's signed serving route must repeat authorization and\nopen that exact capability before loading the asset. See the owning\n[private asset contract](../../assets/agents/private-assets.md).\n\nStorage must be private (including provider ACLs). Public HTTP(S) source locators\nare rejected; a hidden URL alone cannot protect publicly accessible bytes. Apply\nthe manifest migration adding `assets.access_mode` before deploying this runtime;\nlegacy ordinary assets retain the public default. Runtime creates no schema.\n\nPrivate lesson files must already be private Assets in the same tenant. Saving\nan answer-key join, or any join under a personal-use-copy course, requires the\nhost's exact actor/owner/asset capability; a public asset is never automatically\npromoted. Packet splitting retains this capability while creating each join.\nPersisted course tenant/license and section/lesson parent identity cannot change;\ncreate new structure and explicitly re-author its joins instead. Mandatory\nwrite predicates enforce this even for natural-key adoption and concurrent writes.\nOrdinary content and metadata refresh remains supported. This\nprevents existing public material being reclassified by moving its parent.\n\nFor pre-existing invalid joins, an authorized host must inventory private-material\njoins and remove invalid associations, recreate the bytes in private storage as a\nnew privately classified Asset, then re-author the join under its exact capability.\nDo not merely hide the URI, mutate access_mode with raw SQL, or delete shared\npublic bytes. This repair requires explicit storage/ownership authorization;\nnormal runtime does not migrate existing records.\n"
+    },
+    {
+      "path": "agents/workbook-service.md",
+      "module": "workbook-service",
+      "content": "# Physical workbook contract\n\n`WorkbookService` extends `SubmissionService` with the same actor-bound authorization,\nprivate asset runtime, transaction executor and guardian Grade boundary. Both\nLearnerAuthorizer and CatalogAuthorizer receive the active executor. Host session\nheartbeats and current permission checks must use that supplied executor, including\nnested guardian review; a captured outer pool can wait on its own transaction.\nCatalogService obtains the executor through the public collection.db getter and\nfails closed when its four catalog collections do not share the same handle. It is an\nadditive API; existing Submission/Grade consumers retain their contracts. The six\nclosed `Workbook*` models are package-manifest models. Apply normal application\nschema migrations before using them; the service never creates runtime schema.\n\nA guardian calls `resolveWorkbookActivity` with an explicit learner, workbook key,\ntitle, edition (empty means unknown), page key and printed page label. Keys identify\nthe physical copy/edition and page occurrence, including section/side where needed.\nNames and photo hashes do not establish identity. A conflicting reuse fails. One\nprivate personal-use-copy course/enrollment per learner/workbook supplies internal\nsubmission scaffolding. The public page API needs no course-building workflow.\n\n`captureWorkbookWork` owns original files through SubmissionAsset and creates an\nimmutable attempt with source SHA-256 hashes, actual page bounds, actor, capture\ntime, assistance, correction predecessor/episode, policy version and effective\nreview-required flag. Assistance defaults to `unknown`. Capture retries reuse the\nsame Submission/attempt and reject changed bytes or help claims. A correction\nrequires the same learner/activity/current predecessor and stays in the same\npractice episode. Analysis/reanalysis adds revisions, never practice attempts.\nExisting LessonProgress.attempts remains a compatibility capture counter.\n\nThe workbook review-required policy defaults on and is shared by its pages.\n`setWorkbookFeedbackPolicy` uses expected policy version; existing capture snapshots\nremain unchanged. Policy changes cannot erase prior disclosure. Guarded capture,\npolicy and decision writes serialize on the learner within the active transaction.\nIngestion target resolution acquires that learner lock before the enrollment lock,\nmatching capture/review order. Guardian apply follows authorized timeline cursors\nwhen locating a preserved assessment on an older attempt.\nComposite mutations also use the education transaction's serialized composite\nqueue, allowing inherited queued capture/review writes without queue recursion.\nAny swallowed mutation error still aborts the complete transaction and file rollback\nuses the inherited fresh-file compensation ledger.\n\n## Structured assessment and real ingestion\n\n`WorkbookAssessment` version 1 has stable question IDs, original/corrected prompt\nand answer text, explicit result/reason, nullable points, feedback, retained source\nanchors and curated concept mappings. An anchor names an owned asset plus SHA-256,\none-based verified page (or null for a whole-file PDF source) and normalized\nx/y/width/height rectangle. Ingestion proposals never generate rectangles: the\nservice uses [0,0,1,1] and explicit source/page grounding with limitations. The provider wire contract\ncontains evidenceId only, with no page/rect selector. An image is a known single\npage; PDF questions retain a whole original-file anchor with page:null, not a\nclaim about page 1. Extraction metadata remains provenance, never a model page\nlocalization grant. Fictitious PDF\npages and foreign files fail. Missing, illegible, unsupported and absent questions\nare unassessed; unassessed points stay null. Marking certainty, mapping certainty,\nmapping review provenance and evidence limitations are distinct; absent certainty\nis explicitly persisted as unknown. Reviewed overrides append new bodies and keep\noriginal AI text inspectable.\n\nThe configurable vocabulary is trusted server configuration, not AI-created labels.\nThe default `WORKBOOK_MATH_VOCABULARY` has addition, subtraction and place value.\nOther subjects may use an explicit curated `workbookVocabulary` on WorkbookService,\nthe ingestion handler factory and preservation helper. Unknown concept IDs fail;\nzero mapped concepts is valid. AI mappings are proposed, guardian mappings reviewed.\nKnown question IDs are pinned across captures; exact prompts are pinned within a\ncapture's reanalysis only. Correction transcriptions come from the new capture,\nso earlier answer-bearing prompts cannot override corrected work. Immutable\nhistorical prompts remain unchanged. The public `getWorkbookQuestionIdentity`\nreturns IDs only: historical prompt text can itself include a learner response.\nHandlers use printed number/occurrence/subpart when present; unnumbered tasks use\nanswer-free printed-task slugs with visible-task occurrence/subpart, never output\narray position or learner answers. They\nread prompt, answer, feedback and marks exclusively from current evidence. New\nprompts should contain printed task text without the learner response. An absent\nor ambiguously matched known question is unassessed/not_present with an explicit\nlimitation. Missing, duplicate, invented or foreign IDs reject the proposal; a\nchanged question order does not change identity. The ID check does not establish\nsemantic equivalence of printed tasks; uncertain correspondence requires human\nreview rather than an invented match.\nA different page/question requires explicit new activity identity, never AI retargeting.\n\n`captureEducationIntake` accepts optional `workbookActivityId`/`assistance` when its\nservice is WorkbookService. It preserves the existing return SubmissionView and\nbinds the workbook attempt/policy before the host queues processing.\n`educationIntakeHandlers({workbookActivityId,...})` advertises a bounded JSON question\nschema to real ingestion generation. Assessed results require reason none;\nunassessed reasons require null points. Per-question outcomes must agree with\npoints. Correctness is independent of scoring: readable objectively solvable\narithmetic may be assessed without a printed rubric. When no point allocation is\nevidenced, both `points` and `possiblePoints` remain null for every result,\nincluding incorrect; never invent weights or mix null/numeric values. The\naggregate still counts correct/incorrect results while its score remains null.\nIncorrect earns zero only when the possible-point allocation is known.\nModel aggregate scores/narratives are not requested or trusted: exact\ncount summaries and points scores are computed from validated questions without\nrounding or invented partial credit. Default legacy handlers remain compatible.\n`preserveWorkbookIntakeAnalysis` reads the public immutable completed generation,\nchecks its exact submission and offered workbook schema, maps cited original\ningestion evidence by hash/order to retained education-owned files and imports one\nvalidated proposal. Provider/model/version, configuration/rubric, source analysis\npin and proposal digest are durable provenance. Pending/failed processing produces\nno assessment. Malformed/ambiguous/foreign-source proposals return typed needs_review with no\neducation revision or Grade. The host can offer retry/review without a route 500.\nAuthorization, durable-source integrity and database failures still throw. Repeated\ntransfer is idempotent by analysis attempt. Preservation must complete before host\nscratch retention cleanup; there is no automatic retention bypass in this API.\nThe ingestion handler can apply only an exact previously preserved proposal through\nguardian review; it never grants AI grade authority. No prose parsing is used. The generation configuration carries bounded source\nhash/page-support provenance from the completed extraction before it ceases to be\nthe current analysis. This uses public ingestion APIs and is pinned by its\nconfiguration digest; question anchors always use honest source-only grounding.\n\n## Authority, visibility and history\n\n`recordWorkbookAnalysis` accepts authorized submit context and writes provisional\nAI revisions only. `reviewWorkbookAssessment` requires guardian authority, exact\nsource revision, expected current guardian head and stable request key. It appends\nan immutable guardian revision recording sourceRevisionId, superseded head, actor,\ntime and decision reason. Changed retries conflict. Review of the current capture\nuses the existing guardian Grade/progress boundary. Historical annotation changes\nits evidence authority only and cannot grade or reopen its successor. Reanalysis\nafter a guardian decision remains provisional. A guardian can invalidate an outcome\nwith an unassessed replacement and a stated reason; old AI does not regain authority.\n\n`releaseWorkbookFeedback` separately releases an exact revision using expected\ncurrent guardian head. New stale releases fail; accepted retry requests replay their\noriginal result after later decisions. Release creates no Grade. With the gate off,\nAI feedback is visible as provisional while authoritative grading still requires a\nguardian. Gate-on learners receive no unreleased assessment payloads, scores or\nhints. WorkbookService's ordinary getSubmission also redacts Grade for own learners;\nhosts must route workbook reads through this service and prevent legacy routes from\nserving workbook grades. Guardian history is complete; learners see only their own\nwork and visible revisions. Answer keys/source storage URIs never enter these DTOs.\n\n`acknowledgeWorkbookFeedbackDelivery` is an authenticated own-learner acknowledgment\nfor an exact currently visible feedback revision. It deduplicates per actor/revision\nand rejects withheld, foreign, sibling and guardian acknowledgments. Immutable\ndelivery events record actor/time and mean rendered/delivered, never read or understood.\n\n`getWorkbookTimeline` uses education rows/assets without reading ingestion. It lists\nnewest captures/revisions first, includes all releases/delivery events and provides\ncursor pagination (1–100, default 25). A guardian revisionId selector locates its\ncontaining capture for evidence links. Guardian source IDs/actors/reasons remain\ninspectable. Released historical revisions remain visible after supersession.\n\n`getConceptEvidenceSummary` is guardian-only for this milestone. It recomputes from\ncurrent guardian revisions, separates provisional observations, and reports independent,\nassisted and unknown evidence. Correction captures remain one episode; they cannot\nbe extra independent demonstrations. Every observation cites capture, question,\nrevision, episode, result, assistance and time. Unassessed work is excluded from\nerror/correct counts. Descriptive cues cite actual evidence: needs practice, improving\non this item, needs a fresh independent check, not enough evidence. No mastery\npercentage, generic score comparison, hidden threshold or predictive label is used.\n\n## Preserved processing status and retention\n\n`getWorkbookPreservationState` authorizes exact actor/learner/activity/submission\nand returns only the intake ID plus retained assessment/analysis IDs and the\ninterpretation revision. It contains no questions, scores, feedback or hidden\nassessment payloads. New AI provenance records `analysisRevision` from the\ncompleted interpretation snapshot, separately from its extraction-source pin.\n\n`preserveWorkbookIntakeAnalysis` checks this education-owned state and the public\ncontent-free ingestion item revision before requesting raw completed analysis.\nAn exact already-preserved revision returns `retained` immediately. Guardian\nreview, release, corrections and receipt expiry therefore do not force a stale\nproposal reread or prevent durable education history from loading. The public\ningestion stale-snapshot guard remains unchanged and still rejects the old raw\nsnapshot after guardian grading. A genuinely new valid analysis can append a new\nprovisional revision; a novel stale analysis returns `needs_review/stale_analysis`\nand creates no mark. Legacy retained rows without interpretation revision remain\nreadable when scratch is stale/unavailable or the public\nProposalsNotConfiguredError reports removed provider read configuration. A novel\nanalysis with no provider read configuration returns unavailable without import; an authorized current snapshot whose\nattempt ID is already retained is also skipped before retry reconstruction.\n\nOnly the exact public scratch `Intake unavailable` response is translated to\nretained history, or `unavailable` for a capture with no retained assessment,\nafter independent education authorization. Missing/pending current analysis may\nreturn pending or retained. Unexpected configuration, integrity and database\nfailures still throw. This does not widen scratch access: no stale or unavailable\nraw proposal is read, imported or used as grade authority. Hosts must also render\nthe authorized education timeline independently of optional scratch processing.\n\n## Compatibility API privacy boundary\n\nWorkbook feedback is projected only from the revision/release workflow. The base\n`SubmissionService` recognizes authoritative `WorkbookActivity` lesson ownership,\nincluding calls through a plain service instance. Own-learner compatibility views\nwithhold Grade and grade-derived status; learner progress projections withhold\nbestScore/completedAt and do not let completion alter next-lesson selection.\nGuardian and ordinary non-workbook projections retain their existing behavior.\nThis applies in both feedback policy modes; direct feedback remains provisional\nand does not authorize compatibility Grade disclosure.\n\nGeneric capture/resubmission rejects workbook enrollment or lesson scaffolding,\nincluding idempotent retries. Only the protected exact-activity owning workflow\ncan capture workbook work. Hosts must call public\n`assertNonWorkbookSubmissionScope` before legacy intake receipt creation and when\nreading an old legacy binding, using authoritative enrollment, lesson and\npredecessor selectors. `WorkbookWorkflowRequiredError` is a controlled denial.\nThe browser's optional workbook flag is never authority. Authenticated original\nasset delivery remains a separate read authorization path.\n\n## Validation and limits\n\n`src/__tests__/workbook-workflows.ts` is the shared SQLite/PostgreSQL contract suite;\n`workbook-service.test.ts` runs SQLite, and `workbook.optional.test.ts` runs against\nan available isolated PostgreSQL database. Workers never provision service stacks.\nRun package test/typecheck/build; the integration owner runs test:postgres and the\nintegrated review. Synthetic provider DTO tests establish transfer integrity, not\nreal handwriting accuracy. Actual provider/sample and app restart/retention\nacceptance remain separate integration evidence. Family deletion/export/backup\npolicy and automatic lesson generation are not implemented by this milestone.\n\n## Identity-independent work\n\n[Photo intake](photo-intake.md#marking-before-filing) may own an explicit unfiled\nwork unit. Its nullable workbook FK is constrained to an exact retained receipt;\nprivate enrollment/worksheet routing is technical rather than bibliographic.\nThe same attempt/assessment/review/release and concept-evidence contracts apply.\n`filing` is optional on legacy-shaped DTOs and explicit on current projections.\nAppend-only filing changes display association only; it never moves immutable\nlearning evidence or changes captured review policy. Ordinary identified workbook\nidentity and generated-surface restrictions remain unchanged.\n\n### Unnumbered visible questions\n\nA printed question number is not required for marking. On the first valid\nassessment, an unnumbered task may use `u:<short printed-task slug>:<occurrence/subpart>`\nfrom current answer-free task text and unambiguous visible task identity. The\noccurrence distinguishes tasks in the source, never positions in a generated\nquestions array. Responses, computed solutions and changing evidence UUIDs cannot\nsupply identity. Printed IDs remain useful where present; both forms share the\nexisting nonempty/unique ID schema and 200-character bound.\n\nOnce preserved, the exact ID set remains pinned on reanalysis and correction.\nReordering output does not renumber tasks. A cropped, duplicate or illegible task\nwhose correspondence cannot be established remains `unassessed/not_present` with\na limitation on its known ID; it cannot be silently relabeled as another task.\nHistorical IDs are correspondence hints, not evidence of current responses.\nMissing IDs, collisions, changed ID sets and same-capture prompt remapping still\nfail closed. The framework never inserts omitted provider IDs or parses prose to\nrepair malformed proposals.\n\n### Semantic identity visibility\n\nQuestion IDs can contain printed task text. Own-learner identity reads and\noperation discovery therefore require release of the **selected exact revision**\non a guardian-origin source attempt. An unrelated revision or another attempt's\nrelease is insufficient. Ordinary own-origin IDs remain available for legitimate\ncurrent-work marking and corrections without exposing withheld grades/feedback.\n\nCorrection ancestry is checked completely under the same tenant, learner,\nactivity and practice episode. Each guardian-origin ancestor must have an exact\nreleased revision publishing the compatible immutable ID set before a descendant\ncan expose those semantic IDs. Matching published ID sets preserve already public\nhistorical snapshots after a later private head, without aliases or rewritten IDs.\nMissing, corrupt or cyclic ancestry fails closed; there is no depth cutoff that\nsilently skips earlier source guards. Current descendant release never grants\nrights to a hidden ancestor.\n\nThe same boundary governs child correction capture, timeline payloads and delivery\nacknowledgments, including legacy/trusted-produced descendants. Raw provisional\nrevision writes/returns cannot probe or replay guardian-origin private content;\nauthorized guardians retain processing/history access, and own-origin correction\nmarking remains supported once ancestral source identity is published. Schema,\nID collision/remapping rules and immutable stored history remain unchanged.\n\nThe offered marking schema mirrors the assessment validator: assessed results use\n`markingCertainty` clear/unknown; `uncertain` marking requires `unassessed`, an\nallowed non-none reason and both point fields null. This is not a conversion of\nprovider output: contradictory results remain refused. Mapping certainty remains\nindependent. Visible but overwritten/ambiguous responses can stay unassessed while\nother clearly visible questions are assessed in the same valid proposal.\n\n### Observed assessment layout\n\nOptional `WorkbookAssessment.layout` version 1 describes observed sections in source\norder and zero-based row/column question placements. It is advisory, with fixed\n`provenance: 'observed'`; it never establishes identity or verified geometry.\nSections reference a retained source asset and a physical one-based observed page,\nor null when unknown. A whole-file PDF anchor may support an observed page within\nits retained page count while keeping its original anchor page null. Every placed\nquestion must anchor the section's exact source. Multiple question IDs may share a\ncell. When every placement in a cell has an explicit `part`, sort by part then\noriginal question array index for ties. If any placement in that cell omits\n`part`, the whole cell follows original question array order. Partial placement is valid. Missing `readingOrder` preserves original\nquestion order for a flattened display.\n\nThe browser-safe `normalizeWorkbookObservedLayout` copies only bounded known\nfields: at most 32 sections and 200 placements, 1–8 columns, rows 0–199, parts\n0–31, section IDs up to 64 characters and labels up to 200. Duplicate section IDs\nor question placements, invalid source/page/placement references and malformed\nmetadata discard the complete optional layout and retain `layoutOmission: 'invalid'`.\nValid answers and normal assessment validation remain independent. Owning analysis\nand guardian writes both normalize against the current capture's source hashes;\na correction cannot inherit a previous capture's source layout. Default guardian\ncopies retain valid layout and safe omission markers. Bodies remain immutable JSON\ninside existing revision privacy and exact release boundaries; no migration or\nadditional learner visibility is introduced.\n\nFocused shared SQLite/PostgreSQL cases live in\n`src/__tests__/workbook-layout-workflows.ts`, with SQLite in\n`workbook-layout-service.test.ts` and isolated PostgreSQL in\n`workbook-layout.optional.test.ts`. Pure bounds/reference cases are in\n`workbook-layout.test.ts`. Integration runs the PostgreSQL wrapper under its\nexisting isolated database lifecycle.\n\nGeneration carries optional `layout` as advisory JSON so malformed presentation\ncannot make valid question answers fail the generic schema. Its described wire\nshape uses original evidence IDs; the bridge maps those IDs to retained assets\nand then calls the strict owner normalizer. Within existing transport/JSON resource\nlimits, wrong types, unknown versions and conflicting metadata are omitted with\nonly the safe marker, while answers retain their normal strict validation. Layout\nnever establishes a question ID, a source authorization or a verified region.\n\n\n### Same-capture reread context\n\n`getWorkbookQuestionContext` returns authorized canonical `{id,prompt}` only\nfrom the exact current attempt's identity revision. Generation preserves those\nstrings verbatim for the existing strict same-capture prompt invariant, while\nrereading learner responses and any observed layout from current evidence. This\ncontext is not an answer key or authority for answers. A correction without its\nown revision receives predecessor IDs only; predecessor prompts are never copied.\nExact source/revision and full correction-ancestry visibility apply to both paths,\nincluding own-learner reads. No historical rows are rewritten and absent layout\nremains valid. `getWorkbookQuestionIdentity` remains the IDs-only public API.\n\nCanonical prompts follow ordinary assessment payload visibility, including\ncaptured review policy and exact guardian revision release even for learner-owned\nsources; source/ancestry authorization alone does not publish guardian edits.\nFor ingestion callbacks only, the engine supplies current `analysisRevision` from\nits owned item row. Context selection ignores AI materialized by that exact\ncurrent-attempt revision, so preserving a proposal does not invalidate its own\ncompleted snapshot or preview. It never ignores guardian decisions, predecessor\nrevisions or another interpretation. Direct reads omit this engine pin and retain\nnormal current revision visibility; browser/upload fields cannot supply the pin.\n\n### Observed answer-region overlays\n\nOptional `answerRegions` version1/provenance observed/coordinateSpace\n`display-oriented` carries one approximate rect `[x,y,width,height]` per question,\nwith exact retained asset/page1 and observationId. Rects are normalized to the\nwhole EXIF-oriented image; they never change question IDs, grading, anchors or\nlayout, and never claim verified geometry. Images only in this version; PDFs or\nunknown positions omit regions. Direct malformed metadata is omitted with safe\n`answerRegionsOmission: invalid`; marking/layout survive independently.\n\nVision catalogs originate in the existing opt-in extraction call. Generation\nreferences exact evidence/observation IDs, never supplies coordinates. The bridge\ncopies catalog rectangles from the extraction-pinned configuration with matching\nsource hash. Guardian copies retain them; correction sources must match current\nanchors. Existing exact release and ancestry privacy apply to the complete body.\n"
+    },
+    {
+      "path": "agents/photo-intake.md",
+      "module": "photo-intake",
+      "content": "# Photo-first workbook intake\n\n`WorkbookPhotoService` extends `WorkbookService` with the same constructor,\ntransaction executor, actor/tenant checks, private storage and rollback ledger.\nImport server integration from `@happyvertical/smrt-education/ingestion`.\nApply manifest migrations for `WorkbookPhotoIntake`, `WorkbookPhotoAsset`,\n`WorkbookPhotoDecision` and `WorkbookContextRevision` before deploying. There is\nno runtime schema creation and these models expose no generated operations. Each\nconcrete table declares its own tenant/learner fields; a custom abstract model\nbase does not supply persisted columns to independent manifest tables.\n\n## Receipt before assignment\n\nConstruct the service and `IngestionService` from one authenticated server session.\nUse `scope.confidentialScopeId = request.learnerId`, not an enrollment or model\ninference. `authorizePhotoIntake(request)` authorizes a learner's own upload or a\ncurrently authorized guardian before `receiveWorkbookPhotoIntake({ingestion,\nscope,workbooks,request,receive})` calls ingestion. Its result is `{receipt,intake}`;\n`intake:null` means no successful durable receipt. `retainWorkbookPhotoReceipt`\nrepairs an interrupted education copy from an existing authorized receipt.\n\nThe immutable education receipt retains the original bytes as private Assets\nthrough the sole `WorkbookPhotoAsset` owner join, preserving ordered SHA-256\nhashes. Copy retries reject changed bytes, filenames, media types or learner\nownership. Storage uses the inherited fresh-file compensation ledger; borrowed\nhost executors cannot perform file writes. Provider failure does not delete the\nreceipt or originals. `getWorkbookPhotoIntake`, `listWorkbookPhotoIntakes` and\n`readWorkbookPhotoOriginal` reauthorize exact ownership independently of scratch\nretention. A learner cannot list/read guardian-uploaded pending or context-only\nmaterial. Guardian-origin lesson source remains private until an explicit\nfeedback release on its exact captured attempt, regardless of automatic material\nclassification or the workbook provisional-feedback setting. Guardian reads remain\nsubject to the current relationship and grants. Child-owned uploads retain the\nnormal learner boundary.\n\n## Provider identification and human decisions\n\nConfigure `workbookPhotoIntakeHandlers({workbooks,request})` and\n`workbookPhotoIntakeTargetResolver({workbooks,request})` on ingestion's execution\ncatalog, and the normal proposal generator/read configuration. Handler\n`@happyvertical/smrt-education:identify-workbook-photo` uses\n`@happyvertical/smrt-education:WorkbookPhotoIntake:get@1` and\n`workbookphotointakes.read`. This operation classifies only; applying it never\ncreates a Grade. Keep `requireReview:true`. Candidate freshness checks use the\nsupplied executor and the exact authorized workbook/context digest.\n\nThe initial immutable captured ceiling must include all intended later stages\nand a provisioned stable execution principal; for marking, include the existing\nreview-submission/Grade operation as well. Current guardian authorization still\ncontrols every Grade. Never widen the receipt ceiling after upload or create a\nsecond receipt to evade that boundary.\n\nQueue with `queueEducationExtraction`, process extraction/interpretation with\n`processEducationAnalysis`, then call `preserveWorkbookPhotoIdentification`.\nAlternatively `processWorkbookPhotoAnalysis` combines processing, preservation\nand capture of a confidently resolved **completed** lesson. It returns\n`{processing,intake,capture,assessmentRequired}`. The provider runs outside the\neducation transaction. Preservation reads the current public immutable ingestion\nsnapshot, exact offered schema and original hashes; it retains analysis IDs,\nrevision, digests and provider/configuration provenance in append-only decisions.\nUnavailable, failed, stale, malformed and ambiguous results leave durable intake\npending. A provider needs-review outcome, alternatives or splits never authorize\nautomatic resolution; its original proposal remains inspectable. Literal page\nnumbers cannot establish lesson identity. Authorization/integrity/database failures still throw.\n\nProvider output distinguishes lesson, cover, reference (including contents and\nanswer keys), and uncertain material, plus blank/completed/unknown work state.\nAutomatic book identity requires a printed ISBN or complete printed\npublisher/title/edition quotations. Title alone never merges. An existing book may instead match exact current printed title/edition to one\nauthorized contextual record with retained publisher provenance; that publisher\nis context, never a fabricated current quotation. Conflicting or ambiguous\nmatches stay pending. Provider\ncandidates contain book metadata only, never reference text or answer keys.\n`listWorkbookPhotoWorkbooks(request)` includes cover-only books for the provider\nand guardian picker. A printed lesson identity supplies one stable activity key;\nmultiple page files may belong to that same lesson. Page number alone cannot\nautomatically establish lesson identity.\n\nA guardian may call `resolveWorkbookPhotoIntake({...request,intakeId,requestKey,\nidentification})` after upload. It requires planning authority and appends a new\ndecision. Stable request-key retries replay; changed retries conflict. Covers and\nreferences create/reuse the Workbook and append contextual metadata only: no\nCourse, Lesson, progress, attempt, Grade or concept observations. Existing\nWorkbook title/edition identity never changes; context versions retain original\nmetadata and source receipt identity. A captured intake cannot be retargeted.\n\n## Existing marking pipeline\n\n`captureWorkbookPhotoIntake({...request,intakeId,requestKey,assistance?,\npreviousSubmissionId?,completedWork?})` copies the retained originals through\n`captureWorkbookWork` and returns its immutable attempt. Blank or unknown work\nrequires explicit `completedWork:true`; no blank exercise is automatically marked\nas unanswered learner work. Corrections require the explicit current predecessor\nand preserve the existing practice episode. Existing attempts reject automatic\nreplacement; provider classification cannot silently turn a new photo into a\ncorrection.\n\nAfter capture, configure the existing `educationIntakeHandlers` with the returned\nsubmission ID, `view.activity.id`, and authoritative activity enrollment ID.\nQueue `queueEducationExtraction(ingestion,view.itemId,configuration,submissionId)`\non the **same learner-scoped receipt**, process normally, then use\n`preserveWorkbookIntakeAnalysis`. That bridge already verifies exact education\nownership and source binding independently of the receipt's confidential scope.\nGuardian Grade/release policy and immutable assessment history are unchanged.\n\n## Verification matrix\n\n`src/__tests__/photo-intake-workflows.ts` runs on SQLite and available PostgreSQL\n(`photo-intake.test.ts` / `photo-intake.optional.test.ts`).\n`photo-intake-manifest.test.ts` separately pins all concrete ownership/provenance\ncolumns and UUID/FK definitions in the generated structured manifest. It covers actor/resource\nownership and active context, private originals, sibling/foreign asset denial,\nretry conflicts, concurrent deduplication, rollback and borrowed executor denial,\ncover-only context and immutable identity, ambiguous titles, source integrity,\nblank work intent, multi-page capture, real ingestion generation for cover then\nlesson, provider failure, and guardian-only pending/reference originals. The same\ntransaction executor is used for authorization and mutations. Real provider\nhandwriting accuracy and deployment worker isolation remain host acceptance.\n\nRun package test/typecheck/build; integration owns PostgreSQL provisioning and\nfull-suite validation. Workers never start containers. This is additive feature\nwork; a base regression run is N/A because no pre-activity capture API existed.\n\n## Guardian-origin source privacy\n\nThe immutable photo receipt actor, compared with the persisted learner user,\ndetermines source origin. Classification as a lesson does not grant learner\naccess. `Submission.intakeItemId` joins the exact tenant/learner receipt; only a\n`WorkbookFeedbackRelease` on that submission's exact `WorkbookAttempt` releases\nits source. Another attempt or context-only page cannot borrow that release.\n\nThe base `SubmissionService` applies this policy too: own learners receive no\npages, notes, Grade/feedback or grade-derived status before release, and signing\na guessed source asset is denied. The DTO exposes `awaitingParentRelease:true`\nfor an own learner awaiting release, and `sourceRequiresParentRelease:true` to\nall authorized actors for guardian-origin material. The latter remains true\nafter release: every new derived revision still needs its own explicit release.\n`WorkbookAttemptView.reviewRequired` and persisted capture policy snapshots\nretain their historical workbook setting; combine that setting with\n`submission.sourceRequiresParentRelease` when describing effective visibility. Workbook timeline and\nfeedback delivery acknowledgment require exact revision release for this source,\neven when the general workbook policy permits provisional AI feedback.\n\nExisting hosts without photo schema retain ordinary submission behavior through\noptional table-existence checks; no application schema is created at runtime.\nThe shared SQLite/PostgreSQL privacy case covers guardian-origin mistaken lesson\ncapture, policy off, automatic AI and guardian assessment before release, direct\nbase submission reads/signing, exact release, later unreleased reanalysis and a\ndifferent attempt that stays private. Existing own-learner capture cases remain\nreadable, and legacy submission/workbook suites protect consumers without photo\ntables.\n\n## Existing candidate identification\n\n`workbookId` selects an exact authorized candidate; it does not replace the\nrequired `identification.workbook` contract. Copy that candidate's `workbookKey`,\n`title` and `edition` into the required object. Those are catalog identity fields,\nnot invented IDs or claims about what is printed on the new photograph.\n`identityEvidence` quotes only current visible material. A unique current\ntitle/edition may match retained publisher provenance without publisher/ISBN\nbeing reprinted. Conflicting identity, duplicate candidates and title-only\nmatching remain pending; malformed model output is never repaired automatically.\n\n## Exact receipt authorization\n\nProcessing and retries resolve `context.itemId` through the service-owned\n`getWorkbookPhotoIntakeByItem` lookup, scoped to the current tenant and learner\non the supplied executor. It delegates to the same current actor and private\nsource/release checks as the intake-ID getter. The inbox list remains capped at\n1,000 rows for display; that pagination window is never an authorization or\nlifetime receipt limit.\n\nHosts may opt into `listWorkbookPhotoIntakes(request, { newestFirst: true })`\nfor a current inbox. Default ordering remains unchanged and both orders keep the\n1,000-row display bound and the same per-receipt visibility checks. Exact selected\nreceipt reads remain independent of either display window.\n\n## Marking before filing\n\nCompleted learner work does not require a printed lesson number or workbook\nidentity. Identification `kind:'work', workState:'completed'` deliberately omits\n`workbook`, `activity` and `workbookId`. Its confidence concerns observable learner\ncompletion/material kind, independently of bibliographic identity. Printed worked\nexamples, answer keys, blank pages and uncertain material are not completed learner\nwork. `kind:'lesson'` retains the existing strict printed identity contract.\n\nConfident work preservation creates one receipt-bound **unfiled** work unit.\n`processWorkbookPhotoAnalysis` captures it and returns the existing\n`capture/assessmentRequired` result. Queue the normal assessment stage on that\nsame receipt, submission and returned activity/enrollment IDs; do not re-upload or\ncreate another receipt. Visible responses can be assessed while illegible or\nambiguous responses remain unassessed. The extraction observation contract keeps\nprinted examples separate from learner marks and reports matching endpoints only\nwhen observed. Adopt it with a new extraction configuration revision.\n\nThe internal private Course/Enrollment/Worksheet are routing records, not a claim\nabout a canonical book or lesson. `WorkbookActivity.workbookId` is null only for\nexplicit `captureKind:'unfiled'` with an exact owned `photoIntakeId`; all ordinary\nidentified activity invariants remain. No Workbook is invented. Activity DTO\n`filing.state` is `unfiled`, `filed` or `identified`; empty workbook title/key/edition\non unfiled work are intentional. Use the work label as the primary display.\n`listWorkbookActivities` includes these work units. Exact\n`getWorkbookPhotoTimeline({...request,intakeId,limit?,cursor?,revisionId?})`\nreturns existing authorized feedback/history; the normal activity timeline also\nworks. `getWorkbookActivity` refreshes exact filing presentation without loading\nhistory. The receipt view refreshes filing rather than replaying its old label.\n\nOptional guardian `fileWorkbookWork({...request,activityId,workbookId,\ncanonicalActivityId?,expectedRevisionId,requestKey,reason})` appends an association\nto a real authorized workbook and optionally a real identified activity. Initial\nexpected revision is null. Stable retries replay their original accepted result;\nchanged retries/stale heads conflict. Filing does not move or recreate activity,\nsubmission, attempt, assessment, release, source or correction episode IDs. It\ncannot change captured review policy, create a Grade, duplicate concept evidence,\nor release guardian-origin material. Future corrections continue against the\noriginal work-unit ID and explicit current predecessor. Existing identified\ncaptures cannot be retargeted through filing.\n\nApply normal manifest migrations before using this contract. Existing activities\nreceive `capture_kind='identified'` through the declared database default; the\nworkbook FK becomes nullable and photo-intake FK plus filing table are added.\nOld populated SQLite requires the explicit supported nullability-relaxation\nmigration described by #4413; no runtime DDL or manual SQL workaround is allowed.\n\nWhen no book record exists, the same optional filing operation accepts\n`newWorkbook:{title,edition?,workbookKey?}` instead of `workbookId`. Exactly one is\nrequired. Parents need only title/edition; an omitted key becomes an opaque stable\nmanual identity for this work/request, never an automatic title-based match.\nAn explicit existing key must retain its exact title/edition. New metadata cannot\nalso claim `canonicalActivityId`. Book creation and filing share the guardian's\nserialized transaction: stale/unauthorized/conflicting requests create nothing,\nand a later failure rolls both back. No cover re-upload, canonical lesson,\nsubmission replacement or second assessment is needed. New books keep the default\nreview policy; filing never changes the source attempt's captured policy.\n\n## Exact cover context for header selection\n\n`getWorkbookPhotoIntake` adds optional nullable `workbookId`, loaded from the latest\nretained resolution's exact WorkbookContextRevision under the same tenant/learner\nand decision ID. Pending/uncertain or unfiled-work resolution returns null; this is\nindependent of a later activity filing. It never guesses from title or an inbox\nlist. Existing guardian-origin receipt privacy still applies before lookup.\n\nHeader cover camera/upload uses the normal receive/process photo flow. A confident\ncover resolves book/context only, with no attempt, lesson or Grade. Read that exact\nintake, then let the guardian explicitly choose `fileWorkbookWork({workbookId,...})`.\nAn uncertain cover can use the existing guardian `resolveWorkbookPhotoIntake` with\nmanual cover metadata, followed by the same exact getter and explicit filing.\nNeither cover identification nor context alone publishes learner source/feedback.\n"
     },
     {
       "path": "agents/source-import.md",