@happyvertical/smrt-education 0.57.32 → 0.57.34

package/dist/ingestion.js

@@ -1,6 +1,7 @@
+import { F as WorkbookAssessmentValidationError, I as aggregateWorkbookQuestions, L as validateWorkbookAssessment, P as WORKBOOK_MATH_VOCABULARY, R as workbookAggregateFeedback, f as validateWorkbookPhotoIdentification, m as normalizeWorkbookAnswerRegions, n as preservePhotoProposal, p as normalizeWorkbookObservedLayout, r as WorkbookService } from "./chunks/workbook-photo-service-1wcnf-Xf.js";
 import { getCurrentTenant, withTenant } from "@happyvertical/smrt-tenancy";
 import { registerPermissionDefinitions } from "@happyvertical/smrt-users";
-import { extractAnalysis } from "@happyvertical/smrt-ingestion/server";
+import { GenerationSnapshotStaleError, ProposalsNotConfiguredError, extractAnalysis, normalizeObservedImageRegions } from "@happyvertical/smrt-ingestion/server";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createHash } from "node:crypto";
@@ -30,6 +31,312 @@ async function requireIngestionMemoryLimit(maximumBytes) {
 	return { memoryLimitBytes: limit };
 }
 //#endregion
+//#region src/workbook-photo-ingestion.ts
+var MODEL = "@happyvertical/smrt-education:WorkbookPhotoIntake";
+var WORKBOOK_PHOTO_HANDLER = "@happyvertical/smrt-education:identify-workbook-photo";
+registerPermissionDefinitions([{
+	slug: "workbookphotointakes.read",
+	collection: "workbookphotointakes",
+	qualifiedName: MODEL,
+	name: "Identify authorized workbook photos"
+}]);
+function assertScope(scope, request) {
+	if (scope.tenantId !== request.tenantId || scope.actorId !== request.actorUserId || scope.confidentialScopeId !== request.learnerId) throw new Error("Photo intake scope mismatch");
+}
+var canonical = (value) => JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v);
+var string = {
+	type: "string",
+	maxLength: 2e3,
+	pattern: "^[^\\u0000-\\u001F\\u007F]*$"
+};
+var schema = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"identification",
+		"confidence",
+		"identityEvidence",
+		"lessonEvidence"
+	],
+	properties: {
+		workbookId: {
+			type: "string",
+			maxLength: 64,
+			description: "Exact existing candidate id. Also copy its workbookKey, title and edition into the required identification.workbook object; this selects existing identity, not a new workbook."
+		},
+		confidence: {
+			type: "string",
+			enum: ["confident", "uncertain"]
+		},
+		identityEvidence: {
+			type: "array",
+			maxItems: 20,
+			items: {
+				...string,
+				minLength: 1
+			}
+		},
+		lessonEvidence: string,
+		identification: {
+			type: "object",
+			additionalProperties: false,
+			required: ["kind", "workState"],
+			properties: {
+				kind: {
+					type: "string",
+					enum: [
+						"lesson",
+						"work",
+						"cover",
+						"reference",
+						"uncertain"
+					]
+				},
+				workState: {
+					type: "string",
+					enum: [
+						"blank",
+						"completed",
+						"unknown"
+					]
+				},
+				notes: string,
+				workbook: {
+					type: "object",
+					additionalProperties: false,
+					required: ["workbookKey", "title"],
+					properties: {
+						workbookKey: string,
+						title: string,
+						edition: string,
+						publisher: string,
+						isbn: string
+					}
+				},
+				activity: {
+					type: "object",
+					additionalProperties: false,
+					required: ["pageKey", "pageLabel"],
+					properties: {
+						pageKey: string,
+						pageLabel: string
+					}
+				}
+			}
+		}
+	}
+};
+function workbookPhotoIntakeHandlers(input) {
+	const bound = async (context, work) => {
+		assertScope(context.scope, input.request);
+		if (!context.policy.requireReview) throw new Error("Photo intake requires review policy");
+		if (!context.principal) return input.workbooks.withExecutor(context.db, work);
+		const tenant = getCurrentTenant();
+		if (!tenant || tenant.tenantId !== input.request.tenantId || tenant.userId !== context.principal.context.userId || context.principal.context.tenantId !== input.request.tenantId) throw new Error("Photo principal tenant mismatch");
+		return withTenant({
+			...tenant,
+			tenantId: input.request.tenantId,
+			userId: input.request.actorUserId,
+			superAdminBypass: false
+		}, () => input.workbooks.withExecutor(context.db, work));
+	};
+	const authorize = async (context) => bound(context, async (service) => {
+		await service.authorizePhotoIntake(input.request);
+		await service.getWorkbookPhotoIntakeByItem({
+			...input.request,
+			itemId: context.itemId
+		});
+	});
+	return [{
+		id: WORKBOOK_PHOTO_HANDLER,
+		version: "1",
+		description: "Classify photos as work, lesson, cover, reference (contents/answer keys), or uncertain. Visible completed learner responses use work even without book/lesson identity: workState=completed; omit workbook/activity/workbookId; lessonEvidence=\"\". Confidence concerns visible material/completion, not missing identity. Printed examples/answer keys alone are not learner completion. Partial/unreadable answers can be unassessed later. Blank/unknown completion never auto-marks. For lesson/cover/reference identity: existing book selects exact workbookId AND copies candidate workbookKey/title/edition into identification.workbook. Unique current title+edition can match retained publisher context; publisher/ISBN need not reappear. identityEvidence quotes ONLY current photos, never candidate context. Conflicts, duplicate candidates or title/page-only matches cannot establish identity. New book needs visible ISBN or publisher/title/edition; workbookKey is a hint, never merge authority. Lesson activity requires printed lesson identifier: pageKey=lesson:<identifier>, pageLabel printed label, lessonEvidence quotes it; page number alone is insufficient. Multiple pages can share a lesson. Cover/reference omit activity. Missing book/lesson alone uses work, not uncertain. Ambiguous material/completion uses uncertain confidence. args: identification, confidence, identityEvidence, lessonEvidence, optional workbookId. identification: kind, workState, optional workbook, activity, notes. workbook: workbookKey,title, optional edition,publisher,isbn. activity: pageKey,pageLabel. Single-line visible quotes only; no controls/placeholders. Omit absent optional fields, never null or extra keys. Classify only; no marks or learning observations.",
+		operation: {
+			model: MODEL,
+			action: "get",
+			version: "1"
+		},
+		capability: {
+			effect: "read",
+			idempotent: true,
+			openWorld: false
+		},
+		argsSchema: schema,
+		resultSchema: schema,
+		resultModels: {},
+		discovery: {
+			mediaTypes: [
+				"image/jpeg",
+				"image/png",
+				"image/webp",
+				"application/pdf"
+			],
+			references: { workbookId: {
+				kind: "candidate",
+				model: "@happyvertical/smrt-education:Workbook"
+			} },
+			candidates: async (query, context, page) => {
+				await authorize(context);
+				const books = await bound(context, (service) => service.listWorkbookPhotoWorkbooks(input.request));
+				const needle = query.toLowerCase();
+				const ordered = [...books].sort((a, b) => Number(b.title.toLowerCase().includes(needle)) - Number(a.title.toLowerCase().includes(needle)) || a.id.localeCompare(b.id));
+				return {
+					items: ordered.slice(0, page.limit).map((book) => ({
+						model: "@happyvertical/smrt-education:Workbook",
+						id: book.id,
+						revision: workbookRevision(book),
+						label: JSON.stringify(book)
+					})),
+					hasMore: ordered.length > page.limit
+				};
+			}
+		},
+		validate: async (args, context) => {
+			await authorize(context);
+			validateWorkbookPhotoIdentification(args.identification);
+			return { ok: true };
+		},
+		preview: async (args, context) => {
+			await authorize(context);
+			return {
+				display: {
+					classification: args.identification,
+					gradeApplied: false
+				},
+				normalizedArgs: args,
+				targetPreconditions: []
+			};
+		},
+		execution: {
+			kind: "database",
+			apply: async (args, context) => {
+				await authorize(context);
+				return args;
+			}
+		}
+	}];
+}
+function workbookRevision(book) {
+	return `workbook:${createHash("sha256").update(canonical(book)).digest("hex")}`;
+}
+function workbookPhotoIntakeTargetResolver(input) {
+	return async ({ db, scope, model, id, revision }) => {
+		assertScope(scope, input.request);
+		if (model !== "@happyvertical/smrt-education:Workbook") throw new Error("Photo target unavailable");
+		const book = (await withTenant({
+			...getCurrentTenant(),
+			tenantId: input.request.tenantId,
+			userId: input.request.actorUserId,
+			superAdminBypass: false
+		}, () => input.workbooks.withExecutor(db, (service) => service.listWorkbookPhotoWorkbooks(input.request)))).find((book2) => book2.id === id);
+		if (!book) throw new Error("Photo target unavailable");
+		const current = workbookRevision(book);
+		if (revision !== void 0 && revision !== current) throw new Error("Photo target changed");
+		return { revision: current };
+	};
+}
+async function receiveWorkbookPhotoIntake(input) {
+	assertScope(input.scope, input.request);
+	await input.workbooks.authorizePhotoIntake(input.request);
+	const receipt = await input.ingestion.receive(input.receive);
+	if (!("itemId" in receipt) || !receipt.itemId) return {
+		receipt,
+		intake: null
+	};
+	return {
+		receipt,
+		intake: await retainWorkbookPhotoReceipt({
+			...input,
+			itemId: receipt.itemId
+		})
+	};
+}
+async function retainWorkbookPhotoReceipt(input) {
+	assertScope(input.scope, input.request);
+	await input.workbooks.authorizePhotoIntake(input.request);
+	const extensions = {
+		"image/png": "png",
+		"image/jpeg": "jpg",
+		"image/webp": "webp",
+		"application/pdf": "pdf"
+	};
+	const originals = (await input.ingestion.getEvidence(input.itemId)).filter((e) => e.parentEvidenceId === null).sort((a, b) => a.partId.localeCompare(b.partId));
+	if (!originals.length || originals.length > 100 || originals.some((e) => !extensions[e.mediaType] || e.byteLength < 1 || e.byteLength > 25 * 1024 * 1024) || originals.reduce((n, e) => n + e.byteLength, 0) > 100 * 1024 * 1024) throw new Error("Unsupported or oversized photo intake");
+	const pages = [];
+	for (const original of originals) {
+		const data = await input.ingestion.readEvidence(input.itemId, original.id);
+		if (data.length !== original.byteLength || createHash("sha256").update(data).digest("hex") !== original.contentHash) throw new Error("Photo receipt integrity mismatch");
+		pages.push({
+			name: `${original.id}.${extensions[original.mediaType]}`,
+			mimeType: original.mediaType,
+			data: Buffer.from(data)
+		});
+	}
+	return input.workbooks.retainWorkbookPhotoIntake({
+		...input.request,
+		itemId: input.itemId,
+		pages
+	});
+}
+async function preserveWorkbookPhotoIdentification(input) {
+	assertScope(input.scope, input.request);
+	const view = await input.workbooks.getWorkbookPhotoIntake(input.request);
+	let snapshot;
+	try {
+		snapshot = await input.ingestion.getCompletedAnalysis(view.itemId);
+	} catch (error) {
+		if (error instanceof ProposalsNotConfiguredError || error instanceof GenerationSnapshotStaleError || error instanceof Error && ["Analysis unavailable", "Intake unavailable"].includes(error.message)) return view;
+		throw error;
+	}
+	if (snapshot.itemId !== view.itemId || snapshot.configuration.stage !== "interpret" || !["completed", "partial"].includes(snapshot.result.status)) return view;
+	const generation = snapshot.result.output.proposals;
+	if (generation?.version !== 1 || !["proposals", "needs_review"].includes(generation.outcome)) return view;
+	const suggestions = generation.suggestions.filter((s) => s.handlerId === WORKBOOK_PHOTO_HANDLER);
+	const offered = generation.offered.find((o) => o.handler.id === WORKBOOK_PHOTO_HANDLER);
+	if (suggestions.length !== 1 || suggestions[0].missingFields.length || !offered || canonical(offered.handler.argsSchema) !== canonical(schema)) return view;
+	const proposal = suggestions[0].args;
+	try {
+		validateWorkbookPhotoIdentification(proposal.identification);
+		if (!["confident", "uncertain"].includes(proposal.confidence) || !Array.isArray(proposal.identityEvidence) || proposal.identityEvidence.length > 20 || proposal.identityEvidence.some((e) => typeof e !== "string" || e.length > 2e3) || typeof proposal.lessonEvidence !== "string" || proposal.lessonEvidence.length > 200) return view;
+	} catch {
+		return view;
+	}
+	return input.workbooks[preservePhotoProposal]({
+		...input.request,
+		requestKey: `analysis:${snapshot.attemptId}`,
+		proposal,
+		allowAutomaticResolution: generation.outcome === "proposals" && generation.suggestions.length === 1 && suggestions[0].alternatives.length === 0 && generation.splits.length === 0,
+		sourceHashes: snapshot.evidence.filter((e) => e.parentEvidenceId === null).sort((a, b) => a.partId.localeCompare(b.partId)).map((e) => e.contentHash),
+		provenance: {
+			attemptId: snapshot.attemptId,
+			revision: snapshot.revision,
+			inputDigest: snapshot.inputDigest,
+			outputDigest: snapshot.outputDigest,
+			evidenceDigest: snapshot.evidenceDigest,
+			configuration: snapshot.configuration,
+			provider: snapshot.result.provider,
+			model: snapshot.result.model
+		}
+	});
+}
+async function processWorkbookPhotoAnalysis(input) {
+	assertScope(input.scope, input.request);
+	if ((await input.workbooks.getWorkbookPhotoIntake(input.request)).itemId !== input.itemId) throw new Error("Photo worker receipt mismatch");
+	const processing = await processEducationAnalysis(input);
+	const intake = await preserveWorkbookPhotoIdentification(input);
+	const capture = intake.status === "resolved" && ["lesson", "work"].includes(intake.identification?.kind ?? "") && intake.identification?.workState === "completed" ? await input.workbooks.captureWorkbookPhotoIntake({
+		...input.request,
+		requestKey: `photo:${intake.itemId}`
+	}) : null;
+	const current = capture ? await input.workbooks.getWorkbookPhotoIntake(input.request) : intake;
+	return {
+		processing,
+		intake: current,
+		capture,
+		assessmentRequired: current.status === "captured"
+	};
+}
+//#endregion
 //#region src/ingestion.ts
 async function queueEducationExtraction(ingestion, itemId, configuration, submissionId) {
 	return ingestion.analyze(itemId, { extraction: configuration }, `education:extract:${configuration.configurationRevision}:${submissionId ?? "identify"}`);
@@ -50,7 +357,10 @@ async function processEducationAnalysis(input) {
 	const generation = await ingestion.prepareGeneration(itemId, result.attemptId);
 	return {
 		kind: "generation_queued",
-		revision: (await ingestion.analyze(itemId, generation, `education:interpret:${result.attemptId}`)).revision
+		revision: (await ingestion.analyze(itemId, {
+			...generation,
+			educationEvidenceGrounding: educationEvidenceGrounding(result)
+		}, `education:interpret:${result.attemptId}`)).revision
 	};
 }
 async function captureEducationIntake(input) {
@@ -86,6 +396,16 @@ async function captureEducationIntake(input) {
 			previousSubmissionId: request.previousSubmissionId
 		}
 	};
+	if (request.workbookActivityId) {
+		if (!(submissions instanceof WorkbookService) || request.kind !== "completed_work") throw new Error("Workbook intake requires WorkbookService completed work");
+		return (await submissions.captureWorkbookWork({
+			...request,
+			activityId: request.workbookActivityId,
+			intakeItemId: request.itemId,
+			requestKey: capture.requestKey,
+			pages
+		})).submission;
+	}
 	if (request.kind === "blank_reference") return submissions.captureBlankReference({
 		...capture,
 		intakeItemId: request.itemId
@@ -228,10 +548,13 @@ function educationIntakeHandlers(input) {
 		await context.assertTarget(SUBMISSION, submissionId);
 		return submission;
 	};
+	const workbook = input.workbookActivityId;
+	if (workbook && !(submissions instanceof WorkbookService)) throw new Error("Workbook handler requires WorkbookService");
+	const vocabulary = input.workbookVocabulary ?? WORKBOOK_MATH_VOCABULARY;
 	handlers.push({
 		id: "@happyvertical/smrt-education:review-submission",
 		version: "1",
-		description: "Suggest marks and feedback for this captured attempt. Only a current authorized guardian decision may apply a grade.",
+		description: workbook ? "Assess visible questions from current captured evidence only. Historical IDs indicate correspondence, never current answers. Prompt is printed task text excluding response; answer is observed learner response only. Printed solved examples/answer keys are not learner answers or learning evidence. Never solve a task and call it the observed response. Matching answers require explicitly observed line endpoints; unreadable connections are unassessed/illegible or missing_context. Missing book/lesson identity never blocks visible work. Use printed number+occurrence/subpart IDs when present. Unnumbered tasks use u:<short printed-task slug>:<occurrence/subpart>, excluding learner answers and solved results. Occurrence identifies visible tasks, never output-array position. Retain exact known IDs on correction; absent/ambiguous correspondence is unassessed/not_present, never guessed or renumbered. Cite original evidence IDs only; no page/rect/coordinate fields, as service retains whole-source grounding. Correct/incorrect/partially_correct use reason none. Unsupported, unanswered, illegible, missing_context and not_present are unassessed, never incorrect, with null points. Judge objectively solvable arithmetic without a printed rubric. Correctness is independent of points: absent evidenced allocation, BOTH points and possiblePoints are null, including incorrect. Never invent weights/rubric or mix null/numeric fields. Only use incorrect points=0 when possiblePoints is known; correct earns that known total. No aggregate score/summary: service computes totals. Concepts are supplied-vocabulary suggestions; no match uses conceptIds [] and still assesses normally. markingCertainty=uncertain requires result=unassessed, reason illegible/missing_context/unsupported/unanswered/not_present, points=null and possiblePoints=null. Never assert correctness with uncertain marking. Mapping certainty is separate. Guardian review is required for authority." : "Suggest marks and feedback for this captured attempt. Only a current authorized guardian decision may apply a grade.",
 		operation: {
 			model: GRADE,
 			action: "create",
@@ -245,22 +568,54 @@ function educationIntakeHandlers(input) {
 		argsSchema: {
 			type: "object",
 			additionalProperties: false,
-			required: [
+			required: workbook ? ["submissionId", "questions"] : [
 				"submissionId",
 				"score",
 				"feedback"
 			],
 			properties: {
 				submissionId: idSchema,
-				score: {
-					type: ["number", "null"],
-					minimum: 0,
-					maximum: 1
-				},
-				feedback: {
-					type: "string",
-					maxLength: 1e4
-				}
+				...workbook ? {
+					answerRegions: { description: "Include advisory answer locations when a current observedRegions catalog clearly matches visible learner responses. Omit unknown or uncertain positions. Shape {version:1,regions:[{questionId,evidenceId,observationId}]}. Reference ONLY exact current evidence observedRegions catalog IDs with matching visible learner response/question; no coordinates or geometry in arguments. Never infer positions from layout, IDs, canonical prompts or expected answers. Omit uncertain/unknown/missing regions. Image-only sources; PDF unsupported. Invalid metadata is dropped independently of valid marking/layout." },
+					layout: {
+						description: "Optional observed presentation only; omit if unknown. Shape: version1, provenance observed; sections in observed order {id,label?,columns1..8,readingOrder? rows|columns,source:{evidenceId:original evidence ID,page:physical source page1based or null unknown}}; placements {questionId,sectionId,row0based,column0based,part?0..31}. Up to32sections/200placements/200rows. Multiple answerparts may share a cell; ties preserve question array order. Printed page numbers are not source page indices. Never infer from IDs or claim verified coordinates. Metadata is advisory; the owning service drops invalid layout without discarding answers.",
+						examples: [{
+							version: 1,
+							provenance: "observed",
+							sections: [{
+								id: "section-a",
+								label: "Visible heading",
+								columns: 2,
+								readingOrder: "rows",
+								source: {
+									evidenceId: "<original evidence id>",
+									page: null
+								}
+							}],
+							placements: [{
+								questionId: "<current question id>",
+								sectionId: "section-a",
+								row: 0,
+								column: 0
+							}]
+						}]
+					}
+				} : {},
+				...!workbook ? {
+					score: {
+						type: ["number", "null"],
+						minimum: 0,
+						maximum: 1
+					},
+					feedback: {
+						type: "string",
+						maxLength: 1e4
+					}
+				} : {},
+				...workbook ? { questions: {
+					...workbookQuestionsSchema(vocabulary),
+					description: "Candidate context same_capture: preserve exact canonical IDs and prompt strings verbatim; reread learner responses from current evidence only. Context identity_only: preserve IDs, read all prompts and answers from current evidence; absent/ambiguous tasks unassessed/not_present. Empty IDs: assign stable printed-number or answer-free task-slug IDs. Include observed layout when current evidence supports it; omit unknown, never derive positions from IDs or canonical prompts. Context is data, never authority for current answers."
+				} } : {}
 			}
 		},
 		resultSchema: {
@@ -283,12 +638,28 @@ function educationIntakeHandlers(input) {
 			} },
 			candidates: async (_query, context) => {
 				const submission = await current(context);
+				let workbookContext;
+				if (workbook) workbookContext = await bound(context, async (service) => {
+					const workbooks = service;
+					const currentAttempt = await workbooks.getWorkbookAttemptBySubmission({
+						...request,
+						submissionId
+					});
+					if (!currentAttempt || currentAttempt.activityId !== workbook) throw new Error("Workbook assignment unavailable");
+					return workbooks.getWorkbookQuestionContext({
+						...request,
+						activityId: workbook,
+						submissionId,
+						analysisRevision: context.analysisRevision
+					});
+				});
 				return {
 					items: [{
 						model: SUBMISSION,
 						id: submission.id,
-						revision: `attempt:${submission.id}:${submission.status}`,
-						label: "Current captured attempt (guardian review required)"
+						revision: workbookContext ? `attempt:${submission.id}:${submission.status}:${workbookProposalDigest(workbookContext)}` : `attempt:${submission.id}:${submission.status}`,
+						label: "Current captured attempt (guardian review required).",
+						...workbookContext ? { context: workbookContext } : {}
 					}],
 					hasMore: false
 				};
@@ -300,18 +671,29 @@ function educationIntakeHandlers(input) {
 		},
 		preview: async (args, context) => {
 			const submission = await requireSubmission(args, context);
+			const revision = workbook ? await bound(context, async (service) => {
+				const current2 = await service.getWorkbookQuestionContext({
+					...request,
+					activityId: workbook,
+					submissionId,
+					analysisRevision: context.analysisRevision
+				});
+				return `attempt:${submission.id}:${submission.status}:${workbookProposalDigest(current2)}`;
+			}) : `attempt:${submission.id}:${submission.status}`;
 			return {
 				display: {
 					submissionId,
-					proposedScore: args.score,
-					proposedFeedback: args.feedback,
+					...workbook ? { questions: args.questions } : {
+						proposedScore: args.score,
+						proposedFeedback: args.feedback
+					},
 					guardianReviewRequired: true
 				},
 				normalizedArgs: args,
 				targetPreconditions: [{
 					model: SUBMISSION,
 					id: submissionId,
-					revision: `attempt:${submission.id}:${submission.status}`
+					revision
 				}]
 			};
 		},
@@ -319,6 +701,33 @@ function educationIntakeHandlers(input) {
 			kind: "database",
 			apply: async (args, context) => {
 				await requireSubmission(args, context);
+				if (workbook) {
+					await bound(context, async (service) => {
+						const workbooks = service;
+						let cursor;
+						let attempt;
+						do {
+							const timeline = await workbooks.getWorkbookTimeline({
+								...request,
+								activityId: workbook,
+								...cursor ? { cursor } : {}
+							});
+							attempt = timeline.attempts.find((entry) => entry.submissionId === submissionId);
+							cursor = timeline.nextCursor ?? void 0;
+						} while (!attempt && cursor);
+						const proposal = attempt?.revisions.find((revision) => revision.kind === "ai" && revision.assessment.provenance.proposalDigest === workbookProposalDigest(args));
+						if (!proposal) throw new Error("Workbook analysis must be preserved before guardian apply");
+						await workbooks.reviewWorkbookAssessment({
+							...request,
+							activityId: workbook,
+							submissionId,
+							revisionId: proposal.id,
+							expectedHeadId: null,
+							requestKey: `ingestion-review:${proposal.id}`
+						});
+					});
+					return { submissionId };
+				}
 				await bound(context, (service) => service.applyReviewedSubmission({
 					...request,
 					submissionId,
@@ -332,9 +741,10 @@ function educationIntakeHandlers(input) {
 	return handlers;
 }
 function educationIntakeTargetResolver(input) {
-	return async ({ db, scope, itemId, model, id, revision }) => {
+	return async ({ db, scope, itemId, analysisRevision, model, id, revision }) => {
 		const { request, submissions } = input;
 		if (scope.tenantId !== request.tenantId || scope.actorId !== request.actorUserId) throw new Error("Education intake scope mismatch");
+		await db.query("UPDATE learners SET id=id WHERE id=? AND tenant_id=?", request.learnerId, request.tenantId);
 		await db.query("UPDATE enrollments SET id=id WHERE id=? AND tenant_id=?", request.enrollmentId, request.tenantId);
 		const current = await withTenant({
 			...getCurrentTenant(),
@@ -352,13 +762,412 @@ function educationIntakeTargetResolver(input) {
 				submissionId: id
 			});
 			if (submission.intakeItemId !== itemId || submission.kind !== "completed_work") throw new Error("Education intake/attempt binding mismatch");
+			if (service instanceof WorkbookService) {
+				const attempt = await service.getWorkbookAttemptBySubmission({
+					...request,
+					submissionId: id
+				});
+				if (attempt) {
+					const context = await service.getWorkbookQuestionContext({
+						...request,
+						activityId: attempt.activityId,
+						submissionId: id,
+						analysisRevision
+					});
+					return `attempt:${submission.id}:${submission.status}:${workbookProposalDigest(context)}`;
+				}
+			}
 			return `attempt:${submission.id}:${submission.status}`;
 		}));
 		if (revision !== void 0 && revision !== current) throw new Error("Education target changed");
 		return { revision: current };
 	};
 }
+function workbookProposalDigest(value) {
+	const canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)).map(([k, x]) => [k, canonical(x)])) : v;
+	return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+function workbookQuestionsSchema(vocabulary) {
+	return {
+		type: "array",
+		minItems: 1,
+		maxItems: 200,
+		items: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"id",
+				"prompt",
+				"answer",
+				"result",
+				"reason",
+				"feedback",
+				"points",
+				"possiblePoints",
+				"anchors",
+				"conceptIds",
+				"markingCertainty",
+				"mappingCertainty",
+				"evidenceLimitations"
+			],
+			oneOf: [{ properties: {
+				result: { enum: [
+					"correct",
+					"incorrect",
+					"partially_correct"
+				] },
+				markingCertainty: { enum: ["clear", "unknown"] },
+				reason: { const: "none" }
+			} }, { properties: {
+				result: { const: "unassessed" },
+				reason: { enum: [
+					"unanswered",
+					"illegible",
+					"missing_context",
+					"unsupported",
+					"not_present"
+				] },
+				points: { type: "null" },
+				possiblePoints: { type: "null" }
+			} }],
+			properties: {
+				id: {
+					type: "string",
+					minLength: 1,
+					maxLength: 200
+				},
+				prompt: {
+					type: "string",
+					maxLength: 1e4
+				},
+				answer: {
+					type: "string",
+					maxLength: 1e4
+				},
+				result: {
+					type: "string",
+					enum: [
+						"correct",
+						"incorrect",
+						"partially_correct",
+						"unassessed"
+					]
+				},
+				reason: {
+					type: "string",
+					enum: [
+						"none",
+						"unanswered",
+						"illegible",
+						"missing_context",
+						"unsupported",
+						"not_present"
+					]
+				},
+				feedback: {
+					type: "string",
+					maxLength: 1e4
+				},
+				points: {
+					type: ["number", "null"],
+					minimum: 0
+				},
+				possiblePoints: {
+					type: ["number", "null"],
+					minimum: 0
+				},
+				markingCertainty: {
+					type: "string",
+					enum: [
+						"clear",
+						"uncertain",
+						"unknown"
+					]
+				},
+				mappingCertainty: {
+					type: "string",
+					enum: [
+						"clear",
+						"uncertain",
+						"unknown"
+					]
+				},
+				evidenceLimitations: {
+					type: "array",
+					maxItems: 20,
+					items: {
+						type: "string",
+						maxLength: 500
+					}
+				},
+				conceptIds: {
+					type: "array",
+					maxItems: 10,
+					items: {
+						type: "string",
+						enum: vocabulary.concepts.map((c) => c.id)
+					}
+				},
+				anchors: {
+					type: "array",
+					minItems: 1,
+					maxItems: 20,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						required: ["evidenceId"],
+						properties: { evidenceId: idSchema }
+					}
+				}
+			}
+		}
+	};
+}
+function educationEvidenceGrounding(snapshot) {
+	const sources = (Array.isArray(snapshot.result.output?.results) ? snapshot.result.output.results : []).slice(0, 100).flatMap((value) => {
+		if (!value || typeof value !== "object") return [];
+		const result = value;
+		const evidence = (snapshot.evidence ?? []).find((e) => e.id === result.evidence?.id && e.contentHash === result.evidence?.contentHash);
+		if (!evidence) return [];
+		const pages = Array.isArray(result.capabilities) && result.capabilities.some((c) => c.location === "page") && Array.isArray(result.segments) ? [...new Set(result.segments.flatMap((segment) => segment.location?.kind === "page" && Number.isSafeInteger(segment.location.page) && (segment.location.page ?? 0) > 0 ? [segment.location.page] : []))].slice(0, 1e3) : [];
+		const catalogs = typeof evidence.mediaType === "string" && evidence.mediaType.startsWith("image/") && Array.isArray(result.segments) ? result.segments.filter((s) => s.location?.kind === "source").map((s) => normalizeObservedImageRegions(s.observedRegions)).filter((s) => s !== void 0) : [];
+		return [{
+			evidenceId: evidence.id,
+			sha256: evidence.contentHash,
+			pages,
+			...catalogs.length === 1 ? { observedRegions: catalogs[0] } : {}
+		}];
+	});
+	return {
+		version: 1,
+		extractionAttemptId: snapshot.attemptId,
+		sources
+	};
+}
+async function preserveWorkbookIntakeAnalysis(input) {
+	const { ingestion, workbooks, request, activityId, submissionId } = input;
+	const attempt = await workbooks.getWorkbookAttemptBySubmission({
+		...request,
+		submissionId
+	});
+	if (!attempt || attempt.activityId !== activityId || !attempt.submission.intakeItemId) throw new Error("Workbook intake binding unavailable");
+	const itemId = attempt.submission.intakeItemId;
+	const state = await workbooks.getWorkbookPreservationState({
+		...request,
+		activityId,
+		submissionId
+	});
+	const latestRetained = state.retainedAnalyses.at(-1);
+	const legacyRetained = state.retainedAnalyses.every((entry) => entry.analysisRevision === null) ? latestRetained : void 0;
+	let currentRevision;
+	try {
+		currentRevision = (await ingestion.getItem(itemId)).analysisRevision;
+	} catch (error) {
+		if (error instanceof Error && error.message === "Intake unavailable") return latestRetained ? {
+			kind: "retained",
+			revisionId: latestRetained.assessmentRevisionId
+		} : { kind: "unavailable" };
+		throw error;
+	}
+	const exact = state.retainedAnalyses.find((entry) => entry.analysisRevision === currentRevision);
+	if (exact) return {
+		kind: "retained",
+		revisionId: exact.assessmentRevisionId
+	};
+	let snapshot;
+	try {
+		snapshot = await ingestion.getCompletedAnalysis(itemId);
+	} catch (error) {
+		if (error instanceof ProposalsNotConfiguredError) return legacyRetained ? {
+			kind: "retained",
+			revisionId: legacyRetained.assessmentRevisionId
+		} : { kind: "unavailable" };
+		if (error instanceof GenerationSnapshotStaleError) return legacyRetained ? {
+			kind: "retained",
+			revisionId: legacyRetained.assessmentRevisionId
+		} : {
+			kind: "needs_review",
+			reason: "stale_analysis"
+		};
+		if (error instanceof Error && error.message === "Intake unavailable") return latestRetained ? {
+			kind: "retained",
+			revisionId: latestRetained.assessmentRevisionId
+		} : { kind: "unavailable" };
+		if (error instanceof Error && error.message === "Analysis unavailable") return latestRetained ? {
+			kind: "retained",
+			revisionId: latestRetained.assessmentRevisionId
+		} : { kind: "pending" };
+		throw error;
+	}
+	if (snapshot.configuration.stage !== "interpret" || !["completed", "partial"].includes(snapshot.result.status)) return { kind: "pending" };
+	const importedAttempt = state.retainedAnalyses.find((entry) => entry.analysisAttemptId === snapshot.attemptId);
+	if (importedAttempt) return {
+		kind: "retained",
+		revisionId: importedAttempt.assessmentRevisionId
+	};
+	const sources = await workbooks.getWorkbookSourceAnchors({
+		...request,
+		activityId,
+		submissionId
+	});
+	const originals = snapshot.evidence.filter((e) => e.parentEvidenceId === null).sort((a, b) => a.partId.localeCompare(b.partId));
+	if (originals.length !== sources.length || originals.some((e, i) => e.contentHash !== sources[i].sha256)) throw new Error("Workbook retained source mismatch");
+	let assessment;
+	try {
+		const generation = snapshot.result.output.proposals;
+		if (!generation || generation.version !== 1 || !Array.isArray(generation.suggestions)) throw new WorkbookAssessmentValidationError("Malformed workbook generation");
+		if (!["proposals", "needs_review"].includes(generation.outcome)) return {
+			kind: "needs_review",
+			reason: generation.outcome === "ambiguous" ? "ambiguous_proposal" : "invalid_assessment"
+		};
+		const suggestions = generation.suggestions.filter((s) => s.handlerId === "@happyvertical/smrt-education:review-submission");
+		if (suggestions.length !== 1) throw new WorkbookAssessmentValidationError("Expected one workbook proposal", "ambiguous_proposal");
+		const suggestion = suggestions[0];
+		if (suggestion.args.submissionId !== submissionId || !Array.isArray(suggestion.args.questions) || suggestion.missingFields.length) throw new WorkbookAssessmentValidationError("Incomplete workbook question proposal");
+		const questionSchema = generation.offered.find((entry) => entry.handler.id === suggestion.handlerId)?.handler.argsSchema.properties?.questions;
+		if (!questionSchema) throw new WorkbookAssessmentValidationError("Generation did not use workbook question contract");
+		const curated = input.workbookVocabulary ?? WORKBOOK_MATH_VOCABULARY;
+		if (JSON.stringify(questionSchema.items.properties.conceptIds.items.enum) !== JSON.stringify(curated.concepts.map((c) => c.id))) throw new WorkbookAssessmentValidationError("Unsupported workbook vocabulary");
+		const grounding = snapshot.configuration.educationEvidenceGrounding;
+		const trustedGrounding = grounding?.version === 1 && grounding.extractionAttemptId === generation.source?.attemptId ? grounding : void 0;
+		const questions = suggestion.args.questions.map((value) => {
+			if (!value || typeof value !== "object" || Array.isArray(value)) throw new WorkbookAssessmentValidationError("Invalid workbook question");
+			const q = value;
+			if (!Array.isArray(q.anchors)) throw new WorkbookAssessmentValidationError("Missing workbook source anchors", "ungrounded_source");
+			const limitations = new Set(Array.isArray(q.evidenceLimitations) ? q.evidenceLimitations : []);
+			const anchors = q.anchors.map((value2) => {
+				const anchor = value2;
+				const index = originals.findIndex((e) => e.id === anchor?.evidenceId);
+				if (index < 0) throw new WorkbookAssessmentValidationError("Question must cite a captured original", "ungrounded_source");
+				const page = originals[index].mediaType?.startsWith("image/") ? 1 : null;
+				const level = "source";
+				limitations.add("Source-level evidence only; no verified question page or region was supplied by extraction.");
+				return {
+					assetId: sources[index].assetId,
+					sha256: sources[index].sha256,
+					page,
+					rect: [
+						0,
+						0,
+						1,
+						1
+					],
+					grounding: level,
+					...trustedGrounding?.extractionAttemptId ? { extractionAttemptId: trustedGrounding.extractionAttemptId } : {}
+				};
+			});
+			return {
+				...q,
+				anchors,
+				evidenceLimitations: [...limitations]
+			};
+		});
+		let observedLayout = suggestion.args.layout;
+		if (observedLayout && typeof observedLayout === "object" && !Array.isArray(observedLayout)) {
+			const candidate = observedLayout;
+			if (Array.isArray(candidate.sections) && candidate.sections.length <= 32) observedLayout = {
+				...candidate,
+				sections: candidate.sections.map((section) => {
+					if (!section || typeof section !== "object" || Array.isArray(section)) return section;
+					const row = section;
+					const source = row.source;
+					const index = originals.findIndex((e) => e.id === source?.evidenceId);
+					return {
+						...row,
+						source: {
+							assetId: index >= 0 ? sources[index].assetId : "",
+							page: source?.page
+						}
+					};
+				})
+			};
+		}
+		let mappedRegions = suggestion.args.answerRegions;
+		if (mappedRegions && typeof mappedRegions === "object" && !Array.isArray(mappedRegions)) {
+			const proposed = mappedRegions;
+			if (proposed.version === 1 && Array.isArray(proposed.regions)) mappedRegions = {
+				version: 1,
+				provenance: "observed",
+				coordinateSpace: "display-oriented",
+				regions: proposed.regions.map((entry) => {
+					if (!entry || typeof entry !== "object" || Array.isArray(entry)) return {};
+					const r = entry;
+					if (Object.keys(r).some((key) => ![
+						"questionId",
+						"evidenceId",
+						"observationId"
+					].includes(key))) return {};
+					const index = originals.findIndex((e) => e.id === r.evidenceId && typeof e.mediaType === "string" && e.mediaType.startsWith("image/"));
+					const catalogSource = trustedGrounding?.sources?.find((source) => source.evidenceId === r.evidenceId && source.sha256 === originals[index]?.contentHash);
+					const observed = normalizeObservedImageRegions(catalogSource?.observedRegions)?.regions.find((region) => region.id === r.observationId);
+					return {
+						questionId: r.questionId,
+						source: {
+							assetId: index >= 0 ? sources[index].assetId : "",
+							page: 1
+						},
+						observationId: r.observationId,
+						rect: observed?.rect
+					};
+				})
+			};
+		}
+		assessment = {
+			version: 1,
+			feedback: "",
+			questions,
+			...normalizeWorkbookObservedLayout(observedLayout, questions, sources),
+			...normalizeWorkbookAnswerRegions(mappedRegions, questions, sources),
+			vocabulary: structuredClone(curated),
+			provenance: {
+				provider: generation.provenance.generative.provider,
+				model: generation.provenance.generativeResponseModel ?? generation.provenance.generative.model,
+				configurationVersion: generation.provenance.configurationVersion,
+				rubricVersion: generation.provenance.promptVersion,
+				inputHash: snapshot.inputDigest,
+				analysisId: snapshot.attemptId,
+				analysisRevision: snapshot.revision,
+				proposalDigest: workbookProposalDigest(suggestion.args),
+				providerVersion: generation.provenance.generative.version,
+				sourceAnalysis: generation.source,
+				catalogDigest: generation.provenance.catalogDigest,
+				policyVersions: generation.provenance.policyVersions
+			}
+		};
+		validateWorkbookAssessment(assessment);
+		assessment.aggregate = aggregateWorkbookQuestions(assessment.questions);
+		assessment.feedback = workbookAggregateFeedback(assessment.aggregate);
+	} catch (error) {
+		if (error instanceof WorkbookAssessmentValidationError) return {
+			kind: "needs_review",
+			reason: error.reason
+		};
+		if (error instanceof TypeError) return {
+			kind: "needs_review",
+			reason: "invalid_assessment"
+		};
+		throw error;
+	}
+	try {
+		return {
+			kind: "preserved",
+			revisionId: (await workbooks.recordWorkbookAnalysis({
+				...request,
+				activityId,
+				submissionId,
+				requestKey: `ingestion:${snapshot.attemptId}`,
+				assessment
+			})).id
+		};
+	} catch (error) {
+		if (error instanceof WorkbookAssessmentValidationError) return {
+			kind: "needs_review",
+			reason: error.reason
+		};
+		throw error;
+	}
+}
 //#endregion
-export { captureEducationIntake, educationIntakeHandlers, educationIntakeTargetResolver, processEducationAnalysis, queueEducationExtraction, requireIngestionMemoryLimit };
+export { WORKBOOK_PHOTO_HANDLER, captureEducationIntake, educationIntakeHandlers, educationIntakeTargetResolver, preserveWorkbookIntakeAnalysis, preserveWorkbookPhotoIdentification, processEducationAnalysis, processWorkbookPhotoAnalysis, queueEducationExtraction, receiveWorkbookPhotoIntake, requireIngestionMemoryLimit, retainWorkbookPhotoReceipt, workbookPhotoIntakeHandlers, workbookPhotoIntakeTargetResolver };
 
 //# sourceMappingURL=ingestion.js.map